basics-pads.xml 26.9 KB
Newer Older
1 2
<chapter id="chapter-pads" xreflabel="Pads and capabilities">
  <title>Pads and capabilities</title>
3
  <para>
4 5 6 7 8 9
    As we have seen in <xref linkend="chapter-elements"/>, the pads are
    the element's interface to the outside world. Data streams from one
    element's source pad to another element's sink pad. The specific
    type of media that the element can handle will be exposed by the
    pad's capabilities. We will talk more on capabilities later in this
    chapter (see <xref linkend="section-caps"/>).
10 11
  </para>

12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
  <sect1 id="section-pads">
    <title>Pads</title>
    <para>
      A pad type is defined by two properties: its direction and its
      availability. As we've mentioned before, &GStreamer; defines two
      pad directions: source pads and sink pads. This terminology is
      defined from the view of within the element: elements receive data
      on their sink pads and generate data on their source pads.
      Schematically, sink pads are drawn on the left side of an element,
      whereas source pads are drawn on the right side of an element. In
      such graphs, data flows from left to right.
      <footnote>
        <para>
          In reality, there is no objection to data flowing from a
          source pad to the sink pad of an element upstream (to the
          left of this element in drawings). Data will, however, always
          flow from a source pad of one element to the sink pad of
          another.
        </para>
      </footnote>
    </para>

    <para>
      Pad directions are very simple compared to pad availability. A pad
      can have any of three availabilities: always, sometimes and on
      request. The meaning of those three types is exactly as it says:
      always pads always exist, sometimes pad exist only in certain
      cases (and can disappear randomly), and on-request pads appear
Piotr Fusik's avatar
Piotr Fusik committed
40
      only if explicitly requested by applications.
41
    </para>
42 43

    <sect2 id="section-pads-dynamic">
44 45
      <title>Dynamic (or sometimes) pads</title>
      <para>
46
        Some elements might not have all of their pads when the element is
47 48 49 50 51 52
        created. This can happen, for example, with an Ogg demuxer element.
        The element will read the Ogg stream and create dynamic pads for
        each contained elementary stream (vorbis, theora) when it detects
        such a stream in the Ogg stream. Likewise, it will delete the pad
        when the stream ends. This principle is very useful for demuxer
        elements, for example.
53 54
      </para> 
      <para> 
55 56 57 58 59 60 61 62 63 64
        Running <application>gst-inspect oggdemux</application> will show
        that the element has only one pad: a sink pad called 'sink'. The
        other pads are <quote>dormant</quote>. You can see this in the pad
        template because there is an <quote>Exists: Sometimes</quote>
	property. Depending on the type of Ogg file you play, the pads will
        be created. We will see that this is very important when you are
        going to create dynamic pipelines. You can attach a signal handler
        to an element to inform you when the element has created a new pad
        from one of its <quote>sometimes</quote> pad templates. The
        following piece of code is an example of how to do this:
65
      </para> 
66 67 68 69 70 71 72 73
      <programlisting><!-- example-begin pad.c a -->
#include &lt;gst/gst.h&gt;

static void
cb_new_pad (GstElement *element,
	    GstPad     *pad,
	    gpointer    data)
{
74 75 76 77 78
  gchar *name;

  name = gst_pad_get_name (pad);
  g_print ("A new pad %s was created\n", name);
  g_free (name);
79 80 81 82 83 84 85

  /* here, you would setup a new pad link for the newly created pad */
<!-- example-end pad.c a -->[..]
<!-- example-begin pad.c b -->
}

int 
86 87
main (int   argc,
      char *argv[]) 
88 89
{
  GstElement *pipeline, *source, *demux;
90
  GMainLoop *loop;
91 92 93 94 95 96 97 98 99 100 101 102 103 104

  /* init */
  gst_init (&amp;argc, &amp;argv);

  /* create elements */
  pipeline = gst_pipeline_new ("my_pipeline");
  source = gst_element_factory_make ("filesrc", "source");
  g_object_set (source, "location", argv[1], NULL);
  demux = gst_element_factory_make ("oggdemux", "demuxer");

  /* you would normally check that the elements were created properly */

  /* put together a pipeline */
  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 111

  /* start the pipeline */
  gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
112 113
  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);
114 115 116 117 118 119 120
<!--example-end pad.c b -->
[..]<!-- example-begin pad.c c --><!--
  return 0;
