docs/manual/basics-pads.xml

   1 <chapter id="chapter-pads" xreflabel="Pads and capabilities">
   2   <title>Pads and capabilities</title>
   3   <para>
   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"/>).
  10   </para>
  11
  12   <sect1 id="section-pads">
  13     <title>Pads</title>
  14     <para>
  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.
  23       <footnote>
  24         <para>
  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
  29           another.
  30         </para>
  31       </footnote>
  32     </para>
  33
  34     <para>
  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.
  41     </para>
  42
  43     <sect2 id="section-pads-dynamic">
  44       <title>Dynamic (or sometimes) pads</title>
  45       <para>
  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.
  53       </para>
  54       <para>
  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:
  65       </para>
  66       <programlisting><!-- example-begin pad.c a -->
  67 #include &lt;gst/gst.h&gt;
  68
  69 static void
  70 cb_new_pad (GstElement *element,
  71             GstPad     *pad,
  72             gpointer    data)
  73 {
  74   g_print ("A new pad %s was created\n", gst_pad_get_name (pad));
  75
  76   /* here, you would setup a new pad link for the newly created pad */
  77 <!-- example-end pad.c a -->[..]
  78 <!-- example-begin pad.c b -->
  79 }
  80
  81 int
  82 main(int argc, char *argv[])
  83 {
  84   GstElement *pipeline, *source, *demux;
  85
  86   /* init */
  87   gst_init (&amp;argc, &amp;argv);
  88
  89   /* create elements */
  90   pipeline = gst_pipeline_new ("my_pipeline");
  91   source = gst_element_factory_make ("filesrc", "source");
  92   g_object_set (source, "location", argv[1], NULL);
  93   demux = gst_element_factory_make ("oggdemux", "demuxer");
  94
  95   /* you would normally check that the elements were created properly */
  96
  97   /* put together a pipeline */
  98   gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
  99   gst_element_link (source, demux);
 100
 101   /* listen for newly created pads */
 102   g_signal_connect (demux, "new-pad", G_CALLBACK (cb_new_pad), NULL);
 103
 104   /* start the pipeline */
 105   gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
 106   while (gst_bin_iterate (GST_BIN (pipeline)));
 107 <!--example-end pad.c b -->
 108 [..]<!-- example-begin pad.c c --><!--
 109   return 0;
 110 --><!-- example-end pad.c c -->
 111 <!-- example-begin pad.c d -->
 112 }
 113       <!-- example-end pad.c d --></programlisting>
 114     </sect2>
 115
 116     <sect2 id="section-pads-request">
 117       <title>Request pads</title>
 118       <para>
 119         An element can also have request pads. These pads are not created
 120         automatically but are only created on demand. This is very useful
 121         for multiplexers, aggregators and tee elements. Aggregators are
 122         elements that merge the content of several input streams together
 123         into one output stream. Tee elements are the reverse: they are
 124         elements that have one input stream and copy this stream to each
 125         of their output pads, which are created on request. Whenever an
 126         application needs another copy of the stream, it can simply request
 127         a new output pad from the tee element.
 128       </para>
 129       <para>
 130         The following piece of code shows how you can request a new output
 131         pad from a <quote>tee</quote> element:
 132       </para>
 133       <programlisting>
 134 static void
 135 some_function (GstElement *tee)
 136 {
 137   GstPad * pad;
 138
 139   pad = gst_element_get_request_pad (tee, "src%d");
 140   g_print ("A new pad %s was created\n", gst_pad_get_name (pad));
 141
 142   /* here, you would link the pad */
 143 [..]
 144 }
 145       </programlisting>
 146       <para>
 147         The <function>gst_element_get_request_pad ()</function> method
 148         can be used to get a pad from the element based on the name of
 149         the pad template. It is also possible to request a pad that is
 150         compatible with another pad template. This is very useful if
 151         you want to link an element to a multiplexer element and you
 152         need to request a pad that is compatible. The method
 153         <function>gst_element_get_compatible_pad ()</function> can be
 154         used to request a compatible pad, as shown in the next example.
 155         It will request a compatible pad from an Ogg multiplexer from
 156         any input.
 157       </para>
 158       <programlisting>
 159 static void
 160 link_to_multiplexer (GstPad     *tolink_pad,
 161                      GstElement *mux)
 162 {
 163   GstPad *pad;
 164
 165   pad = gst_element_get_compatible_pad (mux, tolink_pad);
 166   gst_pad_link (tolinkpad, pad);
 167
 168   g_print ("A new pad %s was created and linked to %s\n",
 169            gst_pad_get_name (pad), gst_pad_get_name (tolink_pad));
 170 }
 171       </programlisting>
 172     </sect2>
 173   </sect1>
 174
 175   <sect1 id="section-caps">
 176     <title>Capabilities of a pad</title>
 177     <para>
 178       Since the pads play a very important role in how the element is
 179       viewed by the outside world, a mechanism is implemented to describe
 180       the data that can flow or currently flows through the pad by using
 181       capabilities. Here,w e will briefly describe what capabilities are
 182       and how to use them, enough to get an understanding of the concept.
 183       For an in-depth look into capabilities and a list of all capabilities
 184       defined in &GStreamer;, see the <ulink type="http"
 185       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
 186       Writers Guide</ulink>.
 187     </para>
 188     <para>
 189       Capabilities are attached to pad templates and to pads. For pad
 190       templates, it will describe the types of media that may stream
 191       over a pad created from this template. For pads, it can either
 192       be a list of possible caps (usually a copy of the pad template's
 193       capabilities), in which case the pad is not yet negotiated, or it
 194       is the type of media that currently streams over this pad, in
 195       which case the pad has been negotiated already.
 196     </para>
 197
 198     <sect2 id="section-caps-structure">
 199       <title>Dissecting capabilities</title>
 200       <para>
 201         A pads capabilities are described in a <classname>GstCaps</classname>
 202         object. Internally, a <ulink type="http"
 203         url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
 204         will contain one or more <ulink type="http"
 205         url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
 206         that will describe one media type. A negotiated pad will have
 207         capabilities set that contain exactly <emphasis>one</emphasis>
 208         structure. Also, this structure will contain only
 209         <emphasis>fixed</emphasis> values. These constraints are not
 210         true for unnegotiated pads or pad templates.
 211       </para>
 212       <para>
 213         As an example, below is a dump of the capabilities of the
 214         <quote>vorbisdec</quote> element, which you will get by running
 215         <command>gst-inspect vorbisdec</command>. You will see two pads:
 216         a source and a sink pad. Both of these pads are always available,
 217         and both have capabilities attached to them. The sink pad will
 218         accept vorbis-encoded audio data, with the mime-type
 219         <quote>audio/x-vorbis</quote>. The source pad will be used
 220         to send raw (decoded) audio samples to the next element, with
 221         a raw audio mime-type (either <quote>audio/x-raw-int</quote> or
 222         <quote>audio/x-raw-float</quote>). The source pad will also
 223         contain properties for the audio samplerate and the amount of
 224         channels, plus some more that you don't need to worry about
 225         for now.
 226       </para>
 227       <programlisting>
 228 Pad Templates:
 229   SRC template: 'src'
 230     Availability: Always
 231     Capabilities:
 232       audio/x-raw-float
 233                    rate: [ 8000, 50000 ]
 234                channels: [ 1, 2 ]
 235              endianness: 1234
 236                   width: 32
 237           buffer-frames: 0
 238
 239   SINK template: 'sink'
 240     Availability: Always
 241     Capabilities:
 242       audio/x-vorbis
 243       </programlisting>
 244     </sect2>
 245
 246     <sect2 id="section-caps-props">
 247       <title>Properties and values</title>
 248       <para>
 249         Properties are used to describe extra information for
 250         capabilities. A property consists of a key (a string) and
 251         a value. There are different possible value types that can be used:
 252       </para>
 253       <itemizedlist>
 254         <listitem>
 255           <para>
 256             Basic types, this can be pretty much any
 257             <classname>GType</classname> registered with Glib. Those
 258             properties indicate a specific, non-dynamic value for this
 259             property. Examples include:
 260           </para>
 261           <itemizedlist>
 262             <listitem>
 263               <para>
 264                 An integer value (<classname>G_TYPE_INT</classname>):
 265                 the property has this exact value.
 266               </para>
 267             </listitem>
 268             <listitem>
 269               <para>
 270                 A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
 271                 the property is either TRUE or FALSE.
 272               </para>
 273             </listitem>
 274             <listitem>
 275               <para>
 276                 A float value (<classname>G_TYPE_FLOAT</classname>):
 277                 the property has this exact floating point value.
 278               </para>
 279             </listitem>
 280             <listitem>
 281               <para>
 282                 A string value (<classname>G_TYPE_STRING</classname>):
 283                 the property contains a UTF-8 string.
 284               </para>
 285             </listitem>
 286           </itemizedlist>
 287         </listitem>
 288         <listitem>
 289           <para>
 290             Range types are <classname>GType</classname>s registered by
 291             &GStreamer; to indicate a range of possible values. They are
 292             used for indicating allowed audio samplerate values or
 293             supported video sizes. The two types defined in &GStreamer;
 294             are:
 295           </para>
 296           <itemizedlist>
 297            <listitem>
 298               <para>
 299                 An integer range value
 300                 (<classname>GST_TYPE_INT_RANGE</classname>): the property
 301                 denotes a range of possible integers, with a lower and an
 302                 upper boundary. The <quote>vorbisdec</quote> element, for
 303                 example, has a rate property that can be between 8000 and
 304                 50000.
 305               </para>
 306             </listitem>
 307             <listitem>
 308               <para>
 309                 A float range value
 310                 (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
 311                 denotes a range of possible floating point values, with a
 312                 lower and an upper boundary.
 313               </para>
 314             </listitem>
 315           </itemizedlist>
 316         </listitem>
 317         <listitem>
 318           <para>
 319             A list value (<classname>GST_TYPE_LIST</classname>): the
 320             property can take any value from a list of basic values
 321             given in this list.
 322           </para>
 323         </listitem>
 324       </itemizedlist>
 325     </sect2>
 326   </sect1>
 327
 328   <sect1 id="section-caps-api">
 329     <title>What capabilities are used for</title>
 330     <para>
 331       Capabilities describe the type of data that is streamed between
 332       two pads, or that one pad (template) supports. This makes them
 333       very useful for various purposes:
 334     </para>
 335     <itemizedlist>
 336       <listitem>
 337         <para>
 338           Autoplugging: automatically finding elements to link to a
 339           pad based on its capabilities. All autopluggers use this
 340           method.
 341         </para>
 342       </listitem>
 343       <listitem>
 344         <para>
 345           Compatibility detection: when two pads are linked, &GStreamer;
 346           can verify if the two pads are talking about the same media
 347           type. The process of linking two pads and checking if they
 348           are compatible is called <quote>caps negotiation</quote>.
 349         </para>
 350       </listitem>
 351       <listitem>
 352         <para>
 353           Metadata: by reading the capabilities from a pad, applications
 354           can provide information about the type of media that is being
 355           streamed over the pad, which is information about the stream
 356           thatis currently being played back.
 357         </para>
 358       </listitem>
 359       <listitem>
 360         <para>
 361           Filtering: an application can use capabilities to limit the
 362           possible media types that can stream between two pads to a
 363           specific subset of their supported stream types. An application
 364           can, for example, use <quote>filtered caps</quote> to set a
 365           specific (non-fixed) video size that will stream between two
 366           pads.
 367         </para>
 368       </listitem>
 369     </itemizedlist>
 370
 371     <sect2 id="section-caps-metadata">
 372       <title>Using capabilities for metadata</title>
 373       <para>
 374         A pad can have a set (i.e. one or more) of capabilities attached
 375         to it. You can get values of properties in a set of capabilities
 376         by querying individual properties of one structure. You can get
 377         a structure from a caps using
 378         <function>gst_caps_get_structure ()</function>:
 379       </para>
 380       <programlisting>
 381 static void
 382 read_video_props (GstCaps *caps)
 383 {
 384   gint width, height;
 385   const GstStructure *str;
 386
 387   str = gst_caps_get_structure (caps);
 388   if (!gst_structure_get_int (str, "width", &amp;width) ||
 389       !gst_structure_get_int (str, "height", &amp;height)) {
 390     g_print ("No width/height available\n");
 391     return;
 392   }
 393
 394   g_print ("The video size of this set of capabilities is %dx%d\n",
 395            width, height);
 396 }
 397       </programlisting>
 398     </sect2>
 399
 400     <sect2 id="section-caps-filter">
 401       <title>Creating capabilities for filtering</title>
 402       <para>
 403         While capabilities are mainly used inside a plugin to describe the
 404         media type of the pads, the application programmer also has to have
 405         basic understanding of capabilities in order to interface with the
 406         plugins, especially when using filtered caps. When you're using
 407         filtered caps or fixation, you're limiting the allowed types of
 408         media that can stream between two pads to a subset of their supported
 409         media types. You do this by filtering using your own set of
 410         capabilities. In order to do this, you need to create your own
 411         <classname>GstCaps</classname>. The simplest way to do this is by
 412         using the convenience function <function>gst_caps_new_simple
 413         ()</function>:
 414       </para>
 415       <programlisting>
 416 static void
 417 link_pads_with_filter (GstPad *one,
 418                        GstPad *other)
 419 {
 420   GstCaps *caps;
 421
 422   caps = gst_caps_new_simple ("video/x-raw-yuv",
 423                               "width", G_TYPE_INT, 384,
 424                               "height", G_TYPE_INT, 288,
 425                               "framerate", G_TYPE_DOUBLE, 25.,
 426                               NULL);
 427   gst_pad_link_filtered (one, other, caps);
 428 }
 429       </programlisting>
 430       <para>
 431         In some cases, you will want to create a more elaborate set of
 432         capabilities to filter a link between two pads. Then, this function
 433         is too simplistic and you'll want to use the method
 434         <function>gst_caps_new_full ()</function>:
 435       </para>
 436       <programlisting>
 437 static void
 438 link_pads_with_filter (GstPad *one,
 439                        GstPad *other)
 440 {
 441   GstCaps *caps;
 442
 443   caps = gst_caps_new_full (
 444       gst_structure_new ("video/x-raw-yuv",
 445                          "width", G_TYPE_INT, 384,
 446                          "height", G_TYPE_INT, 288,
 447                          "framerate", G_TYPE_DOUBLE, 25.,
 448                          NULL),
 449       gst_structure_new ("video/x-raw-rgb",
 450                          "width", G_TYPE_INT, 384,
 451                          "height", G_TYPE_INT, 288,
 452                          "framerate", G_TYPE_DOUBLE, 25.,
 453                          NULL),
 454       NULL);
 455
 456   gst_pad_link_filtered (one, other, caps);
 457 }
 458       </programlisting>
 459       <para>
 460         See the API references for the full API of
 461         <classname>GstStructure</classname> and
 462         <classname>GstCaps</classname>.
 463       </para>
 464     </sect2>
 465   </sect1>
 466
 467   <sect1 id="section-pads-ghost">
 468     <title>Ghost pads</title>
 469     <para>
 470       You can see from <xref linkend="section-bin-noghost-img"/> how a bin
 471       has no pads of its own. This is where "ghost pads" come into play.
 472     </para>
 473     <figure float="1" id="section-bin-noghost-img">
 474       <title>Visualisation of a <ulink type="http"
 475       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 476       element without ghost pads</title>
 477       <mediaobject>
 478         <imageobject>
 479           <imagedata fileref="images/bin-element-noghost.&image;"
 480           format="&IMAGE;"/>
 481         </imageobject>
 482       </mediaobject>
 483     </figure>
 484     <para>
 485       A ghost pad is a pad from some element in the bin that can be
 486       accessed directly from the bin as well. Compare it to a symbolic
 487       link in UNIX filesystems. Using ghost pads on bins, the bin also
 488       has a pad and can transparently be used as an element in other
 489       parts of your code.
 490     </para>
 491
 492     <figure float="1" id="section-bin-ghost-img">
 493       <title>Visualisation of a <ulink type="http"
 494       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 495       element with a ghost pad</title>
 496       <mediaobject>
 497         <imageobject>
 498           <imagedata fileref="images/bin-element-ghost.&image;"
 499           format="&IMAGE;"/>
 500         </imageobject>
 501       </mediaobject>
 502     </figure>
 503     <para>
 504       <xref linkend="section-bin-ghost-img"/> is a representation of a
 505       ghost pad. The sink pad of element one is now also a pad of the bin.
 506       Obviously, ghost pads can be added to any type of elements, not just
 507       to a <classname>GstBin</classname>.
 508     </para>
 509     <para>
 510       A ghostpad is created using the function
 511       <function>gst_element_add_ghost_pad ()</function>:
 512     </para>
 513     <programlisting><!-- example-begin ghostpad.c a -->
 514 #include &lt;gst/gst.h&gt;
 515
 516 int
 517 main (int   argc,
 518       char *argv[])
 519 {
 520   GstElement *bin, *sink;
 521
 522   /* init */
 523   gst_init (&amp;argc, &amp;argv);
 524
 525   /* create element, add to bin, add ghostpad */
 526   sink = gst_element_factory_make ("fakesink", "sink");
 527   bin = gst_bin_new ("mybin");
 528   gst_bin_add (GST_BIN (bin), sink);
 529   gst_element_add_ghost_pad (bin,
 530       gst_element_get_pad (sink, "sink"), "sink");
 531 <!-- example-end ghostpad.c a -->
 532 [..]<!-- example-begin ghostpad.c b --><!--
 533   return 0;
 534 --><!-- example-end ghostpad.c b -->
 535 <!-- example-begin ghostpad.c c -->
 536 }
 537     <!-- example-end ghostpad.c c --></programlisting>
 538     <para>
 539       In the above example, the bin now also has a pad: the pad called
 540       <quote>sink</quote> of the given element. The bin can, from here
 541       on, be used as a substitute for the sink element. You could, for
 542       example, link another element to the bin.
 543     </para>
 544   </sect1>
 545 </chapter>