1 <chapter id="chapter-pads" xreflabel="Pads and capabilities">
2 <title>Pads and capabilities</title>
4 As we have seen in <xref linkend="chapter-elements"/>, the pads are
5 the element's interface to the outside world. Data streams from one
6 element's source pad to another element's sink pad. The specific
7 type of media that the element can handle will be exposed by the
8 pad's capabilities. We will talk more on capabilities later in this
9 chapter (see <xref linkend="section-caps"/>).
12 <sect1 id="section-pads">
15 A pad type is defined by two properties: its direction and its
16 availability. As we've mentioned before, &GStreamer; defines two
17 pad directions: source pads and sink pads. This terminology is
18 defined from the view of within the element: elements receive data
19 on their sink pads and generate data on their source pads.
20 Schematically, sink pads are drawn on the left side of an element,
21 whereas source pads are drawn on the right side of an element. In
22 such graphs, data flows from left to right.
25 In reality, there is no objection to data flowing from a
26 source pad to the sink pad of an element upstream (to the
27 left of this element in drawings). Data will, however, always
28 flow from a source pad of one element to the sink pad of
35 Pad directions are very simple compared to pad availability. A pad
36 can have any of three availabilities: always, sometimes and on
37 request. The meaning of those three types is exactly as it says:
38 always pads always exist, sometimes pad exist only in certain
39 cases (and can disappear randomly), and on-request pads appear
40 only if explicitely requested by applications.
43 <sect2 id="section-pads-dynamic">
44 <title>Dynamic (or sometimes) pads</title>
46 Some elements might not have all of their pads when the element is
47 created. This can happen, for example, with an Ogg demuxer element.
48 The element will read the Ogg stream and create dynamic pads for
49 each contained elementary stream (vorbis, theora) when it detects
50 such a stream in the Ogg stream. Likewise, it will delete the pad
51 when the stream ends. This principle is very useful for demuxer
52 elements, for example.
55 Running <application>gst-inspect oggdemux</application> will show
56 that the element has only one pad: a sink pad called 'sink'. The
57 other pads are <quote>dormant</quote>. You can see this in the pad
58 template because there is an <quote>Exists: Sometimes</quote>
59 property. Depending on the type of Ogg file you play, the pads will
60 be created. We will see that this is very important when you are
61 going to create dynamic pipelines. You can attach a signal handler
62 to an element to inform you when the element has created a new pad
63 from one of its <quote>sometimes</quote> pad templates. The
64 following piece of code is an example of how to do this:
66 <programlisting><!-- example-begin pad.c a -->
67 #include <gst/gst.h>
70 cb_new_pad (GstElement *element,
76 name = gst_pad_get_name (pad);
77 g_print ("A new pad %s was created\n", name);
80 /* here, you would setup a new pad link for the newly created pad */
81 <!-- example-end pad.c a -->[..]
82 <!-- example-begin pad.c b -->
89 GstElement *pipeline, *source, *demux;
93 gst_init (&argc, &argv);
96 pipeline = gst_pipeline_new ("my_pipeline");
97 source = gst_element_factory_make ("filesrc", "source");
98 g_object_set (source, "location", argv[1], NULL);
99 demux = gst_element_factory_make ("oggdemux", "demuxer");
101 /* you would normally check that the elements were created properly */
103 /* put together a pipeline */
104 gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
105 gst_element_link_pads (source, "src", demux, "sink");
107 /* listen for newly created pads */
108 g_signal_connect (demux, "new-pad", G_CALLBACK (cb_new_pad), NULL);
110 /* start the pipeline */
111 gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
112 loop = g_main_loop_new (NULL, FALSE);
113 g_main_loop_run (loop);
114 <!--example-end pad.c b -->
115 [..]<!-- example-begin pad.c c --><!--
117 --><!-- example-end pad.c c -->
118 <!-- example-begin pad.c d -->
120 <!-- example-end pad.c d --></programlisting>
123 <sect2 id="section-pads-request">
124 <title>Request pads</title>
126 An element can also have request pads. These pads are not created
127 automatically but are only created on demand. This is very useful
128 for multiplexers, aggregators and tee elements. Aggregators are
129 elements that merge the content of several input streams together
130 into one output stream. Tee elements are the reverse: they are
131 elements that have one input stream and copy this stream to each
132 of their output pads, which are created on request. Whenever an
133 application needs another copy of the stream, it can simply request
134 a new output pad from the tee element.
137 The following piece of code shows how you can request a new output
138 pad from a <quote>tee</quote> element:
142 some_function (GstElement *tee)
147 pad = gst_element_get_request_pad (tee, "src%d");
148 name = gst_pad_get_name (pad);
149 g_print ("A new pad %s was created\n", name);
152 /* here, you would link the pad */
155 /* and, after doing that, free our reference */
156 gst_object_unref (GST_OBJECT (pad));
160 The <function>gst_element_get_request_pad ()</function> method
161 can be used to get a pad from the element based on the name of
162 the pad template. It is also possible to request a pad that is
163 compatible with another pad template. This is very useful if
164 you want to link an element to a multiplexer element and you
165 need to request a pad that is compatible. The method
166 <function>gst_element_get_compatible_pad ()</function> can be
167 used to request a compatible pad, as shown in the next example.
168 It will request a compatible pad from an Ogg multiplexer from
173 link_to_multiplexer (GstPad *tolink_pad,
177 gchar *srcname = gst_pad_get_name (tolink_pad), *sinkname;
179 pad = gst_element_get_compatible_pad (mux, tolink_pad);
180 gst_pad_link (tolinkpad, pad);
181 sinkname = gst_pad_get_name (pad);
182 gst_object_unref (GST_OBJECT (pad));
184 g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
192 <sect1 id="section-caps">
193 <title>Capabilities of a pad</title>
195 Since the pads play a very important role in how the element is
196 viewed by the outside world, a mechanism is implemented to describe
197 the data that can flow or currently flows through the pad by using
198 capabilities. Here,w e will briefly describe what capabilities are
199 and how to use them, enough to get an understanding of the concept.
200 For an in-depth look into capabilities and a list of all capabilities
201 defined in &GStreamer;, see the <ulink type="http"
202 url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
203 Writers Guide</ulink>.
206 Capabilities are attached to pad templates and to pads. For pad
207 templates, it will describe the types of media that may stream
208 over a pad created from this template. For pads, it can either
209 be a list of possible caps (usually a copy of the pad template's
210 capabilities), in which case the pad is not yet negotiated, or it
211 is the type of media that currently streams over this pad, in
212 which case the pad has been negotiated already.
215 <sect2 id="section-caps-structure">
216 <title>Dissecting capabilities</title>
218 A pads capabilities are described in a <classname>GstCaps</classname>
219 object. Internally, a <ulink type="http"
220 url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
221 will contain one or more <ulink type="http"
222 url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
223 that will describe one media type. A negotiated pad will have
224 capabilities set that contain exactly <emphasis>one</emphasis>
225 structure. Also, this structure will contain only
226 <emphasis>fixed</emphasis> values. These constraints are not
227 true for unnegotiated pads or pad templates.
230 As an example, below is a dump of the capabilities of the
231 <quote>vorbisdec</quote> element, which you will get by running
232 <command>gst-inspect vorbisdec</command>. You will see two pads:
233 a source and a sink pad. Both of these pads are always available,
234 and both have capabilities attached to them. The sink pad will
235 accept vorbis-encoded audio data, with the mime-type
236 <quote>audio/x-vorbis</quote>. The source pad will be used
237 to send raw (decoded) audio samples to the next element, with
238 a raw audio mime-type (either <quote>audio/x-raw-int</quote> or
239 <quote>audio/x-raw-float</quote>). The source pad will also
240 contain properties for the audio samplerate and the amount of
241 channels, plus some more that you don't need to worry about
250 rate: [ 8000, 50000 ]
256 SINK template: 'sink'
263 <sect2 id="section-caps-props">
264 <title>Properties and values</title>
266 Properties are used to describe extra information for
267 capabilities. A property consists of a key (a string) and
268 a value. There are different possible value types that can be used:
273 Basic types, this can be pretty much any
274 <classname>GType</classname> registered with Glib. Those
275 properties indicate a specific, non-dynamic value for this
276 property. Examples include:
281 An integer value (<classname>G_TYPE_INT</classname>):
282 the property has this exact value.
287 A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
288 the property is either TRUE or FALSE.
293 A float value (<classname>G_TYPE_FLOAT</classname>):
294 the property has this exact floating point value.
299 A string value (<classname>G_TYPE_STRING</classname>):
300 the property contains a UTF-8 string.
307 Range types are <classname>GType</classname>s registered by
308 &GStreamer; to indicate a range of possible values. They are
309 used for indicating allowed audio samplerate values or
310 supported video sizes. The two types defined in &GStreamer;
316 An integer range value
317 (<classname>GST_TYPE_INT_RANGE</classname>): the property
318 denotes a range of possible integers, with a lower and an
319 upper boundary. The <quote>vorbisdec</quote> element, for
320 example, has a rate property that can be between 8000 and
327 (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
328 denotes a range of possible floating point values, with a
329 lower and an upper boundary.
336 A list value (<classname>GST_TYPE_LIST</classname>): the
337 property can take any value from a list of basic values
343 An array value (<classname>GST_TYPE_FIXED_LIST</classname>): the
344 property is an array of values. Each value in the array is a
345 full value on its own, too. All values in the array should be
346 of the same elementary type. This means that an array can
347 contain any combination of integers, lists of integers, integer
348 ranges together, and the same for floats or strings, but it can
349 not contain both floats and ints at the same time.
356 <sect1 id="section-caps-api">
357 <title>What capabilities are used for</title>
359 Capabilities describe the type of data that is streamed between
360 two pads, or that one pad (template) supports. This makes them
361 very useful for various purposes:
366 Autoplugging: automatically finding elements to link to a
367 pad based on its capabilities. All autopluggers use this
373 Compatibility detection: when two pads are linked, &GStreamer;
374 can verify if the two pads are talking about the same media
375 type. The process of linking two pads and checking if they
376 are compatible is called <quote>caps negotiation</quote>.
381 Metadata: by reading the capabilities from a pad, applications
382 can provide information about the type of media that is being
383 streamed over the pad, which is information about the stream
384 thatis currently being played back.
389 Filtering: an application can use capabilities to limit the
390 possible media types that can stream between two pads to a
391 specific subset of their supported stream types. An application
392 can, for example, use <quote>filtered caps</quote> to set a
393 specific (non-fixed) video size that will stream between two
399 <sect2 id="section-caps-metadata">
400 <title>Using capabilities for metadata</title>
402 A pad can have a set (i.e. one or more) of capabilities attached
403 to it. You can get values of properties in a set of capabilities
404 by querying individual properties of one structure. You can get
405 a structure from a caps using
406 <function>gst_caps_get_structure ()</function>:
410 read_video_props (GstCaps *caps)
413 const GstStructure *str;
415 str = gst_caps_get_structure (caps);
416 if (!gst_structure_get_int (str, "width", &width) ||
417 !gst_structure_get_int (str, "height", &height)) {
418 g_print ("No width/height available\n");
422 g_print ("The video size of this set of capabilities is %dx%d\n",
428 <sect2 id="section-caps-filter">
429 <title>Creating capabilities for filtering</title>
431 While capabilities are mainly used inside a plugin to describe the
432 media type of the pads, the application programmer also has to have
433 basic understanding of capabilities in order to interface with the
434 plugins, especially when using filtered caps. When you're using
435 filtered caps or fixation, you're limiting the allowed types of
436 media that can stream between two pads to a subset of their supported
437 media types. You do this by filtering using your own set of
438 capabilities. In order to do this, you need to create your own
439 <classname>GstCaps</classname>. The simplest way to do this is by
440 using the convenience function <function>gst_caps_new_simple
445 link_pads_with_filter (GstPad *one,
450 caps = gst_caps_new_simple ("video/x-raw-yuv",
451 "width", G_TYPE_INT, 384,
452 "height", G_TYPE_INT, 288,
453 "framerate", G_TYPE_DOUBLE, 25.,
455 gst_pad_link_filtered (one, other, caps);
459 In some cases, you will want to create a more elaborate set of
460 capabilities to filter a link between two pads. Then, this function
461 is too simplistic and you'll want to use the method
462 <function>gst_caps_new_full ()</function>:
466 link_pads_with_filter (GstPad *one,
471 caps = gst_caps_new_full (
472 gst_structure_new ("video/x-raw-yuv",
473 "width", G_TYPE_INT, 384,
474 "height", G_TYPE_INT, 288,
475 "framerate", G_TYPE_DOUBLE, 25.,
477 gst_structure_new ("video/x-raw-rgb",
478 "width", G_TYPE_INT, 384,
479 "height", G_TYPE_INT, 288,
480 "framerate", G_TYPE_DOUBLE, 25.,
484 gst_pad_link_filtered (one, other, caps);
488 See the API references for the full API of
489 <classname>GstStructure</classname> and
490 <classname>GstCaps</classname>.
495 <sect1 id="section-pads-ghost">
496 <title>Ghost pads</title>
498 You can see from <xref linkend="section-bin-noghost-img"/> how a bin
499 has no pads of its own. This is where "ghost pads" come into play.
501 <figure float="1" id="section-bin-noghost-img">
502 <title>Visualisation of a <ulink type="http"
503 url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
504 element without ghost pads</title>
507 <imagedata fileref="images/bin-element-noghost.ℑ"
513 A ghost pad is a pad from some element in the bin that can be
514 accessed directly from the bin as well. Compare it to a symbolic
515 link in UNIX filesystems. Using ghost pads on bins, the bin also
516 has a pad and can transparently be used as an element in other
520 <figure float="1" id="section-bin-ghost-img">
521 <title>Visualisation of a <ulink type="http"
522 url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
523 element with a ghost pad</title>
526 <imagedata fileref="images/bin-element-ghost.ℑ"
532 <xref linkend="section-bin-ghost-img"/> is a representation of a
533 ghost pad. The sink pad of element one is now also a pad of the bin.
534 Obviously, ghost pads can be added to any type of elements, not just
535 to a <classname>GstBin</classname>.
538 A ghostpad is created using the function
539 <function>gst_ghost_pad_new ()</function>:
541 <programlisting><!-- example-begin ghostpad.c a -->
542 #include <gst/gst.h>
548 GstElement *bin, *sink;
552 gst_init (&argc, &argv);
554 /* create element, add to bin */
555 sink = gst_element_factory_make ("fakesink", "sink");
556 bin = gst_bin_new ("mybin");
557 gst_bin_add (GST_BIN (bin), sink);
560 pad = gst_element_get_pad (sink, "sink");
561 gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
562 gst_object_unref (GST_OBJECT (pad));
563 <!-- example-end ghostpad.c a -->
564 [..]<!-- example-begin ghostpad.c b --><!--
566 --><!-- example-end ghostpad.c b -->
567 <!-- example-begin ghostpad.c c -->
569 <!-- example-end ghostpad.c c --></programlisting>
571 In the above example, the bin now also has a pad: the pad called
572 <quote>sink</quote> of the given element. The bin can, from here
573 on, be used as a substitute for the sink element. You could, for
574 example, link another element to the bin.