--><!-- example-end pad.c c -->
<!-- example-begin pad.c d -->
}
      <!-- example-end pad.c d --></programlisting>
121 122 123 124 125 126 127 128
      <para>
        It is not uncommon to add elements to the pipeline only from within
        the "pad-added" or "new-decoded-pad" callback. If you do this, don't
        forget to set the state of the newly-added elements to the target
        state of the pipeline using
        <function>gst_element_set_state ()</function> or
        <function>gst_element_sync_state_with_parent ()</function>.
      </para>
129
    </sect2>
130

131 132 133 134 135
    <sect2 id="section-pads-request">
      <title>Request pads</title>
      <para> 
        An element can also have request pads. These pads are not created
        automatically but are only created on demand. This is very useful
136 137 138 139 140 141 142
        for multiplexers, aggregators and tee elements. Aggregators are
        elements that merge the content of several input streams together
        into one output stream. Tee elements are the reverse: they are
        elements that have one input stream and copy this stream to each
        of their output pads, which are created on request. Whenever an
        application needs another copy of the stream, it can simply request
        a new output pad from the tee element.
143 144
      </para> 
      <para> 
145 146 147 148 149 150 151 152
        The following piece of code shows how you can request a new output
        pad from a <quote>tee</quote> element:
      </para>
      <programlisting>
static void
some_function (GstElement *tee)
{
  GstPad * pad;
153
  gchar *name;
154 155

  pad = gst_element_get_request_pad (tee, "src%d");
156 157 158
  name = gst_pad_get_name (pad);
  g_print ("A new pad %s was created\n", name);
  g_free (name);
159 160 161

  /* here, you would link the pad */
[..]
162 163 164

  /* and, after doing that, free our reference */
  gst_object_unref (GST_OBJECT (pad));
165 166 167 168 169 170 171 172 173 174 175 176 177
}
      </programlisting>
      <para> 
        The <function>gst_element_get_request_pad ()</function> method
        can be used to get a pad from the element based on the name of
        the pad template. It is also possible to request a pad that is
        compatible with another pad template. This is very useful if
        you want to link an element to a multiplexer element and you
        need to request a pad that is compatible. The method
        <function>gst_element_get_compatible_pad ()</function> can be
        used to request a compatible pad, as shown in the next example.
        It will request a compatible pad from an Ogg multiplexer from
        any input.
178
      </para> 
179 180 181 182 183 184
      <programlisting>
static void
link_to_multiplexer (GstPad     *tolink_pad,
		     GstElement *mux)
{
  GstPad *pad;
185
  gchar *srcname, *sinkname;
186

187
  srcname = gst_pad_get_name (tolink_pad);
188 189
  pad = gst_element_get_compatible_pad (mux, tolink_pad);
  gst_pad_link (tolinkpad, pad);
190 191
  sinkname = gst_pad_get_name (pad);
  gst_object_unref (GST_OBJECT (pad));
192

193 194 195
  g_print ("A new pad %s was created and linked to %s\n", srcname, sinkname);
  g_free (sinkname);
  g_free (srcname);
196 197 198
}
      </programlisting>
    </sect2>
199 200 201 202 203
  </sect1>

  <sect1 id="section-caps">
    <title>Capabilities of a pad</title>
    <para> 
204 205 206
      Since the pads play a very important role in how the element is
      viewed by the outside world, a mechanism is implemented to describe
      the data that can flow or currently flows through the pad by using
Wim Taymans's avatar
Wim Taymans committed
207
      capabilities. Here, we will briefly describe what capabilities are
208 209 210 211 212
      and how to use them, enough to get an understanding of the concept.
      For an in-depth look into capabilities and a list of all capabilities
      defined in &GStreamer;, see the <ulink type="http"
      url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
      Writers Guide</ulink>.
213
    </para>
214 215 216 217 218 219 220 221
    <para>
      Capabilities are attached to pad templates and to pads. For pad
      templates, it will describe the types of media that may stream
      over a pad created from this template. For pads, it can either
      be a list of possible caps (usually a copy of the pad template's
      capabilities), in which case the pad is not yet negotiated, or it
      is the type of media that currently streams over this pad, in
      which case the pad has been negotiated already.
222 223
    </para>

224 225
    <sect2 id="section-caps-structure">
      <title>Dissecting capabilities</title>
226
      <para>
