-<chapter id="cha-pads">
- <title>Pads</title>
+<chapter id="chapter-pads" xreflabel="Pads and capabilities">
+ <title>Pads and capabilities</title>
<para>
- As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
- interface to the outside world.
- </para>
- <para>
- The specific type of media that the element can handle will be exposed by the pads.
- The description of this media type is done with capabilities(see
- <xref linkend="sec-caps"/>)
- </para>
-
- <para>
- Pads are either source or sink pads. The terminology is defined from the
- view of the element itself: elements accept data on their sink pads, and
- send data out on their source pads. Sink pads are drawn on the left,
- while source pads are drawn on the right of an element. In general,
- data flows from left to right in the graph.<footnote>
- <para>
- In reality, there is no objection to data flowing from a
- source pad to the sink pad of an element upstream. Data will, however,
- always flow from a source pad of one element to the sink pad of
- another.
- </para></footnote>
+ As we have seen in <xref linkend="chapter-elements"/>, the pads are
+ the element's interface to the outside world. Data streams from one
+ element's source pad to another element's sink pad. The specific
+ type of media that the element can handle will be exposed by the
+ pad's capabilities. We will talk more on capabilities later in this
+ chapter (see <xref linkend="section-caps"/>).
</para>
- <sect1 id="sec-pads-get">
- <title>Getting pads from an element</title>
- <para>
- Once you have created an element, you can get one of its pads with:
+ <sect1 id="section-pads">
+ <title>Pads</title>
+ <para>
+ A pad type is defined by two properties: its direction and its
+ availability. As we've mentioned before, &GStreamer; defines two
+ pad directions: source pads and sink pads. This terminology is
+ defined from the view of within the element: elements receive data
+ on their sink pads and generate data on their source pads.
+ Schematically, sink pads are drawn on the left side of an element,
+ whereas source pads are drawn on the right side of an element. In
+ such graphs, data flows from left to right.
+ <footnote>
+ <para>
+ In reality, there is no objection to data flowing from a
+ source pad to the sink pad of an element upstream (to the
+ left of this element in drawings). Data will, however, always
+ flow from a source pad of one element to the sink pad of
+ another.
+ </para>
+ </footnote>
</para>
- <programlisting>
- GstPad *srcpad;
- ...
- srcpad = gst_element_get_pad (element, "src");
- ...
- </programlisting>
- <para>
- This function will get the pad named "src" from the given element.
- </para>
- <para>
- Alternatively, you can request a GList of pads from the element. The
- following code example will print the names of all the pads of an
- element.
+
+ <para>
+ Pad directions are very simple compared to pad availability. A pad
+ can have any of three availabilities: always, sometimes and on
+ request. The meaning of those three types is exactly as it says:
+ always pads always exist, sometimes pad exist only in certain
+ cases (and can disappear randomly), and on-request pads appear
+ only if explicitely requested by applications.
</para>
- <programlisting>
- GList *pads;
- ...
- pads = gst_element_get_pad_list (element);
- while (pads) {
- GstPad *pad = GST_PAD (pads->data);
-
- g_print ("pad name %s\n", gst_pad_get_name (pad));
-
- pads = g_list_next (pads);
- }
- ...
- </programlisting>
- <sect2 id="sec-pads-functions">
- <title>Useful pad functions</title>
- <para>
- You can get the name of a pad with gst_pad_get_name () and set its name with
- get_pad_set_name().
- </para>
- <para>
- gst_pad_get_direction (GstPad *pad) can be used to query if the pad
- is a sink or a source pad. Remember that a source pad is a pad that
- can output data and a sink pad is one that accepts data.
- </para>
- <para>
- You can get the parent of the pad, this is the element that this pad belongs to,
- with get_pad_get_parent(GstPad *pad). This function will return a pointer to a
- GstElement.
- </para>
- </sect2>
- </sect1>
- <sect1 id="sec-pads-type">
- <title>Types of pads</title>
-
- <sect2 id="sec-pads-dynamic">
- <title>Dynamic pads</title>
- <para>
+ <sect2 id="section-pads-dynamic">
+ <title>Dynamic (or sometimes) pads</title>
+ <para>
Some elements might not have all of their pads when the element is
- created. This
- can happen, for example, with an MPEG system demultiplexer. The
- demultiplexer will create its pads at runtime when it detects the
- different elementary streams in the MPEG system stream.
- </para>
- <para>
- Running <application>gst-inspect mpegdemux</application> will show that
- the element has only one pad: a sink pad called 'sink'. The other pads are
- "dormant". You can see this in the pad template because there is
- an 'Exists: Sometimes'
- property. Depending on the type of MPEG file you play, the pads will
- be created. We
- will see that this is very important when you are going to create dynamic
- pipelines later on in this manual.
+ created. This can happen, for example, with an Ogg demuxer element.
+ The element will read the Ogg stream and create dynamic pads for
+ each contained elementary stream (vorbis, theora) when it detects
+ such a stream in the Ogg stream. Likewise, it will delete the pad
+ when the stream ends. This principle is very useful for demuxer
+ elements, for example.
</para>
<para>
- You can attach a signal to an element to inform you when the element has created
- a new pad from one of its padtemplates. The following piece of code is an example
- of how to do this:
+ Running <application>gst-inspect oggdemux</application> will show
+ that the element has only one pad: a sink pad called 'sink'. The
+ other pads are <quote>dormant</quote>. You can see this in the pad
+ template because there is an <quote>Exists: Sometimes</quote>
+ property. Depending on the type of Ogg file you play, the pads will
+ be created. We will see that this is very important when you are
+ going to create dynamic pipelines. You can attach a signal handler
+ to an element to inform you when the element has created a new pad
+ from one of its <quote>sometimes</quote> pad templates. The
+ following piece of code is an example of how to do this:
</para>
- <programlisting>
+ <programlisting><!-- example-begin pad.c a -->
+#include <gst/gst.h>
+
static void
-pad_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline)
+cb_new_pad (GstElement *element,
+ GstPad *pad,
+ gpointer data)
{
- g_print("***** a new pad %s was created\n", gst_pad_get_name(pad));
+ gchar *name;
- gst_element_set_state (pipeline, GST_STATE_PAUSED);
+ name = gst_pad_get_name (pad);
+ g_print ("A new pad %s was created\n", name);
+ g_free (name);
- if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) {
- // set up an AC3 decoder pipeline
- ...
- // link pad to the AC3 decoder pipeline
- ...
- }
- gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY);
+ /* here, you would setup a new pad link for the newly created pad */
+<!-- example-end pad.c a -->[..]
+<!-- example-begin pad.c b -->
}
int
-main(int argc, char *argv[])
+main (int argc,
+ char *argv[])
{
- GstElement *pipeline;
- GstElement *mpeg2parser;
+ GstElement *pipeline, *source, *demux;
+ GMainLoop *loop;
+
+ /* init */
+ gst_init (&argc, &argv);
- // create pipeline and do something useful
- ...
-
- mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux");
- g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline);
- ...
+ /* create elements */
+ pipeline = gst_pipeline_new ("my_pipeline");
+ source = gst_element_factory_make ("filesrc", "source");
+ g_object_set (source, "location", argv[1], NULL);
+ demux = gst_element_factory_make ("oggdemux", "demuxer");
- // start the pipeline
+ /* you would normally check that the elements were created properly */
+
+ /* put together a pipeline */
+ gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
+ gst_element_link_pads (source, "src", demux, "sink");
+
+ /* listen for newly created pads */
+ g_signal_connect (demux, "pad-added", G_CALLBACK (cb_new_pad), NULL);
+
+ /* start the pipeline */
gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
- ...
+ loop = g_main_loop_new (NULL, FALSE);
+ g_main_loop_run (loop);
+<!--example-end pad.c b -->
+[..]<!-- example-begin pad.c c --><!--
+ return 0;
+--><!-- example-end pad.c c -->
+<!-- example-begin pad.c d -->
}
- </programlisting>
- <note>
- <para>
- A pipeline cannot be changed in the PLAYING state.
- </para>
- </note>
+ <!-- example-end pad.c d --></programlisting>
</sect2>
- <sect2 id="sec-pads-request">
+
+ <sect2 id="section-pads-request">
<title>Request pads</title>
<para>
An element can also have request pads. These pads are not created
automatically but are only created on demand. This is very useful
- for multiplexers, aggregators and tee elements.
+ for multiplexers, aggregators and tee elements. Aggregators are
+ elements that merge the content of several input streams together
+ into one output stream. Tee elements are the reverse: they are
+ elements that have one input stream and copy this stream to each
+ of their output pads, which are created on request. Whenever an
+ application needs another copy of the stream, it can simply request
+ a new output pad from the tee element.
</para>
<para>
- The tee element, for example, has one input pad and a request padtemplate for the
- output pads. Whenever an element wants to get an output pad from the tee element, it
- has to request the pad.
- </para>
- <para>
- The following piece of code can be used to get a pad from the tee element. After
- the pad has been requested, it can be used to link another element to it.
- </para>
+ The following piece of code shows how you can request a new output
+ pad from a <quote>tee</quote> element:
+ </para>
<programlisting>
- ...
- GstPad *pad;
- ...
- element = gst_element_factory_make ("tee", "element");
+static void
+some_function (GstElement *tee)
+{
+ GstPad * pad;
+ gchar *name;
+
+ pad = gst_element_get_request_pad (tee, "src%d");
+ name = gst_pad_get_name (pad);
+ g_print ("A new pad %s was created\n", name);
+ g_free (name);
+
+ /* here, you would link the pad */
+[..]
- pad = gst_element_get_request_pad (element, "src%d");
- g_print ("new pad %s\n", gst_pad_get_name (pad));
- ...
+ /* and, after doing that, free our reference */
+ gst_object_unref (GST_OBJECT (pad));
+}
</programlisting>
<para>
- The gst_element_get_request_pad method can be used to get a pad
- from the element based on the name_template of the padtemplate.
- </para>
- <para>
- It is also possible to request a pad that is compatible with another
- pad template. This is very useful if you want to link an element
- to a multiplexer element and you need to request a pad that is
- compatible. The gst_element_get_compatible_pad is used to request
- a compatible pad, as is shown in the next example.
+ The <function>gst_element_get_request_pad ()</function> method
+ can be used to get a pad from the element based on the name of
+ the pad template. It is also possible to request a pad that is
+ compatible with another pad template. This is very useful if
+ you want to link an element to a multiplexer element and you
+ need to request a pad that is compatible. The method
+ <function>gst_element_get_compatible_pad ()</function> can be
+ used to request a compatible pad, as shown in the next example.
+ It will request a compatible pad from an Ogg multiplexer from
+ any input.
</para>
<programlisting>
- ...
- GstPadTemplate *templ;
+static void
+link_to_multiplexer (GstPad *tolink_pad,
+ GstElement *mux)
+{
GstPad *pad;
- ...
- element = gst_element_factory_make ("tee", "element");
- mad = gst_element_factory_make ("mad", "mad");
+ gchar *srcname, *sinkname;
- templ = gst_element_get_pad_template_by_name (mad, "sink");
+ srcname = gst_pad_get_name (tolink_pad);
+ pad = gst_element_get_compatible_pad (mux, tolink_pad);
+ gst_pad_link (tolinkpad, pad);
+ sinkname = gst_pad_get_name (pad);
+ gst_object_unref (GST_OBJECT (pad));
- pad = gst_element_get_compatible_pad (element, templ);
- g_print ("new pad %s\n", gst_pad_get_name (pad));
- ...
+ g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
+ g_free (sinkname);
+ g_free (srcname);
+}
</programlisting>
</sect2>
-
</sect1>
- <sect1 id="sec-caps">
+ <sect1 id="section-caps">
<title>Capabilities of a pad</title>
<para>
- Since the pads play a very important role in how the element is viewed by the
- outside world, a mechanism is implemented to describe the data that can
- flow through the pad by using capabilities.
+ Since the pads play a very important role in how the element is
+ viewed by the outside world, a mechanism is implemented to describe
+ the data that can flow or currently flows through the pad by using
+ capabilities. Here, we will briefly describe what capabilities are
+ and how to use them, enough to get an understanding of the concept.
+ For an in-depth look into capabilities and a list of all capabilities
+ defined in &GStreamer;, see the <ulink type="http"
+ url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
+ Writers Guide</ulink>.
</para>
- <para>
- We will briefly describe what capabilities are, enough for you to get a basic understanding
- of the concepts. You will find more information on how to create capabilities in the
- Plugin Writer's Guide.
+ <para>
+ Capabilities are attached to pad templates and to pads. For pad
+ templates, it will describe the types of media that may stream
+ over a pad created from this template. For pads, it can either
+ be a list of possible caps (usually a copy of the pad template's
+ capabilities), in which case the pad is not yet negotiated, or it
+ is the type of media that currently streams over this pad, in
+ which case the pad has been negotiated already.
</para>
- <sect2 id="sec-pads-caps">
- <title>What are capabilities ?</title>
- <para>
- Capabilities are attached to a pad in order to describe
- what type of media the pad can handle.
- </para>
- <para>
- Capabilities is shorthand for "capability chain". A capability chain
- is a chain of one capability or more.
- </para>
+ <sect2 id="section-caps-structure">
+ <title>Dissecting capabilities</title>
<para>
- The basic entity is a capability, and is defined by a name, a MIME
- type and a set of properties. A capability can be chained to
- another capability, which is why we commonly refer to a chain of
- capability entities as "capabilities".<footnote>
- <para>
- It is important to understand that the term "capabilities" refers
- to a chain of one capability or more. This will be clearer when
- you see the structure definition of a <classname>GstCaps</classname>
- element.
- </para></footnote>
+ A pad's capabilities are described in a <classname>GstCaps</classname>
+ object. Internally, a <ulink type="http"
+ url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
+ will contain one or more <ulink type="http"
+ url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
+ that will describe one media type. A negotiated pad will have
+ capabilities set that contain exactly <emphasis>one</emphasis>
+ structure. Also, this structure will contain only
+ <emphasis>fixed</emphasis> values. These constraints are not
+ true for unnegotiated pads or pad templates.
</para>
<para>
- Its structure is:
+ As an example, below is a dump of the capabilities of the
+ <quote>vorbisdec</quote> element, which you will get by running
+ <command>gst-inspect vorbisdec</command>. You will see two pads:
+ a source and a sink pad. Both of these pads are always available,
+ and both have capabilities attached to them. The sink pad will
+ accept vorbis-encoded audio data, with the mime-type
+ <quote>audio/x-vorbis</quote>. The source pad will be used
+ to send raw (decoded) audio samples to the next element, with
+ a raw audio mime-type (in this case,
+ <quote>audio/x-raw-float</quote>). The source pad will also
+ contain properties for the audio samplerate and the amount of
+ channels, plus some more that you don't need to worry about
+ for now.
</para>
<programlisting>
-struct _GstCaps {
- gchar *name; /* the name of this caps */
- guint16 id; /* type id (major type) */
-
- guint refcount; /* caps are refcounted */
-
- GstProps *properties; /* properties for this capability */
-
- GstCaps *next; /* caps can be chained together */
-};
- </programlisting>
- <para>
- Below is a dump of the capabilities of the element mad, as shown by
- <command>gst-inspect</command>.
- You can see two pads: sink and src. Both pads have capability information attached to them.
- </para>
- <para>
- The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has
- three properties: layer, bitrate and framed.
- </para>
- <para>
- The source pad (output pad) is called 'src' and outputs data of
- MIME type 'audio/raw'. It also has four properties: format, depth,
- rate and channels.
- </para>
- <programlisting>
-Pads:
- SINK template: 'sink'
+Pad Templates:
+ SRC template: 'src'
Availability: Always
Capabilities:
- 'mad_sink':
- MIME type: 'audio/mp3':
-
- SRC template: 'src'
+ audio/x-raw-float
+ rate: [ 8000, 50000 ]
+ channels: [ 1, 2 ]
+ endianness: 1234
+ width: 32
+ buffer-frames: 0
+
+ SINK template: 'sink'
Availability: Always
Capabilities:
- 'mad_src':
- MIME type: 'audio/raw':
- format: String: int
- endianness: Integer: 1234
- width: Integer: 16
- depth: Integer: 16
- channels: Integer range: 1 - 2
- law: Integer: 0
- signed: Boolean: TRUE
- rate: Integer range: 11025 - 48000
+ audio/x-vorbis
</programlisting>
</sect2>
- <sect2 id="sec-pads-props">
- <title>What are properties ?</title>
+
+ <sect2 id="section-caps-props">
+ <title>Properties and values</title>
<para>
Properties are used to describe extra information for
capabilities. A property consists of a key (a string) and
a value. There are different possible value types that can be used:
</para>
-
<itemizedlist>
<listitem>
<para>
- basic types:
+ Basic types, this can be pretty much any
+ <classname>GType</classname> registered with Glib. Those
+ properties indicate a specific, non-dynamic value for this
+ property. Examples include:
</para>
<itemizedlist>
<listitem>
<para>
- an integer value: the property has this exact value.
+ An integer value (<classname>G_TYPE_INT</classname>):
+ the property has this exact value.
</para>
</listitem>
<listitem>
<para>
- a boolean value: the property is either TRUE or FALSE.
+ A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
+ the property is either TRUE or FALSE.
</para>
</listitem>
<listitem>
<para>
- a fourcc value: this is a value that is commonly used to
- describe an encoding for video,
- as used for example by the AVI specification.
- <footnote><para>
- fourcc values consist of four bytes.
- <ulink url="http://www.fourcc.org" type="http">The FOURCC
- Definition List</ulink> is the most complete resource
- on the allowed fourcc values.
- </para></footnote>
+ A float value (<classname>G_TYPE_FLOAT</classname>):
+ the property has this exact floating point value.
</para>
</listitem>
<listitem>
<para>
- a float value: the property has this exact floating point value.
+ A string value (<classname>G_TYPE_STRING</classname>):
+ the property contains a UTF-8 string.
</para>
</listitem>
<listitem>
<para>
- a string value.
+ A fraction value (<classname>GST_TYPE_FRACTION</classname>):
+ contains a fraction expressed by an integer numerator and
+ denominator.
</para>
</listitem>
</itemizedlist>
</listitem>
-
<listitem>
<para>
- range types:
+ Range types are <classname>GType</classname>s registered by
+ &GStreamer; to indicate a range of possible values. They are
+ used for indicating allowed audio samplerate values or
+ supported video sizes. The two types defined in &GStreamer;
+ are:
</para>
<itemizedlist>
<listitem>
<para>
- an integer range value: the property denotes a range of
- possible integer. For example, the wavparse element has
- a source pad where the "rate" property can go from 8000 to
- 48000.
+ An integer range value
+ (<classname>GST_TYPE_INT_RANGE</classname>): the property
+ denotes a range of possible integers, with a lower and an
+ upper boundary. The <quote>vorbisdec</quote> element, for
+ example, has a rate property that can be between 8000 and
+ 50000.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A float range value
+ (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
+ denotes a range of possible floating point values, with a
+ lower and an upper boundary.
</para>
</listitem>
<listitem>
<para>
- a float range value: the property denotes a range of possible
- floating point values.
+ A fraction range value
+ (<classname>GST_TYPE_FRACTION_RANGE</classname>): the property
+ denotes a range of possible fraction values, with a
+ lower and an upper boundary.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
- a list value: the property can take any value from a list of
- basic value types or range types.
+ A list value (<classname>GST_TYPE_LIST</classname>): the
+ property can take any value from a list of basic values
+ given in this list.
</para>
- </listitem>
- </itemizedlist>
-
- </sect2>
- <sect2 id="sec-pads-caps-use">
- <title>What capabilities are used for</title>
- <para>
- Capabilities describe in great detail the type of media that is handled by the pads.
- They are mostly used for:
- </para>
- <itemizedlist>
- <listitem>
<para>
- Autoplugging: automatically finding plugins for a set of capabilities
+ Example: caps that express that either
+ a sample rate of 44100 Hz and a sample rate of 48000 Hz
+ is supported would use a list of integer values, with
+ one value being 44100 and one value being 48000.
</para>
</listitem>
<listitem>
<para>
- Compatibility detection: when two pads are linked, <application>GStreamer</application>
- can verify if the two pads are talking about the same media types.
- The process of linking two pads and checking if they are compatible
- is called "caps negotiation".
+ An array value (<classname>GST_TYPE_ARRAY</classname>): the
+ property is an array of values. Each value in the array is a
+ full value on its own, too. All values in the array should be
+ of the same elementary type. This means that an array can
+ contain any combination of integers, lists of integers, integer
+ ranges together, and the same for floats or strings, but it can
+ not contain both floats and ints at the same time.
+ </para>
+ <para>
+ Example: for audio where there are more than two channels involved
+ the channel layout needs to be specified (for one and two channel
+ audio the channel layout is implicit unless stated otherwise in the
+ caps). So the channel layout would be an array of integer enum
+ values where each enum value represents a loudspeaker position.
+ Unlike a <classname>GST_TYPE_LIST</classname>, the values in an
+ array will be interpreted as a whole.
</para>
</listitem>
</itemizedlist>
</sect2>
- <sect2 id="sec-pads-caps-get">
- <title>Getting the capabilities of a pad</title>
+ </sect1>
+
+ <sect1 id="section-caps-api">
+ <title>What capabilities are used for</title>
+ <para>
+ Capabilities (short: caps) describe the type of data that is streamed
+ between two pads, or that one pad (template) supports. This makes them
+ very useful for various purposes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Autoplugging: automatically finding elements to link to a
+ pad based on its capabilities. All autopluggers use this
+ method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Compatibility detection: when two pads are linked, &GStreamer;
+ can verify if the two pads are talking about the same media
+ type. The process of linking two pads and checking if they
+ are compatible is called <quote>caps negotiation</quote>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Metadata: by reading the capabilities from a pad, applications
+ can provide information about the type of media that is being
+ streamed over the pad, which is information about the stream
+ that is currently being played back.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Filtering: an application can use capabilities to limit the
+ possible media types that can stream between two pads to a
+ specific subset of their supported stream types. An application
+ can, for example, use <quote>filtered caps</quote> to set a
+ specific (fixed or non-fixed) video size that should stream
+ between two pads. You will see an example of filtered caps
+ later in this manual, in <xref linkend="section-data-spoof"/>.
+ You can do caps filtering by inserting a capsfilter element into
+ your pipeline and setting its <quote>caps</quote> property. Caps
+ filters are often placed after converter elements like audioconvert,
+ audioresample, ffmpegcolorspace or videoscale to force those
+ converters to convert data to a specific output format at a
+ certain point in a stream.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 id="section-caps-metadata">
+ <title>Using capabilities for metadata</title>
<para>
- A pad can have a chain of capabilities attached to it. You can get the capabilities chain
- with:
+ A pad can have a set (i.e. one or more) of capabilities attached
+ to it. Capabilities (<classname>GstCaps</classname>) are represented
+ as an array of one or more <classname>GstStructure</classname>s, and
+ each <classname>GstStructure</classname> is an array of fields where
+ each field consists of a field name string (e.g. "width") and a
+ typed value (e.g. <classname>G_TYPE_INT</classname> or
+ <classname>GST_TYPE_INT_RANGE</classname>).
+ </para>
+ <para>
+ Note that there is a distinct difference between the
+ <emphasis>possible</emphasis> capabilities of a pad (ie. usually what
+ you find as caps of pad templates as they are shown in gst-inspect),
+ the <emphasis>allowed</emphasis> caps of a pad (can be the same as
+ the pad's template caps or a subset of them, depending on the possible
+ caps of the peer pad) and lastly <emphasis>negotiated</emphasis> caps
+ (these describe the exact format of a stream or buffer and contain
+ exactly one structure and have no variable bits like ranges or lists,
+ ie. they are fixed caps).
+ </para>
+ <para>
+ You can get values of properties in a set of capabilities
+ by querying individual properties of one structure. You can get
+ a structure from a caps using
+ <function>gst_caps_get_structure ()</function> and the number of
+ structures in a <classname>GstCaps</classname> using
+ <function>gst_caps_get_size ()</function>.
</para>
- <programlisting>
- GstCaps *caps;
- ...
- caps = gst_pad_get_caps (pad);
+ <para>
+ Caps are called <emphasis>simple caps</emphasis> when they contain
+ only one structure, and <emphasis>fixed caps</emphasis> when they
+ contain only one structure and have no variable field types (like
+ ranges or lists of possible values). Two other special types of caps
+ are <emphasis>ANY caps</emphasis> and <emphasis>empty caps</emphasis>.
+ </para>
+ <para>
+ Here is an example of how to extract the width and height from
+ a set of fixed video caps:
+ <programlisting>
+static void
+read_video_props (GstCaps *caps)
+{
+ gint width, height;
+ const GstStructure *str;
- g_print ("pad name %s\n", gst_pad_get_name (pad));
-
- while (caps) {
- g_print (" Capability name %s, MIME type %s\n",
- gst_caps_get_name (cap),
- gst_caps_get_mime (cap));
-
- caps = caps->next;
- }
- ...
- </programlisting>
+ g_return_if_fail (gst_caps_is_fixed (caps));
+
+ str = gst_caps_get_structure (caps, 0);
+ if (!gst_structure_get_int (str, "width", &width) ||
+ !gst_structure_get_int (str, "height", &height)) {
+ g_print ("No width/height available\n");
+ return;
+ }
+
+ g_print ("The video size of this set of capabilities is %dx%d\n",
+ width, height);
+}
+ </programlisting>
+ </para>
</sect2>
- <sect2 id="sec-pads-caps-create">
- <title>Creating capability structures</title>
+
+ <sect2 id="section-caps-filter">
+ <title>Creating capabilities for filtering</title>
<para>
While capabilities are mainly used inside a plugin to describe the
- media type of the pads, the application programmer also has to have
- basic understanding of capabilities in order to interface with the
- plugins, specially when using the autopluggers.
- </para>
- <para>
- As we said, a capability has a name, a mime-type and some
- properties. The signature of the function to create a new
- <classname>GstCaps</classname> structure is:
-
- <programlisting>
-GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
- </programlisting>
+ media type of the pads, the application programmer often also has
+ to have basic understanding of capabilities in order to interface
+ with the plugins, especially when using filtered caps. When you're
+ using filtered caps or fixation, you're limiting the allowed types of
+ media that can stream between two pads to a subset of their supported
+ media types. You do this using a <classname>capsfilter</classname>
+ element in your pipeline. In order to do this, you also need to
+ create your own <classname>GstCaps</classname>. The easiest way to
+ do this is by using the convenience function
+ <function>gst_caps_new_simple ()</function>:
</para>
<para>
- You can therefore create a new capability with no properties like this:
- <programlisting>
- GstCaps *newcaps;
-
- newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
- </programlisting>
- </para>
- <para>
- <classname>GstProps</classname> basically consist of a set of key-value pairs
- and are created with a function with this signature:
- <programlisting>
-GstProps* gst_props_new (const gchar *firstname, ...);
- </programlisting>
+ <programlisting>
+static gboolean
+link_elements_with_filter (GstElement *element1, GstElement *element2)
+{
+ gboolean link_ok;
+ GstCaps *caps;
+
+ caps = gst_caps_new_simple ("video/x-raw-yuv",
+ "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
+ "width", G_TYPE_INT, 384,
+ "height", G_TYPE_INT, 288,
+ "framerate", GST_TYPE_FRACTION, 25, 1,
+ NULL);
+
+ link_ok = gst_element_link_filtered (element1, element2, caps);
+ gst_caps_unref (caps);
+
+ if (!link_ok) {
+ g_warning ("Failed to link element1 and element2!");
+ }
+
+ return link_ok;
+}
+ </programlisting>
+ This will force the data flow between those two elements to
+ a certain video format, width, height and framerate (or the linking
+ will fail if that cannot be achieved in the context of the elements
+ involved). Keep in mind that when you use <function>
+ gst_element_link_filtered ()</function> it will automatically create
+ a <classname>capsfilter</classname> element for you and insert it into
+ your bin or pipeline between the two elements you want to connect (this
+ is important if you ever want to disconnect those elements because then
+ you will have to disconnect both elements from the capsfilter instead).
</para>
<para>
- The keys are given as strings and the values are given with a set of macros:
- <itemizedlist>
- <listitem>
- <para>
- GST_PROPS_INT(a): An integer value
- </para>
- </listitem>
- <listitem>
- <para>
- GST_PROPS_FLOAT(a): A floating point value
- </para>
- </listitem>
- <listitem>
- <para>
- GST_PROPS_FOURCC(a): A fourcc value
- </para>
- </listitem>
- <listitem>
- <para>
- GST_PROPS_BOOLEAN(a): A boolean value
- </para>
- </listitem>
- <listitem>
- <para>
- GST_PROPS_STRING(a): A string value
- </para>
- </listitem>
- </itemizedlist>
- The values can also be specified as ranges with:
- <itemizedlist>
- <listitem>
- <para>
- GST_PROPS_INT_RANGE(a,b): An integer range from a to b
- </para>
- </listitem>
- <listitem>
- <para>
- GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
- </para>
- </listitem>
- </itemizedlist>
- All of the above values can be given with a list too, using:
- <itemizedlist>
- <listitem>
- <para>
- GST_PROPS_LIST(a,...): A list of property values.
- </para>
- </listitem>
- </itemizedlist>
+ In some cases, you will want to create a more elaborate set of
+ capabilities to filter a link between two pads. Then, this function
+ is too simplistic and you'll want to use the method
+ <function>gst_caps_new_full ()</function>:
</para>
+ <programlisting>
+static gboolean
+link_elements_with_filter (GstElement *element1, GstElement *element2)
+{
+ gboolean link_ok;
+ GstCaps *caps;
+
+ caps = gst_caps_new_full (
+ gst_structure_new ("video/x-raw-yuv",
+ "width", G_TYPE_INT, 384,
+ "height", G_TYPE_INT, 288,
+ "framerate", GST_TYPE_FRACTION, 25, 1,
+ NULL),
+ gst_structure_new ("video/x-raw-rgb",
+ "width", G_TYPE_INT, 384,
+ "height", G_TYPE_INT, 288,
+ "framerate", GST_TYPE_FRACTION, 25, 1,
+ NULL),
+ NULL);
+
+ link_ok = gst_element_link_filtered (element1, element2, caps);
+ gst_caps_unref (caps);
+
+ if (!link_ok) {
+ g_warning ("Failed to link element1 and element2!");
+ }
+
+ return link_ok;
+}
+ </programlisting>
<para>
- A more complex capability with properties is created like this:
- <programlisting>
- GstCaps *newcaps;
-
- newcaps = gst_caps_new ("my_caps",
- "audio/wav",
- gst_props_new (
- "bitrate", GST_PROPS_INT_RANGE (11025,22050),
- "depth", GST_PROPS_INT (16),
- "signed", GST_PROPS_LIST (
- GST_PROPS_BOOLEAN (TRUE),
- GST_PROPS_BOOLEAN (FALSE)
- ),
- NULL
- );
- </programlisting>
- Optionally, the convenient shortcut macro can be used. The above complex
- capability can be created with:
- <programlisting>
- GstCaps *newcaps;
-
- newcaps = GST_CAPS_NEW ("my_caps",
- "audio/wav",
- "bitrate", GST_PROPS_INT_RANGE (11025,22050),
- "depth", GST_PROPS_INT (16),
- "signed", GST_PROPS_LIST (
- GST_PROPS_BOOLEAN (TRUE),
- GST_PROPS_BOOLEAN (FALSE)
- )
- );
- </programlisting>
+ See the API references for the full API of
+ <ulink type="http"
+ url="&URLAPI;GstStructure.html"><classname>GstStructure</classname></ulink>
+ and <ulink type="http"
+ url="&URLAPI;GstCaps.html"><classname>GstCaps</classname></ulink>.
</para>
</sect2>
+ </sect1>
+
+ <sect1 id="section-pads-ghost">
+ <title>Ghost pads</title>
+ <para>
+ You can see from <xref linkend="section-bin-noghost-img"/> how a bin
+ has no pads of its own. This is where "ghost pads" come into play.
+ </para>
+ <figure float="1" id="section-bin-noghost-img">
+ <title>Visualisation of a <ulink type="http"
+ url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
+ element without ghost pads</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="75" fileref="images/bin-element-noghost.ℑ"
+ format="&IMAGE;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ A ghost pad is a pad from some element in the bin that can be
+ accessed directly from the bin as well. Compare it to a symbolic
+ link in UNIX filesystems. Using ghost pads on bins, the bin also
+ has a pad and can transparently be used as an element in other
+ parts of your code.
+ </para>
+
+ <figure float="1" id="section-bin-ghost-img">
+ <title>Visualisation of a <ulink type="http"
+ url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
+ element with a ghost pad</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="75" fileref="images/bin-element-ghost.ℑ"
+ format="&IMAGE;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ <xref linkend="section-bin-ghost-img"/> is a representation of a
+ ghost pad. The sink pad of element one is now also a pad of the bin.
+ Because ghost pads look and work like any other pads, they can be added
+ to any type of elements, not just to a <classname>GstBin</classname>,
+ just like ordinary pads.
+ </para>
+ <para>
+ A ghostpad is created using the function
+ <function>gst_ghost_pad_new ()</function>:
+ </para>
+ <programlisting><!-- example-begin ghostpad.c a -->
+#include <gst/gst.h>
+
+int
+main (int argc,
+ char *argv[])
+{
+ GstElement *bin, *sink;
+ GstPad *pad;
+ /* init */
+ gst_init (&argc, &argv);
+
+ /* create element, add to bin */
+ sink = gst_element_factory_make ("fakesink", "sink");
+ bin = gst_bin_new ("mybin");
+ gst_bin_add (GST_BIN (bin), sink);
+
+ /* add ghostpad */
+ pad = gst_element_get_static_pad (sink, "sink");
+ gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
+ gst_object_unref (GST_OBJECT (pad));
+<!-- example-end ghostpad.c a -->
+[..]<!-- example-begin ghostpad.c b --><!--
+ return 0;
+--><!-- example-end ghostpad.c b -->
+<!-- example-begin ghostpad.c c -->
+}
+ <!-- example-end ghostpad.c c --></programlisting>
+ <para>
+ In the above example, the bin now also has a pad: the pad called
+ <quote>sink</quote> of the given element. The bin can, from here
+ on, be used as a substitute for the sink element. You could, for
+ example, link another element to the bin.
+ </para>
</sect1>
</chapter>
projects / platform / upstream / gstreamer.git / blobdiff