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 explicitly 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       <para>
 122         It is not uncommon to add elements to the pipeline only from within
 123         the "pad-added" or "new-decoded-pad" callback. If you do this, don't
 124         forget to set the state of the newly-added elements to the target
 125         state of the pipeline using
 126         <function>gst_element_set_state ()</function> or
 127         <function>gst_element_sync_state_with_parent ()</function>.
 128       </para>
 129     </sect2>
 130
 131     <sect2 id="section-pads-request">
 132       <title>Request pads</title>
 133       <para>
 134         An element can also have request pads. These pads are not created
 135         automatically but are only created on demand. This is very useful
 136         for multiplexers, aggregators and tee elements. Aggregators are
 137         elements that merge the content of several input streams together
 138         into one output stream. Tee elements are the reverse: they are
 139         elements that have one input stream and copy this stream to each
 140         of their output pads, which are created on request. Whenever an
 141         application needs another copy of the stream, it can simply request
 142         a new output pad from the tee element.
 143       </para>
 144       <para>
 145         The following piece of code shows how you can request a new output
 146         pad from a <quote>tee</quote> element:
 147       </para>
 148       <programlisting>
 149 static void
 150 some_function (GstElement *tee)
 151 {
 152   GstPad * pad;
 153   gchar *name;
 154
 155   pad = gst_element_get_request_pad (tee, "src%d");
 156   name = gst_pad_get_name (pad);
 157   g_print ("A new pad %s was created\n", name);
 158   g_free (name);
 159
 160   /* here, you would link the pad */
 161 [..]
 162
 163   /* and, after doing that, free our reference */
 164   gst_object_unref (GST_OBJECT (pad));
 165 }
 166       </programlisting>
 167       <para>
 168         The <function>gst_element_get_request_pad ()</function> method
 169         can be used to get a pad from the element based on the name of
 170         the pad template. It is also possible to request a pad that is
 171         compatible with another pad template. This is very useful if
 172         you want to link an element to a multiplexer element and you
 173         need to request a pad that is compatible. The method
 174         <function>gst_element_get_compatible_pad ()</function> can be
 175         used to request a compatible pad, as shown in the next example.
 176         It will request a compatible pad from an Ogg multiplexer from
 177         any input.
 178       </para>
 179       <programlisting>
 180 static void
 181 link_to_multiplexer (GstPad     *tolink_pad,
 182                      GstElement *mux)
 183 {
 184   GstPad *pad;
 185   gchar *srcname, *sinkname;
 186
 187   srcname = gst_pad_get_name (tolink_pad);
 188   pad = gst_element_get_compatible_pad (mux, tolink_pad);
 189   gst_pad_link (tolinkpad, pad);
 190   sinkname = gst_pad_get_name (pad);
 191   gst_object_unref (GST_OBJECT (pad));
 192
 193   g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
 194   g_free (sinkname);
 195   g_free (srcname);
 196 }
 197       </programlisting>
 198     </sect2>
 199   </sect1>
 200
 201   <sect1 id="section-caps">
 202     <title>Capabilities of a pad</title>
 203     <para>
 204       Since the pads play a very important role in how the element is
 205       viewed by the outside world, a mechanism is implemented to describe
 206       the data that can flow or currently flows through the pad by using
 207       capabilities. Here, we will briefly describe what capabilities are
 208       and how to use them, enough to get an understanding of the concept.
 209       For an in-depth look into capabilities and a list of all capabilities
 210       defined in &GStreamer;, see the <ulink type="http"
 211       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
 212       Writers Guide</ulink>.
 213     </para>
 214     <para>
 215       Capabilities are attached to pad templates and to pads. For pad
 216       templates, it will describe the types of media that may stream
 217       over a pad created from this template. For pads, it can either
 218       be a list of possible caps (usually a copy of the pad template's
 219       capabilities), in which case the pad is not yet negotiated, or it
 220       is the type of media that currently streams over this pad, in
 221       which case the pad has been negotiated already.
 222     </para>
 223
 224     <sect2 id="section-caps-structure">
 225       <title>Dissecting capabilities</title>
 226       <para>
 227         A pad's capabilities are described in a <classname>GstCaps</classname>
 228         object. Internally, a <ulink type="http"
 229         url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
 230         will contain one or more <ulink type="http"
 231         url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
 232         that will describe one media type. A negotiated pad will have
 233         capabilities set that contain exactly <emphasis>one</emphasis>
 234         structure. Also, this structure will contain only
 235         <emphasis>fixed</emphasis> values. These constraints are not
 236         true for unnegotiated pads or pad templates.
 237       </para>
 238       <para>
 239         As an example, below is a dump of the capabilities of the
 240         <quote>vorbisdec</quote> element, which you will get by running
 241         <command>gst-inspect vorbisdec</command>. You will see two pads:
 242         a source and a sink pad. Both of these pads are always available,
 243         and both have capabilities attached to them. The sink pad will
 244         accept vorbis-encoded audio data, with the mime-type
 245         <quote>audio/x-vorbis</quote>. The source pad will be used
 246         to send raw (decoded) audio samples to the next element, with
 247         a raw audio mime-type (in this case,
 248         <quote>audio/x-raw-float</quote>).  The source pad will also
 249         contain properties for the audio samplerate and the amount of
 250         channels, plus some more that you don't need to worry about
 251         for now.
 252       </para>
 253       <programlisting>
 254 Pad Templates:
 255   SRC template: 'src'
 256     Availability: Always
 257     Capabilities:
 258       audio/x-raw-float
 259                    rate: [ 8000, 50000 ]
 260                channels: [ 1, 2 ]
 261              endianness: 1234
 262                   width: 32
 263           buffer-frames: 0
 264
 265   SINK template: 'sink'
 266     Availability: Always
 267     Capabilities:
 268       audio/x-vorbis
 269       </programlisting>
 270     </sect2>
 271
 272     <sect2 id="section-caps-props">
 273       <title>Properties and values</title>
 274       <para>
 275         Properties are used to describe extra information for
 276         capabilities. A property consists of a key (a string) and
 277         a value. There are different possible value types that can be used:
 278       </para>
 279       <itemizedlist>
 280         <listitem>
 281           <para>
 282             Basic types, this can be pretty much any
 283             <classname>GType</classname> registered with Glib. Those
 284             properties indicate a specific, non-dynamic value for this
 285             property. Examples include:
 286           </para>
 287           <itemizedlist>
 288             <listitem>
 289               <para>
 290                 An integer value (<classname>G_TYPE_INT</classname>):
 291                 the property has this exact value.
 292               </para>
 293             </listitem>
 294             <listitem>
 295               <para>
 296                 A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
 297                 the property is either TRUE or FALSE.
 298               </para>
 299             </listitem>
 300             <listitem>
 301               <para>
 302                 A float value (<classname>G_TYPE_FLOAT</classname>):
 303                 the property has this exact floating point value.
 304               </para>
 305             </listitem>
 306             <listitem>
 307               <para>
 308                 A string value (<classname>G_TYPE_STRING</classname>):
 309                 the property contains a UTF-8 string.
 310               </para>
 311             </listitem>
 312             <listitem>
 313               <para>
 314                 A fraction value (<classname>GST_TYPE_FRACTION</classname>):
 315                 contains a fraction expressed by an integer numerator and
 316                 denominator.
 317               </para>
 318             </listitem>
 319           </itemizedlist>
 320         </listitem>
 321         <listitem>
 322           <para>
 323             Range types are <classname>GType</classname>s registered by
 324             &GStreamer; to indicate a range of possible values. They are
 325             used for indicating allowed audio samplerate values or
 326             supported video sizes. The two types defined in &GStreamer;
 327             are:
 328           </para>
 329           <itemizedlist>
 330            <listitem>
 331               <para>
 332                 An integer range value
 333                 (<classname>GST_TYPE_INT_RANGE</classname>): the property
 334                 denotes a range of possible integers, with a lower and an
 335                 upper boundary. The <quote>vorbisdec</quote> element, for
 336                 example, has a rate property that can be between 8000 and
 337                 50000.
 338               </para>
 339             </listitem>
 340             <listitem>
 341               <para>
 342                 A float range value
 343                 (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
 344                 denotes a range of possible floating point values, with a
 345                 lower and an upper boundary.
 346               </para>
 347             </listitem>
 348             <listitem>
 349               <para>
 350                 A fraction range value
 351                 (<classname>GST_TYPE_FRACTION_RANGE</classname>): the property
 352                 denotes a range of possible fraction values, with a
 353                 lower and an upper boundary.
 354               </para>
 355             </listitem>
 356           </itemizedlist>
 357         </listitem>
 358         <listitem>
 359           <para>
 360             A list value (<classname>GST_TYPE_LIST</classname>): the
 361             property can take any value from a list of basic values
 362             given in this list.
 363           </para>
 364           <para>
 365             Example: caps that express that either
 366             a sample rate of 44100 Hz and a sample rate of 48000 Hz
 367             is supported would use a list of integer values, with
 368             one value being 44100 and one value being 48000.
 369           </para>
 370         </listitem>
 371         <listitem>
 372           <para>
 373             An array value (<classname>GST_TYPE_ARRAY</classname>): the
 374             property is an array of values. Each value in the array is a
 375             full value on its own, too. All values in the array should be
 376             of the same elementary type. This means that an array can
 377             contain any combination of integers, lists of integers, integer
 378             ranges together, and the same for floats or strings, but it can
 379             not contain both floats and ints at the same time.
 380           </para>
 381           <para>
 382             Example: for audio where there are more than two channels involved
 383             the channel layout needs to be specified (for one and two channel
 384             audio the channel layout is implicit unless stated otherwise in the
 385             caps). So the channel layout would be an array of integer enum
 386             values where each enum value represents a loudspeaker position.
 387             Unlike a <classname>GST_TYPE_LIST</classname>, the values in an
 388             array will be interpreted as a whole.
 389           </para>
 390         </listitem>
 391       </itemizedlist>
 392     </sect2>
 393   </sect1>
 394
 395   <sect1 id="section-caps-api">
 396     <title>What capabilities are used for</title>
 397     <para>
 398       Capabilities (short: caps) describe the type of data that is streamed
 399       between two pads, or that one pad (template) supports. This makes them
 400       very useful for various purposes:
 401     </para>
 402     <itemizedlist>
 403       <listitem>
 404         <para>
 405           Autoplugging: automatically finding elements to link to a
 406           pad based on its capabilities. All autopluggers use this
 407           method.
 408         </para>
 409       </listitem>
 410       <listitem>
 411         <para>
 412           Compatibility detection: when two pads are linked, &GStreamer;
 413           can verify if the two pads are talking about the same media
 414           type. The process of linking two pads and checking if they
 415           are compatible is called <quote>caps negotiation</quote>.
 416         </para>
 417       </listitem>
 418       <listitem>
 419         <para>
 420           Metadata: by reading the capabilities from a pad, applications
 421           can provide information about the type of media that is being
 422           streamed over the pad, which is information about the stream
 423           that is currently being played back.
 424         </para>
 425       </listitem>
 426       <listitem>
 427         <para>
 428           Filtering: an application can use capabilities to limit the
 429           possible media types that can stream between two pads to a
 430           specific subset of their supported stream types. An application
 431           can, for example, use <quote>filtered caps</quote> to set a
 432           specific (fixed or non-fixed) video size that should stream
 433           between two pads. You will see an example of filtered caps
 434           later in this manual, in <xref linkend="section-data-spoof"/>.
 435           You can do caps filtering by inserting a capsfilter element into
 436           your pipeline and setting its <quote>caps</quote> property. Caps
 437           filters are often placed after converter elements like audioconvert,
 438           audioresample, ffmpegcolorspace or videoscale to force those
 439           converters to convert data to a specific output format at a
 440           certain point in a stream.
 441         </para>
 442       </listitem>
 443     </itemizedlist>
 444
 445     <sect2 id="section-caps-metadata">
 446       <title>Using capabilities for metadata</title>
 447       <para>
 448         A pad can have a set (i.e. one or more) of capabilities attached
 449         to it. Capabilities (<classname>GstCaps</classname>) are represented
 450         as an array of one or more <classname>GstStructure</classname>s, and
 451         each <classname>GstStructure</classname> is an array of fields where
 452         each field consists of a field name string (e.g. "width") and a
 453         typed value (e.g. <classname>G_TYPE_INT</classname> or
 454         <classname>GST_TYPE_INT_RANGE</classname>).
 455       </para>
 456       <para>
 457         Note that there is a distinct difference between the
 458         <emphasis>possible</emphasis> capabilities of a pad (ie. usually what
 459         you find as caps of pad templates as they are shown in gst-inspect),
 460         the <emphasis>allowed</emphasis> caps of a pad (can be the same as
 461         the pad's template caps or a subset of them, depending on the possible
 462         caps of the peer pad) and lastly <emphasis>negotiated</emphasis> caps
 463         (these describe the exact format of a stream or buffer and contain
 464         exactly one structure and have no variable bits like ranges or lists,
 465         ie. they are fixed caps).
 466       </para>
 467       <para>
 468         You can get values of properties in a set of capabilities
 469         by querying individual properties of one structure. You can get
 470         a structure from a caps using
 471         <function>gst_caps_get_structure ()</function> and the number of
 472         structures in a <classname>GstCaps</classname> using
 473         <function>gst_caps_get_size ()</function>.
 474       </para>
 475       <para>
 476         Caps are called <emphasis>simple caps</emphasis> when they contain
 477         only one structure, and <emphasis>fixed caps</emphasis> when they
 478         contain only one structure and have no variable field types (like
 479         ranges or lists of possible values). Two other special types of caps
 480         are <emphasis>ANY caps</emphasis> and <emphasis>empty caps</emphasis>.
 481       </para>
 482       <para>
 483         Here is an example of how to extract the width and height from
 484         a set of fixed video caps:
 485       <programlisting>
 486 static void
 487 read_video_props (GstCaps *caps)
 488 {
 489   gint width, height;
 490   const GstStructure *str;
 491
 492   g_return_if_fail (gst_caps_is_fixed (caps));
 493
 494   str = gst_caps_get_structure (caps, 0);
 495   if (!gst_structure_get_int (str, "width", &amp;width) ||
 496       !gst_structure_get_int (str, "height", &amp;height)) {
 497     g_print ("No width/height available\n");
 498     return;
 499   }
 500
 501   g_print ("The video size of this set of capabilities is %dx%d\n",
 502            width, height);
 503 }
 504       </programlisting>
 505       </para>
 506     </sect2>
 507
 508     <sect2 id="section-caps-filter">
 509       <title>Creating capabilities for filtering</title>
 510       <para>
 511         While capabilities are mainly used inside a plugin to describe the
 512         media type of the pads, the application programmer often also has
 513         to have basic understanding of capabilities in order to interface
 514         with the plugins, especially when using filtered caps. When you're
 515         using filtered caps or fixation, you're limiting the allowed types of
 516         media that can stream between two pads to a subset of their supported
 517         media types. You do this using a <classname>capsfilter</classname>
 518         element in your pipeline. In order to do this, you also need to
 519         create your own <classname>GstCaps</classname>. The easiest way to
 520         do this is by using the convenience function
 521         <function>gst_caps_new_simple ()</function>:
 522       </para>
 523       <para>
 524       <programlisting>
 525 static gboolean
 526 link_elements_with_filter (GstElement *element1, GstElement *element2)
 527 {
 528   gboolean link_ok;
 529   GstCaps *caps;
 530
 531   caps = gst_caps_new_simple ("video/x-raw-yuv",
 532               "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
 533               "width", G_TYPE_INT, 384,
 534               "height", G_TYPE_INT, 288,
 535               "framerate", GST_TYPE_FRACTION, 25, 1,
 536               NULL);
 537
 538   link_ok = gst_element_link_filtered (element1, element2, caps);
 539   gst_caps_unref (caps);
 540
 541   if (!link_ok) {
 542     g_warning ("Failed to link element1 and element2!");
 543   }
 544
 545   return link_ok;
 546 }
 547       </programlisting>
 548       This will force the data flow between those two elements to
 549       a certain video format, width, height and framerate (or the linking
 550       will fail if that cannot be achieved in the context of the elements
 551       involved). Keep in mind that when you use <function>
 552       gst_element_link_filtered ()</function> it will automatically create
 553       a <classname>capsfilter</classname> element for you and insert it into
 554       your bin or pipeline between the two elements you want to connect (this
 555       is important if you ever want to disconnect those elements because then
 556       you will have to disconnect both elements from the capsfilter instead).
 557       </para>
 558       <para>
 559         In some cases, you will want to create a more elaborate set of
 560         capabilities to filter a link between two pads. Then, this function
 561         is too simplistic and you'll want to use the method
 562         <function>gst_caps_new_full ()</function>:
 563       </para>
 564       <programlisting>
 565 static gboolean
 566 link_elements_with_filter (GstElement *element1, GstElement *element2)
 567 {
 568   gboolean link_ok;
 569   GstCaps *caps;
 570
 571   caps = gst_caps_new_full (
 572       gst_structure_new ("video/x-raw-yuv",
 573                          "width", G_TYPE_INT, 384,
 574                          "height", G_TYPE_INT, 288,
 575                          "framerate", GST_TYPE_FRACTION, 25, 1,
 576                          NULL),
 577       gst_structure_new ("video/x-raw-rgb",
 578                          "width", G_TYPE_INT, 384,
 579                          "height", G_TYPE_INT, 288,
 580                          "framerate", GST_TYPE_FRACTION, 25, 1,
 581                          NULL),
 582       NULL);
 583
 584   link_ok = gst_element_link_filtered (element1, element2, caps);
 585   gst_caps_unref (caps);
 586
 587   if (!link_ok) {
 588     g_warning ("Failed to link element1 and element2!");
 589   }
 590
 591   return link_ok;
 592 }
 593       </programlisting>
 594       <para>
 595         See the API references for the full API of
 596         <ulink type="http"
 597           url="&URLAPI;GstStructure.html"><classname>GstStructure</classname></ulink>
 598         and <ulink type="http"
 599           url="&URLAPI;GstCaps.html"><classname>GstCaps</classname></ulink>.
 600       </para>
 601     </sect2>
 602   </sect1>
 603
 604   <sect1 id="section-pads-ghost">
 605     <title>Ghost pads</title>
 606     <para>
 607       You can see from <xref linkend="section-bin-noghost-img"/> how a bin
 608       has no pads of its own. This is where "ghost pads" come into play.
 609     </para>
 610     <figure float="1" id="section-bin-noghost-img">
 611       <title>Visualisation of a <ulink type="http"
 612       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 613       element without ghost pads</title>
 614       <mediaobject>
 615         <imageobject>
 616           <imagedata scale="75" fileref="images/bin-element-noghost.&image;"
 617           format="&IMAGE;"/>
 618         </imageobject>
 619       </mediaobject>
 620     </figure>
 621     <para>
 622       A ghost pad is a pad from some element in the bin that can be
 623       accessed directly from the bin as well. Compare it to a symbolic
 624       link in UNIX filesystems. Using ghost pads on bins, the bin also
 625       has a pad and can transparently be used as an element in other
 626       parts of your code.
 627     </para>
 628
 629     <figure float="1" id="section-bin-ghost-img">
 630       <title>Visualisation of a <ulink type="http"
 631       url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 632       element with a ghost pad</title>
 633       <mediaobject>
 634         <imageobject>
 635           <imagedata scale="75" fileref="images/bin-element-ghost.&image;"
 636           format="&IMAGE;"/>
 637         </imageobject>
 638       </mediaobject>
 639     </figure>
 640     <para>
 641       <xref linkend="section-bin-ghost-img"/> is a representation of a
 642       ghost pad. The sink pad of element one is now also a pad of the bin.
 643       Because ghost pads look and work like any other pads, they can be added
 644       to any type of elements, not just to a <classname>GstBin</classname>,
 645       just like ordinary pads.
 646     </para>
 647     <para>
 648       A ghostpad is created using the function
 649       <function>gst_ghost_pad_new ()</function>:
 650     </para>
 651     <programlisting><!-- example-begin ghostpad.c a -->
 652 #include &lt;gst/gst.h&gt;
 653
 654 int
 655 main (int   argc,
 656       char *argv[])
 657 {
 658   GstElement *bin, *sink;
 659   GstPad *pad;
 660
 661   /* init */
 662   gst_init (&amp;argc, &amp;argv);
 663
 664   /* create element, add to bin */
 665   sink = gst_element_factory_make ("fakesink", "sink");
 666   bin = gst_bin_new ("mybin");
 667   gst_bin_add (GST_BIN (bin), sink);
 668
 669   /* add ghostpad */
 670   pad = gst_element_get_static_pad (sink, "sink");
 671   gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
 672   gst_object_unref (GST_OBJECT (pad));
 673 <!-- example-end ghostpad.c a -->
 674 [..]<!-- example-begin ghostpad.c b --><!--
 675   return 0;
 676 --><!-- example-end ghostpad.c b -->
 677 <!-- example-begin ghostpad.c c -->
 678 }
 679     <!-- example-end ghostpad.c c --></programlisting>
 680     <para>
 681       In the above example, the bin now also has a pad: the pad called
 682       <quote>sink</quote> of the given element. The bin can, from here
 683       on, be used as a substitute for the sink element. You could, for
 684       example, link another element to the bin.
 685     </para>
 686   </sect1>
 687 </chapter>