227
        A pad's capabilities are described in a <classname>GstCaps</classname>
228 229 230 231 232 233 234 235 236
        object. Internally, a <ulink type="http"
        url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
        will contain one or more <ulink type="http"
        url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure</classname></ulink>
        that will describe one media type. A negotiated pad will have
        capabilities set that contain exactly <emphasis>one</emphasis>
        structure. Also, this structure will contain only
        <emphasis>fixed</emphasis> values. These constraints are not
        true for unnegotiated pads or pad templates.
237
      </para>
238 239 240 241 242 243 244 245 246
      <para>
        As an example, below is a dump of the capabilities of the
        <quote>vorbisdec</quote> element, which you will get by running
        <command>gst-inspect vorbisdec</command>. You will see two pads:
        a source and a sink pad. Both of these pads are always available,
        and both have capabilities attached to them. The sink pad will
        accept vorbis-encoded audio data, with the mime-type
        <quote>audio/x-vorbis</quote>. The source pad will be used
        to send raw (decoded) audio samples to the next element, with
247 248
        a raw audio mime-type (in this case,
	<quote>audio/x-raw-float</quote>).  The source pad will also
249 250 251
        contain properties for the audio samplerate and the amount of
        channels, plus some more that you don't need to worry about
        for now.
252 253
      </para>
      <programlisting>
254 255
Pad Templates:
  SRC template: 'src'
256 257
    Availability: Always
    Capabilities:
258 259 260 261 262 263 264 265
      audio/x-raw-float
                   rate: [ 8000, 50000 ]
               channels: [ 1, 2 ]
             endianness: 1234
                  width: 32
          buffer-frames: 0
 
  SINK template: 'sink'
266 267
    Availability: Always
    Capabilities:
268
      audio/x-vorbis
269 270
      </programlisting>
    </sect2>
271 272 273

    <sect2 id="section-caps-props">
      <title>Properties and values</title>
274 275 276 277 278 279 280 281
      <para> 
        Properties are used to describe extra information for 
        capabilities. A property consists of a key (a string) and
        a value. There are different possible value types that can be used:
      </para> 
      <itemizedlist>
        <listitem>
          <para>
282 283 284 285
            Basic types, this can be pretty much any
            <classname>GType</classname> registered with Glib. Those
            properties indicate a specific, non-dynamic value for this
            property. Examples include:
286 287 288 289
          </para>
          <itemizedlist>
            <listitem>
              <para>
290 291
                An integer value (<classname>G_TYPE_INT</classname>):
                the property has this exact value. 
292 293 294 295
              </para>
            </listitem>
            <listitem>
              <para>
296 297
    	        A boolean value (<classname>G_TYPE_BOOLEAN</classname>):
                the property is either TRUE or FALSE.
298 299 300 301
              </para>
            </listitem>
            <listitem>
              <para>
302 303
                A float value (<classname>G_TYPE_FLOAT</classname>):
                the property has this exact floating point value.
304 305 306 307
              </para>
            </listitem>
            <listitem>
              <para>
308 309
                A string value (<classname>G_TYPE_STRING</classname>):
                the property contains a UTF-8 string.
310 311
              </para>
            </listitem>
312 313 314 315 316 317 318
            <listitem>
              <para>
                A fraction value (<classname>GST_TYPE_FRACTION</classname>):
                contains a fraction expressed by an integer numerator and
                denominator.
              </para>
            </listitem>
319 320 321 322
          </itemizedlist>
        </listitem>
        <listitem>
          <para>
323 324 325 326 327
            Range types are <classname>GType</classname>s registered by
            &GStreamer; to indicate a range of possible values. They are
            used for indicating allowed audio samplerate values or
            supported video sizes. The two types defined in &GStreamer;
            are:
328 329 330 331
          </para>
          <itemizedlist>
           <listitem>
              <para>
332 333 334 335 336 337
                An integer range value
                (<classname>GST_TYPE_INT_RANGE</classname>): the property
                denotes a range of possible integers, with a lower and an
                upper boundary. The <quote>vorbisdec</quote> element, for
                example, has a rate property that can be between 8000 and
                50000.
338 339 340 341
              </para>
            </listitem>
            <listitem>
              <para>
342 343 344 345
    	        A float range value
                (<classname>GST_TYPE_FLOAT_RANGE</classname>): the property
                denotes a range of possible floating point values, with a
                lower and an upper boundary.
