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:
68 cb_new_pad (GstElement *element,
72 g_print ("A new pad %s was created\n", gst_pad_get_name (pad));
74 /* here, you would setup a new pad link for the newly created pad */
79 main(int argc, char *argv[])
81 GstElement *pipeline, *source, *demux;
84 gst_init (&argc, &argv);
87 pipeline = gst_pipeline_new ("my_pipeline");
88 source = gst_element_factory_make ("filesrc", "source");
89 g_object_set (source, "location", argv[1], NULL);
90 demux = gst_element_factory_make ("oggdemux", "demuxer");
92 /* you would normally check that the elements were created properly */
94 /* put together a pipeline */
95 gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
96 gst_element_link (source, demux);
98 /* listen for newly created pads */
99 g_signal_connect (demux, "new-pad", G_CALLBACK (cb_new_pad), NULL);
101 /* start the pipeline */
102 gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
103 while (gst_bin_iterate (GST_BIN (pipeline)));
110 <sect2 id="section-pads-request">
111 <title>Request pads</title>
113 An element can also have request pads. These pads are not created
114 automatically but are only created on demand. This is very useful
115 for multiplexers, aggregators and tee elements. Aggregators are
116 elements that merge the content of several input streams together
117 into one output stream. Tee elements are the reverse: they are
118 elements that have one input stream and copy this stream to each
119 of their output pads, which are created on request. Whenever an
120 application needs another copy of the stream, it can simply request
121 a new output pad from the tee element.
124 The following piece of code shows how you can request a new output
125 pad from a <quote>tee</quote> element:
129 some_function (GstElement *tee)
133 pad = gst_element_get_request_pad (tee, "src%d");
134 g_print ("A new pad %s was created\n", gst_pad_get_name (pad));
136 /* here, you would link the pad */
141 The <function>gst_element_get_request_pad ()</function> method
142 can be used to get a pad from the element based on the name of
143 the pad template. It is also possible to request a pad that is
144 compatible with another pad template. This is very useful if
145 you want to link an element to a multiplexer element and you
146 need to request a pad that is compatible. The method
147 <function>gst_element_get_compatible_pad ()</function> can be
148 used to request a compatible pad, as shown in the next example.
149 It will request a compatible pad from an Ogg multiplexer from
154 link_to_multiplexer (GstPad *tolink_pad,
159 pad = gst_element_get_compatible_pad (mux, tolink_pad);
160 gst_pad_link (tolinkpad, pad);
162 g_print ("A new pad %s was created and linked to %s\n",
163 gst_pad_get_name (pad), gst_pad_get_name (tolink_pad));
169 <sect1 id="section-caps">
170 <title>Capabilities of a pad</title>
172 Since the pads play a very important role in how the element is
173 viewed by the outside world, a mechanism is implemented to describe
174 the data that can flow or currently flows through the pad by using
175 capabilities. Here,w e will briefly describe what capabilities are
176 and how to use them, enough to get an understanding of the concept.
177 For an in-depth look into capabilities and a list of all capabilities
178 defined in &GStreamer;, see the <ulink type="http"
179 url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
180 Writers Guide</ulink>.
183 Capabilities are attached to pad templates and to pads. For pad
184 templates, it will describe the types of media that may stream
185 over a pad created from this template. For pads, it can either
186 be a list of possible caps (usually a copy of the pad template's
187 capabilities), in which case the pad is not yet negotiated, or it
188 is the type of media that currently streams over this pad, in
189 which case the pad has been negotiated already.
192 <sect2 id="section-caps-structure">
193 <title>Dissecting capabilities</title>
195 A pads capabilities are described in a <classname>GstCaps</classname>
196 object. Internally, a <ulink type="http"
197 url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
198 will contain one or more <ulink type="http"
199 url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
200 that will describe one media type. A negotiated pad will have
201 capabilities set that contain exactly <emphasis>one</emphasis>
202 structure. Also, this structure will contain only
203 <emphasis>fixed</emphasis> values. These constraints are not
204 true for unnegotiated pads or pad templates.
207 As an example, below is a dump of the capabilities of the
208 <quote>vorbisdec</quote> element, which you will get by running
209 <command>gst-inspect vorbisdec</command>. You will see two pads:
210 a source and a sink pad. Both of these pads are always available,
211 and both have capabilities attached to them. The sink pad will
212 accept vorbis-encoded audio data, with the mime-type
213 <quote>audio/x-vorbis</quote>. The source pad will be used
214 to send raw (decoded) audio samples to the next element, with
215 a raw audio mime-type (either <quote>audio/x-raw-int</quote> or
216 <quote>audio/x-raw-float</quote>). The source pad will also
217 contain properties for the audio samplerate and the amount of
218 channels, plus some more that you don't need to worry about
227 rate: [ 8000, 50000 ]
233 SINK template: 'sink'
240 <sect2 id="section-caps-props">
241 <title>Properties and values</title>
243 Properties are used to describe extra information for
244 capabilities. A property consists of a key (a string) and
245 a value. There are different possible value types that can be used:
250 Basic types, this can be pretty much any
251 <classname>GType</classname> registered with Glib. Those
252 properties indicate a specific, non-dynamic value for this
253 property. Examples include:
258 An integer value (<classname>G_TYPE_INT</classname>):
259 the property has this exact value.
264 A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
265 the property is either TRUE or FALSE.
270 A float value (<classname>G_TYPE_FLOAT</classname>):
271 the property has this exact floating point value.
276 A string value (<classname>G_TYPE_STRING</classname>):
277 the property contains a UTF-8 string.
284 Range types are <classname>GType</classname>s registered by
285 &GStreamer; to indicate a range of possible values. They are
286 used for indicating allowed audio samplerate values or
287 supported video sizes. The two types defined in &GStreamer;
293 An integer range value
294 (<classname>GST_TYPE_INT_RANGE</classname>): the property
295 denotes a range of possible integers, with a lower and an
296 upper boundary. The <quote>vorbisdec</quote> element, for
297 example, has a rate property that can be between 8000 and
304 (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
305 denotes a range of possible floating point values, with a
306 lower and an upper boundary.
313 A list value (<classname>GST_TYPE_LIST</classname>): the
314 property can take any value from a list of basic values
322 <sect1 id="section-caps-api">
323 <title>What capabilities are used for</title>
325 Capabilities describe the type of data that is streamed between
326 two pads, or that one pad (template) supports. This makes them
327 very useful for various purposes:
332 Autoplugging: automatically finding elements to link to a
333 pad based on its capabilities. All autopluggers use this
339 Compatibility detection: when two pads are linked, &GStreamer;
340 can verify if the two pads are talking about the same media
341 type. The process of linking two pads and checking if they
342 are compatible is called <quote>caps negotiation</quote>.
347 Metadata: by reading the capabilities from a pad, applications
348 can provide information about the type of media that is being
349 streamed over the pad, which is information about the stream
350 thatis currently being played back.
355 Filtering: an application can use capabilities to limit the
356 possible media types that can stream between two pads to a
357 specific subset of their supported stream types. An application
358 can, for example, use <quote>filtered caps</quote> to set a
359 specific (non-fixed) video size that will stream between two
365 <sect2 id="section-caps-metadata">
366 <title>Using capabilities for metadata</title>
368 A pad can have a set (i.e. one or more) of capabilities attached
369 to it. You can get values of properties in a set of capabilities
370 by querying individual properties of one structure. You can get
371 a structure from a caps using
372 <function>gst_caps_get_structure ()</function>:
376 read_video_props (GstCaps *caps)
379 const GstStructure *str;
381 str = gst_caps_get_structure (caps);
382 if (!gst_structure_get_int (str, "width", &width) ||
383 !gst_structure_get_int (str, "height", &height)) {
384 g_print ("No width/height available\n");
388 g_print ("The video size of this set of capabilities is %dx%d\n",
394 <sect2 id="section-caps-filter">
395 <title>Creating capabilities for filtering</title>
397 While capabilities are mainly used inside a plugin to describe the
398 media type of the pads, the application programmer also has to have
399 basic understanding of capabilities in order to interface with the
400 plugins, especially when using filtered caps. When you're using
401 filtered caps or fixation, you're limiting the allowed types of
402 media that can stream between two pads to a subset of their supported
403 media types. You do this by filtering using your own set of
404 capabilities. In order to do this, you need to create your own
405 <classname>GstCaps</classname>. The simplest way to do this is by
406 using the convenience function <function>gst_caps_new_simple
411 link_pads_with_filter (GstPad *one,
416 caps = gst_caps_new_simple ("video/x-raw-yuv",
417 "width", G_TYPE_INT, 384,
418 "height", G_TYPE_INT, 288,
419 "framerate", G_TYPE_DOUBLE, 25.,
421 gst_pad_link_filtered (one, other, caps);
425 In some cases, you will want to create a more elaborate set of
426 capabilities to filter a link between two pads. Then, this function
427 is too simplistic and you'll want to use the method
428 <function>gst_caps_new_full ()</function>:
432 link_pads_with_filter (GstPad *one,
437 caps = gst_caps_new_full (
438 gst_structure_new ("video/x-raw-yuv",
439 "width", G_TYPE_INT, 384,
440 "height", G_TYPE_INT, 288,
441 "framerate", G_TYPE_DOUBLE, 25.,
443 gst_structure_new ("video/x-raw-rgb",
444 "width", G_TYPE_INT, 384,
445 "height", G_TYPE_INT, 288,
446 "framerate", G_TYPE_DOUBLE, 25.,
450 gst_pad_link_filtered (one, other, caps);
454 See the API references for the full API of
455 <classname>GstStructure</classname> and
456 <classname>GstCaps</classname>.
461 <sect1 id="section-pads-ghost">
462 <title>Ghost pads</title>
464 You can see from <xref linkend="section-bin-noghost-img"/> how a bin
465 has no pads of its own. This is where "ghost pads" come into play.
467 <figure float="1" id="section-bin-noghost-img">
468 <title>Visualisation of a <ulink type="http"
469 url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
470 element without ghost pads</title>
473 <imagedata fileref="images/bin-element-noghost.ℑ"
479 A ghost pad is a pad from some element in the bin that can be
480 accessed directly from the bin as well. Compare it to a symbolic
481 link in UNIX filesystems. Using ghost pads on bins, the bin also
482 has a pad and can transparently be used as an element in other
486 <figure float="1" id="section-bin-ghost-img">
487 <title>Visualisation of a <ulink type="http"
488 url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
489 element with a ghost pad</title>
492 <imagedata fileref="images/bin-element-ghost.ℑ"
498 <xref linkend="section-bin-ghost-img"/> is a representation of a
499 ghost pad. The sink pad of element one is now also a pad of the bin.
500 Obviously, ghost pads can be added to any type of elements, not just
501 to a <classname>GstBin</classname>.
504 A ghostpad is created using the function
505 <function>gst_element_add_ghost_pad ()</function>:
512 GstElement *bin, *sink;
515 gst_init (&argc, &argv);
517 /* create element, add to bin, add ghostpad */
518 sink = gst_element_factory_make ("fakesink", "sink");
519 bin = gst_bin_new ("mybin");
520 gst_bin_add (GST_BIN (bin), sink);
521 gst_element_add_ghost_pad (bin,
522 gst_element_get_pad (sink, "sink"), "sink");
528 In the above example, the bin now also has a pad: the pad called
529 <quote>sink</quote> of the given element. The bin can, from here
530 on, be used as a substitute for the sink element. You could, for
531 example, link another element to the bin.