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   gchar *name;
  75
  76   name = gst_pad_get_name (pad);
  77   g_print ("A new pad %s was created\n", name);
  78   g_free (name);
  79
  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 -->
  83 }
  84
  85 int
  86 main (int   argc,
  87       char *argv[])
  88 {
  89   GstElement *pipeline, *source, *demux;
  90   GMainLoop *loop;
  91
  92   /* init */
  93   gst_init (&amp;argc, &amp;argv);
  94
  95   /* create elements */
  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");
 100
 101   /* you would normally check that the elements were created properly */
 102
 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");
 106
 107   /* listen for newly created pads */
 108   g_signal_connect (demux, "pad-added", G_CALLBACK (cb_new_pad), NULL);
 109
 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 --><!--
 116   return 0;
 117 --><!-- example-end pad.c c -->
 118 <!-- example-begin pad.c d -->
 119 }
 120       <!-- example-end pad.c d --></programlisting>
 121     </sect2>
 122
 123     <sect2 id="section-pads-request">
 124       <title>Request pads</title>
 125       <para>
 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.
 135       </para>
 136       <para>
 137         The following piece of code shows how you can request a new output
 138         pad from a <quote>tee</quote> element:
 139       </para>
 140       <programlisting>
 141 static void
 142 some_function (GstElement *tee)
 143 {
 144   GstPad * pad;
 145   gchar *name;
 146
 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);
 150   g_free (name);
 151
 152   /* here, you would link the pad */
 153 [..]
 154
 155   /* and, after doing that, free our reference */
 156   gst_object_unref (GST_OBJECT (pad));
 157 }
 158       </programlisting>
 159       <para>
 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
 169         any input.
 170       </para>
 171       <programlisting>
 172 static void
 173 link_to_multiplexer (GstPad     *tolink_pad,
 174                      GstElement *mux)
 175 {
 176   GstPad *pad;
 177   gchar *srcname = gst_pad_get_name (tolink_pad), *sinkname;
 178
 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));
 183
 184   g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
 185   g_free (sinkname);
 186   g_free (srcname);
 187 }
 188       </programlisting>
 189     </sect2>
 190   </sect1>
 191
 192   <sect1 id="section-caps">
 193     <title>Capabilities of a pad</title>
 194     <para>
 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, we 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>.
 204     </para>
 205     <para>
 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.
 213     </para>
 214
 215     <sect2 id="section-caps-structure">
 216       <title>Dissecting capabilities</title>
 217       <para>
 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.
 228       </para>
 229       <para>
 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
 242         for now.
 243       </para>
 244       <programlisting>
 245 Pad Templates:
 246   SRC template: 'src'
 247     Availability: Always
 248     Capabilities:
 249       audio/x-raw-float
 250                    rate: [ 8000, 50000 ]
 251                channels: [ 1, 2 ]
 252              endianness: 1234
 253                   width: 32
 254           buffer-frames: 0
 255
 256   SINK template: 'sink'
 257     Availability: Always
 258     Capabilities:
 259       audio/x-vorbis
 260       </programlisting>
 261     </sect2>
 262
 263     <sect2 id="section-caps-props">
 264       <title>Properties and values</title>
 265       <para>
 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:
 269       </para>
 270       <itemizedlist>
 271         <listitem>
 272           <para>
 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:
 277           </para>
 278           <itemizedlist>
 279             <listitem>
 280               <para>
 281                 An integer value (<classname>G_TYPE_INT</classname>):
 282                 the property has this exact value.
 283               </para>
 284             </listitem>
 285             <listitem>
 286               <para>
 287                 A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
 288                 the property is either TRUE or FALSE.
 289               </para>
 290             </listitem>
 291             <listitem>
 292               <para>
 293                 A float value (<classname>G_TYPE_FLOAT</classname>):
 294                 the property has this exact floating point value.
 295               </para>
 296             </listitem>
 297             <listitem>
 298               <para>
 299                 A string value (<classname>G_TYPE_STRING</classname>):
 300                 the property contains a UTF-8 string.
 301               </para>
 302             </listitem>
 303           </itemizedlist>
 304         </listitem>
 305         <listitem>
 306           <para>
 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;
 311             are:
 312           </para>
 313           <itemizedlist>
 314            <listitem>
 315               <para>
 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
 321                 50000.
 322               </para>
 323             </listitem>
 324             <listitem>
 325               <para>
 326                 A float range value
 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.
 330               </para>
 331             </listitem>
 332           </itemizedlist>
 333         </listitem>
 334         <listitem>
 335           <para>
 336             A list value (<classname>GST_TYPE_LIST</classname>): the
 337             property can take any value from a list of basic values
 338             given in this list.
 339           </para>
 340         </listitem>
 341         <listitem>
 342           <para>
 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.
 350           </para>
 351         </listitem>
 352       </itemizedlist>
 353     </sect2>
 354   </sect1>
 355
 356   <sect1 id="section-caps-api">
 357     <title>What capabilities are used for</title>
 358     <para>
 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:
 362     </para>
 363     <itemizedlist>
 364       <listitem>
 365         <para>
 366           Autoplugging: automatically finding elements to link to a
 367           pad based on its capabilities. All autopluggers use this
 368           method.
 369         </para>
 370       </listitem>
 371       <listitem>
 372         <para>
 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>.
 377         </para>
 378       </listitem>
 379       <listitem>
 380         <para>
 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           that is currently being played back.
 385         </para>
 386       </listitem>
 387       <listitem>
 388         <para>
 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
 394           pads. You will see an example of filtered caps further on in
 395           this manual, in <xref linkend="section-data-spoof"/>.
 396         </para>
 397       </listitem>
 398     </itemizedlist>
 399
 400     <sect2 id="section-caps-metadata">
 401       <title>Using capabilities for metadata</title>
 402       <para>
 403         A pad can have a set (i.e. one or more) of capabilities attached
 404         to it. You can get values of properties in a set of capabilities
 405         by querying individual properties of one structure. You can get
 406         a structure from a caps using
 407         <function>gst_caps_get_structure ()</function>:
 408       </para>
 409       <programlisting>
 410 static void
 411 read_video_props (GstCaps *caps)
 412 {
 413   gint width, height;
 414   const GstStructure *str;
 415
 416   str = gst_caps_get_structure (caps);
 417   if (!gst_structure_get_int (str, "width", &amp;width) ||
 418       !gst_structure_get_int (str, "height", &amp;height)) {
 419     g_print ("No width/height available\n");
 420     return;
 421   }
 422
 423   g_print ("The video size of this set of capabilities is %dx%d\n",
 424            width, height);
 425 }
 426       </programlisting>
 427     </sect2>
 428
 429     <sect2 id="section-caps-filter">
 430       <title>Creating capabilities for filtering</title>
 431       <para>
 432         While capabilities are mainly used inside a plugin to describe the
 433         media type of the pads, the application programmer also has to have
 434         basic understanding of capabilities in order to interface with the
 435         plugins, especially when using filtered caps. When you're using
 436         filtered caps or fixation, you're limiting the allowed types of
 437         media that can stream between two pads to a subset of their supported
 438         media types. You do this by filtering using your own set of
 439         capabilities. In order to do this, you need to create your own
 440         <classname>GstCaps</classname>. The simplest way to do this is by
 441         using the convenience function <function>gst_caps_new_simple
 442         ()</function>:
 443       </para>
 444       <programlisting>
 445 static void
 446 link_pads_with_filter (GstPad *one,
 447                        GstPad *other)
 448 {
 449   GstCaps *caps;
 450
 451   caps = gst_caps_new_simple ("video/x-raw-yuv",
 452                               "width", G_TYPE_INT, 384,
 453                               "height", G_TYPE_INT, 288,
 454                               "framerate", GST_TYPE_FRACTION, 25, 1,
 455                               NULL);
 456   gst_pad_link_filtered (one, other, caps);
 457 }
 458       </programlisting>
 459       <para>
 460         In some cases, you will want to create a more elaborate set of
 461         capabilities to filter a link between two pads. Then, this function
 462         is too simplistic and you'll want to use the method
 463         <function>gst_caps_new_full ()</function>:
 464       </para>
 465       <programlisting>
 466 static void
 467 link_pads_with_filter (GstPad *one,
 468                        GstPad *other)
 469 {
 470   GstCaps *caps;
 471
 472   caps = gst_caps_new_full (
 473       gst_structure_new ("video/x-raw-yuv",
 474                          "width", G_TYPE_INT, 384,
 475                          "height", G_TYPE_INT, 288,
 476                          "framerate", GST_TYPE_FRACTION, 25, 1,
 477                          NULL),
 478       gst_structure_new ("video/x-raw-rgb",
 479                          "width", G_TYPE_INT, 384,
 480                          "height", G_TYPE_INT, 288,
 481                          "framerate", GST_TYPE_FRACTION, 25, 1,
 482                          NULL),
 483       NULL);
 484
 485   gst_pad_link_filtered (one, other, caps);
 486 }
 487       </programlisting>
 488       <para>
 489         See the API references for the full API of
 490         <classname>GstStructure</classname> and
 491         <classname>GstCaps</classname>.
 492       </para>
 493     </sect2>
 494   </sect1>
 495
 496   <sect1 id="section-pads-ghost">
 497     <title>Ghost pads</title>
 498     <para>
 499       You can see from <xref linkend="section-bin-noghost-img"/> how a bin
 500       has no pads of its own. This is where "ghost pads" come into play.
 501     </para>
 502     <figure float="1" id="section-bin-noghost-img">
 503       <title>Visualisation of a <ulink type="http"
 504       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 505       element without ghost pads</title>
 506       <mediaobject>
 507         <imageobject>
 508           <imagedata fileref="images/bin-element-noghost.&image;"
 509           format="&IMAGE;"/>
 510         </imageobject>
 511       </mediaobject>
 512     </figure>
 513     <para>
 514       A ghost pad is a pad from some element in the bin that can be
 515       accessed directly from the bin as well. Compare it to a symbolic
 516       link in UNIX filesystems. Using ghost pads on bins, the bin also
 517       has a pad and can transparently be used as an element in other
 518       parts of your code.
 519     </para>
 520
 521     <figure float="1" id="section-bin-ghost-img">
 522       <title>Visualisation of a <ulink type="http"
 523       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 524       element with a ghost pad</title>
 525       <mediaobject>
 526         <imageobject>
 527           <imagedata fileref="images/bin-element-ghost.&image;"
 528           format="&IMAGE;"/>
 529         </imageobject>
 530       </mediaobject>
 531     </figure>
 532     <para>
 533       <xref linkend="section-bin-ghost-img"/> is a representation of a
 534       ghost pad. The sink pad of element one is now also a pad of the bin.
 535       Obviously, ghost pads can be added to any type of elements, not just
 536       to a <classname>GstBin</classname>.
 537     </para>
 538     <para>
 539       A ghostpad is created using the function
 540       <function>gst_ghost_pad_new ()</function>:
 541     </para>
 542     <programlisting><!-- example-begin ghostpad.c a -->
 543 #include &lt;gst/gst.h&gt;
 544
 545 int
 546 main (int   argc,
 547       char *argv[])
 548 {
 549   GstElement *bin, *sink;
 550   GstPad *pad;
 551
 552   /* init */
 553   gst_init (&amp;argc, &amp;argv);
 554
 555   /* create element, add to bin */
 556   sink = gst_element_factory_make ("fakesink", "sink");
 557   bin = gst_bin_new ("mybin");
 558   gst_bin_add (GST_BIN (bin), sink);
 559
 560   /* add ghostpad */
 561   pad = gst_element_get_pad (sink, "sink");
 562   gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
 563   gst_object_unref (GST_OBJECT (pad));
 564 <!-- example-end ghostpad.c a -->
 565 [..]<!-- example-begin ghostpad.c b --><!--
 566   return 0;
 567 --><!-- example-end ghostpad.c b -->
 568 <!-- example-begin ghostpad.c c -->
 569 }
 570     <!-- example-end ghostpad.c c --></programlisting>
 571     <para>
 572       In the above example, the bin now also has a pad: the pad called
 573       <quote>sink</quote> of the given element. The bin can, from here
 574       on, be used as a substitute for the sink element. You could, for
 575       example, link another element to the bin.
 576     </para>
 577   </sect1>
 578 </chapter>