346 347
              </para>
            </listitem>
348 349 350 351 352 353 354 355
            <listitem>
              <para>
    	        A fraction range value
                (<classname>GST_TYPE_FRACTION_RANGE</classname>): the property
                denotes a range of possible fraction values, with a
                lower and an upper boundary.
              </para>
            </listitem>
356 357 358 359
          </itemizedlist>
        </listitem>
        <listitem>
          <para>
360 361 362
    	    A list value (<classname>GST_TYPE_LIST</classname>): the
            property can take any value from a list of basic values
            given in this list.
363
          </para>
364 365 366 367 368 369
          <para>
            Example: caps that express that either
            a sample rate of 44100 Hz and a sample rate of 48000 Hz
            is supported would use a list of integer values, with
            one value being 44100 and one value being 48000.
          </para>
370
        </listitem>
371 372
        <listitem>
          <para>
373
            An array value (<classname>GST_TYPE_ARRAY</classname>): the
374 375 376 377 378 379 380
            property is an array of values. Each value in the array is a
            full value on its own, too. All values in the array should be
            of the same elementary type. This means that an array can
            contain any combination of integers, lists of integers, integer
            ranges together, and the same for floats or strings, but it can
            not contain both floats and ints at the same time.
          </para>
381 382 383 384 385 386 387 388 389
          <para>
            Example: for audio where there are more than two channels involved
            the channel layout needs to be specified (for one and two channel
            audio the channel layout is implicit unless stated otherwise in the
            caps). So the channel layout would be an array of integer enum
            values where each enum value represents a loudspeaker position.
            Unlike a <classname>GST_TYPE_LIST</classname>, the values in an
            array will be interpreted as a whole.
          </para>
390
        </listitem>
391
      </itemizedlist>
392 393 394 395 396 397
    </sect2>
  </sect1>

  <sect1 id="section-caps-api">
    <title>What capabilities are used for</title>
    <para> 
398 399
      Capabilities (short: caps) describe the type of data that is streamed
      between two pads, or that one pad (template) supports. This makes them
400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
      very useful for various purposes:
    </para> 
    <itemizedlist>
      <listitem>
        <para>
          Autoplugging: automatically finding elements to link to a
          pad based on its capabilities. All autopluggers use this
          method.
        </para>
      </listitem>
      <listitem>
        <para>
          Compatibility detection: when two pads are linked, &GStreamer;
          can verify if the two pads are talking about the same media
          type. The process of linking two pads and checking if they
          are compatible is called <quote>caps negotiation</quote>.
        </para>
      </listitem>
      <listitem>
        <para>
          Metadata: by reading the capabilities from a pad, applications
          can provide information about the type of media that is being
          streamed over the pad, which is information about the stream
Wim Taymans's avatar
Wim Taymans committed
423
          that is currently being played back.
424 425 426 427 428 429 430 431
        </para>
      </listitem>
      <listitem>
        <para>
          Filtering: an application can use capabilities to limit the
          possible media types that can stream between two pads to a
          specific subset of their supported stream types. An application
          can, for example, use <quote>filtered caps</quote> to set a
432 433 434 435 436 437 438 439 440
          specific (fixed or non-fixed) video size that should stream
          between two pads. You will see an example of filtered caps
          later in this manual, in <xref linkend="section-data-spoof"/>.
          You can do caps filtering by inserting a capsfilter element into
          your pipeline and setting its <quote>caps</quote> property. Caps
          filters are often placed after converter elements like audioconvert,
          audioresample, ffmpegcolorspace or videoscale to force those
          converters to convert data to a specific output format at a
          certain point in a stream.
441 442 443
        </para>
      </listitem>
    </itemizedlist>
444

445 446 447 448
    <sect2 id="section-caps-metadata">
      <title>Using capabilities for metadata</title>
      <para> 
        A pad can have a set (i.e. one or more) of capabilities attached
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
        to it. Capabilities (<classname>GstCaps</classname>) are represented
        as an array of one or more <classname>GstStructure</classname>s, and
        each <classname>GstStructure</classname> is an array of fields where
        each field consists of a field name string (e.g. "width") and a
        typed value (e.g. <classname>G_TYPE_INT</classname> or
        <classname>GST_TYPE_INT_RANGE</classname>).
      </para>
      <para>
        Note that there is a distinct difference between the
        <emphasis>possible</emphasis> capabilities of a pad (ie. usually what
        you find as caps of pad templates as they are shown in gst-inspect),
        the <emphasis>allowed</emphasis> caps of a pad (can be the same as
        the pad's template caps or a subset of them, depending on the possible
        caps of the peer pad) and lastly <emphasis>negotiated</emphasis> caps
        (these describe the exact format of a stream or buffer and contain
        exactly one structure and have no variable bits like ranges or lists,
        ie. they are fixed caps).
      </para>
      <para>
        You can get values of properties in a set of capabilities
