diff --git a/ChangeLog b/ChangeLog index 773ac10c18..1149ee23d1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2004-01-28 Ronald Bultje + + * docs/pwg/advanced_types.xml: + Add notes on creating your own types. + * docs/pwg/building_boiler.xml: + * docs/pwg/building_pads.xml: + * docs/pwg/building_state.xml: + Add some stuff about how to retrieve values from structures, how + that relates to types and change layout slightly again to be almost + perfect. + 2004-01-28 Ronald Bultje * docs/pwg/advanced_dparams.xml: diff --git a/docs/pwg/advanced-types.xml b/docs/pwg/advanced-types.xml index c95883cab6..075dc1f3ab 100644 --- a/docs/pwg/advanced-types.xml +++ b/docs/pwg/advanced-types.xml @@ -59,22 +59,25 @@ Building a Simple Format for Testing + If you need a new format that has not yet been defined in our , you will want to have some general + guidelines on mimetype naming, properties and such. A mimetype would + ideally be one defined by IANA; else, it should be in the form + type/x-name, where type is the sort of data this mimetype handles (audio, + video, ...) and name should be something specific for this specific type. + Audio and video mimetypes should try to support the general audio/video + properties (see the list), and can use their own properties, too. To get + an idea of what properties we think are useful, see (again) the list. - - - - - - A Simple Mime Type - - - - - - - - Type Properties + Take your time to find the right set of properties for your type. There + is no reason to hurry. Also, experimenting with this is generally a good + idea. Experience learns that theoretically thought-out types are good, + but they still need practical use to assure that they serve their needs. + Make sure that your property names do not clash with similar properties + used in other types. If they match, make sure they mean the same thing; + properties with different types but the same names are + not allowed. @@ -83,6 +86,7 @@ Typefind Functions and Autoplugging + WRITEME diff --git a/docs/pwg/building-boiler.xml b/docs/pwg/building-boiler.xml index ab22406283..5248045ab9 100644 --- a/docs/pwg/building-boiler.xml +++ b/docs/pwg/building-boiler.xml @@ -313,6 +313,40 @@ gst_my_filter_base_init (GstMyFilterClass *klass) [..] } + + The last argument in a template is its type + or list of supported types. In this example, we use 'ANY', which means + that this element will accept all input. In real-life situations, you + would set a mimetype and optionally a set of properties to make sure + that only supported input will come in. This representation should be + a string that starts with a mimetype, then a set of comma-separates + properties with their supported values. In case of an audio filter that + supports raw integer 16-bit audio, mono or stereo at any samplerate, the + correct template would look like this: + + +static GstStaticPadTemplate sink_factory = +GST_STATIC_PAD_TEMPLATE ( + "sink", + GST_PAD_SINK, + GST_PAD_ALWAYS, + GST_STATIC_CAPS ( + "audio/x-raw-int, " + "width = (int) 16, " + "depth = (int) 16, " + "endianness = (int) BYTE_ORDER, " + "channels = (int) { 1, 2 }, " + "rate = (int) [ 8000, 96000 ]" + ) +); + + + Values surrounded by {} are lists, values surrounded by [] are ranges. + Multiple sets of types are supported too, and should be separated by + a semicolon (;). Later, in the chapter on pads, we will + see how to use types to know the exact format of a stream: + . + diff --git a/docs/pwg/building-pads.xml b/docs/pwg/building-pads.xml index f80d87ec4f..1148f9a064 100644 --- a/docs/pwg/building-pads.xml +++ b/docs/pwg/building-pads.xml @@ -55,6 +55,9 @@ gst_my_filter_init (GstMyFilter *filter) [..] } + + + The link function The _link () is called during caps negotiation. This is the process where the linked pads decide on the streamtype that will @@ -108,6 +111,16 @@ gst_my_filter_link (GstPad *pad, return ret; } + + In here, we check the mimetype of the provided caps. Normally, you don't + need to do that in your own plugin/element, because the core does that + for you. We simply use it to show how to retrieve the mimetype from a + provided set of caps. Types are stored in GstStructure + internally. A GstCaps is nothing more than a small + wrapper for 0 or more structures/types. From the structure, you can also + retrieve properties, as is shown above with the function + gst_structure_get_int (). + If your _link () function does not need to perform any specific operation (i.e. it will only forward caps), you can set it @@ -115,6 +128,10 @@ gst_my_filter_link (GstPad *pad, function implementation provided by the core. It is useful for elements such as identity. + + + + The getcaps function The _getcaps () funtion is used to request the list of supported formats and properties from the element. In some cases, this @@ -158,6 +175,10 @@ gst_my_filter_getcaps (GstPad *pad) return caps; } + + + + Explicit caps Obviously, many elements will not need this complex mechanism, because they are much simpler than that. They only support one format, or their format @@ -191,5 +212,6 @@ gst_my_filter_somefunction (GstMyFilter *filter) [..] } + diff --git a/docs/pwg/building-state.xml b/docs/pwg/building-state.xml index 1d1e71ee2b..f8d6253861 100644 --- a/docs/pwg/building-state.xml +++ b/docs/pwg/building-state.xml @@ -53,8 +53,8 @@ as possible and would ideally cause no delay at all. The same goes for the reverse transition (GST_STATE_PLAYING_TO_PAUSED). - - + + Mangaging filter state @@ -99,4 +99,5 @@ gst_my_filter_change_state (GstElement *element) return GST_STATE_SUCCESS; } +