469 470
        by querying individual properties of one structure. You can get
        a structure from a caps using
471 472 473
        <function>gst_caps_get_structure ()</function> and the number of
        structures in a <classname>GstCaps</classname> using
        <function>gst_caps_get_size ()</function>.
474
      </para>
475 476 477 478 479 480 481 482 483 484
      <para>
        Caps are called <emphasis>simple caps</emphasis> when they contain
        only one structure, and <emphasis>fixed caps</emphasis> when they
        contain only one structure and have no variable field types (like
        ranges or lists of possible values). Two other special types of caps
        are <emphasis>ANY caps</emphasis> and <emphasis>empty caps</emphasis>.
      </para>
      <para>
        Here is an example of how to extract the width and height from
        a set of fixed video caps:
485 486 487 488 489 490 491
      <programlisting>
static void
read_video_props (GstCaps *caps)
{
  gint width, height;
  const GstStructure *str;

492 493 494
  g_return_if_fail (gst_caps_is_fixed (caps));

  str = gst_caps_get_structure (caps, 0);
495 496 497 498 499 500 501 502 503 504
  if (!gst_structure_get_int (str, "width", &amp;width) ||
      !gst_structure_get_int (str, "height", &amp;height)) {
    g_print ("No width/height available\n");
    return;
  }

  g_print ("The video size of this set of capabilities is %dx%d\n",
	   width, height);
}
      </programlisting>
505
      </para>
506
    </sect2>
507 508 509

    <sect2 id="section-caps-filter">
      <title>Creating capabilities for filtering</title>
510
      <para> 
511
        While capabilities are mainly used inside a plugin to describe the
512 513 514 515
        media type of the pads, the application programmer often also has
        to have basic understanding of capabilities in order to interface
        with the plugins, especially when using filtered caps. When you're
        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 518 519 520 521
        media types. You do this using a <classname>capsfilter</classname>
        element in your pipeline. In order to do this, you also need to
        create your own <classname>GstCaps</classname>. The easiest way to
        do this is by using the convenience function
        <function>gst_caps_new_simple ()</function>:
522
      </para>
523
      <para>
524
      <programlisting>
525 526
static gboolean
link_elements_with_filter (GstElement *element1, GstElement *element2)
527
{
528
  gboolean link_ok;
529 530 531
  GstCaps *caps;

  caps = gst_caps_new_simple ("video/x-raw-yuv",
532 533 534 535 536 537 538 539 540 541 542 543 544 545
  	      "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
	      "width", G_TYPE_INT, 384,
	      "height", G_TYPE_INT, 288,
	      "framerate", GST_TYPE_FRACTION, 25, 1,
	      NULL);

  link_ok = gst_element_link_filtered (element1, element2, caps);
  gst_caps_unref (caps);

  if (!link_ok) {
    g_warning ("Failed to link element1 and element2!");
  }

  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 552 553 554
      involved). Keep in mind that when you use <function>
      gst_element_link_filtered ()</function> it will automatically create
      a <classname>capsfilter</classname> element for you and insert it into
      your bin or pipeline between the two elements you want to connect (this
555 556
      is important if you ever want to disconnect those elements because then
      you will have to disconnect both elements from the capsfilter instead).
557
      </para>
558 559 560 561 562 563 564
      <para>
        In some cases, you will want to create a more elaborate set of
        capabilities to filter a link between two pads. Then, this function
        is too simplistic and you'll want to use the method
        <function>gst_caps_new_full ()</function>:
      </para>
      <programlisting>
565 566
static gboolean
link_elements_with_filter (GstElement *element1, GstElement *element2)
567
{
568
  gboolean link_ok;
569 570 571 572 573 574
  GstCaps *caps;
                                                                                
  caps = gst_caps_new_full (
      gst_structure_new ("video/x-raw-yuv",
			 "width", G_TYPE_INT, 384,
			 "height", G_TYPE_INT, 288,
575
			 "framerate", GST_TYPE_FRACTION, 25, 1,
576 577 578 579
			 NULL),
      gst_structure_new ("video/x-raw-rgb",
			 "width", G_TYPE_INT, 384,
			 "height", G_TYPE_INT, 288,
580
			 "framerate", GST_TYPE_FRACTION, 25, 1,
581 582 583
			 NULL),
      NULL);

584 585 586 587 588 589 590 591
  link_ok = gst_element_link_filtered (element1, element2, caps);
  gst_caps_unref (caps);

  if (!link_ok) {
    g_warning ("Failed to link element1 and element2!");
  }

  return link_ok;
592 593 594 595
}
      </programlisting>
      <para>
        See the API references for the full API of
596 597 598 599
	<ulink type="http"
	  url="&URLAPI;GstStructure.html"><classname>GstStructure</classname></ulink>
	and <ulink type="http"
	  url="&URLAPI;GstCaps.html"><classname>GstCaps</classname></ulink>.
600
      </para>
601 602
    </sect2>
  </sect1>
603 604 605 606 607 608 609 610 611 612 613 614 615

  <sect1 id="section-pads-ghost">
    <title>Ghost pads</title>
    <para>
      You can see from <xref linkend="section-bin-noghost-img"/> how a bin
      has no pads of its own. This is where "ghost pads" come into play.
    </para>
    <figure float="1" id="section-bin-noghost-img">
      <title>Visualisation of a <ulink type="http"
      url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
      element without ghost pads</title>
      <mediaobject>
        <imageobject>
616
          <imagedata scale="75" fileref="images/bin-element-noghost.&image;"
617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634
          format="&IMAGE;"/>
        </imageobject>
      </mediaobject>  
    </figure>
    <para>
      A ghost pad is a pad from some element in the bin that can be
      accessed directly from the bin as well. Compare it to a symbolic
      link in UNIX filesystems. Using ghost pads on bins, the bin also
      has a pad and can transparently be used as an element in other
      parts of your code.
    </para>
    
    <figure float="1" id="section-bin-ghost-img">
      <title>Visualisation of a <ulink type="http"
      url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
      element with a ghost pad</title>
      <mediaobject>
        <imageobject>
635
          <imagedata scale="75" fileref="images/bin-element-ghost.&image;"
636 637 638 639 640 641 642
          format="&IMAGE;"/>
        </imageobject>
      </mediaobject>  
    </figure>
    <para>
      <xref linkend="section-bin-ghost-img"/> is a representation of a
      ghost pad. The sink pad of element one is now also a pad of the bin.
643 644 645
      Because ghost pads look and work like any other pads, they can be added 
      to any type of elements, not just to a <classname>GstBin</classname>,
      just like ordinary pads.
646 647 648
    </para>
    <para>
      A ghostpad is created using the function
649
      <function>gst_ghost_pad_new ()</function>:
650 651 652 653 654 655 656 657 658
    </para>
    <programlisting><!-- example-begin ghostpad.c a -->
#include &lt;gst/gst.h&gt;

int
main (int   argc,
      char *argv[])
{
  GstElement *bin, *sink;
659
  GstPad *pad;
660 661 662 663

  /* init */
  gst_init (&amp;argc, &amp;argv);

664
  /* create element, add to bin */
665 666 667
  sink = gst_element_factory_make ("fakesink", "sink");
  bin = gst_bin_new ("mybin");
  gst_bin_add (GST_BIN (bin), sink);
668 669

  /* add ghostpad */
670
  pad = gst_element_get_static_pad (sink, "sink");
671 672
  gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
  gst_object_unref (GST_OBJECT (pad));
673 674 675 676 677 678 679 680 681 682 683 684 685 686
<!-- example-end ghostpad.c a -->
[..]<!-- example-begin ghostpad.c b --><!--
  return 0;
--><!-- example-end ghostpad.c b -->
<!-- example-begin ghostpad.c c -->
}
    <!-- example-end ghostpad.c c --></programlisting>
    <para>
      In the above example, the bin now also has a pad: the pad called
      <quote>sink</quote> of the given element. The bin can, from here
      on, be used as a substitute for the sink element. You could, for
      example, link another element to the bin.
    </para>
  </sect1>
687
</chapter>