subprojects/gst-docs/markdown/application-development/basics/pads.md

   1 ---
   2 title: Pads and capabilities
   3 ...
   4
   5 # Pads and capabilities
   6
   7 As we have seen in [Elements][elements], the pads are the
   8 element's interface to the outside world. Data streams from one
   9 element's source pad to another element's sink pad. The specific type of
  10 media that the element can handle will be exposed by the pad's
  11 capabilities. We will talk more on capabilities later in this chapter
  12 (see [Capabilities of a pad](#capabilities-of-a-pad)).
  13
  14 [elements]: application-development/basics/elements.md
  15
  16 ## Pads
  17
  18 A pad type is defined by two properties: its direction and its
  19 availability. As we've mentioned before, GStreamer defines two pad
  20 directions: source pads and sink pads. This terminology is defined from
  21 the view of within the element: elements receive data on their sink pads
  22 and generate data on their source pads. Schematically, sink pads are
  23 drawn on the left side of an element, whereas source pads are drawn on
  24 the right side of an element. In such graphs, data flows from left to
  25 right. \[1\]
  26
  27 Pad directions are very simple compared to pad availability. A pad can
  28 have any of three availabilities: always, sometimes and on request. The
  29 meaning of those three types is exactly as it says: always pads always
  30 exist, sometimes pads exist only in certain cases (and can disappear
  31 randomly), and on-request pads appear only if explicitly requested by
  32 applications.
  33
  34 ### Dynamic (or sometimes) pads
  35
  36 Some elements might not have all of their pads when the element is
  37 created. This can happen, for example, with an Ogg demuxer element. The
  38 element will read the Ogg stream and create dynamic pads for each
  39 contained elementary stream (vorbis, theora) when it detects such a
  40 stream in the Ogg stream. Likewise, it will delete the pad when the
  41 stream ends. This principle is very useful for demuxer elements, for
  42 example.
  43
  44 Running `gst-inspect-1.0 oggdemux` will show that the element has only one
  45 pad: a sink pad called 'sink'. The other pads are “dormant”. You can see
  46 this in the pad template because there is an “Availability: Sometimes”
  47 property. Depending on the type of Ogg file you play, the pads will be
  48 created. We will see that this is very important when you are going to
  49 create dynamic pipelines. You can attach a signal handler to an element
  50 to inform you when the element has created a new pad from one of its
  51 “sometimes” pad templates. The following piece of code is an example
  52 of how to do this:
  53
  54 ``` c
  55 #include <gst/gst.h>
  56
  57 static void
  58 cb_new_pad (GstElement *element,
  59         GstPad     *pad,
  60         gpointer    data)
  61 {
  62   gchar *name;
  63
  64   name = gst_pad_get_name (pad);
  65   g_print ("A new pad %s was created\n", name);
  66   g_free (name);
  67
  68   /* here, you would setup a new pad link for the newly created pad */
  69 [..]
  70
  71 }
  72
  73 int
  74 main (int   argc,
  75       char *argv[])
  76 {
  77   GstElement *pipeline, *source, *demux;
  78   GMainLoop *loop;
  79
  80   /* init */
  81   gst_init (&argc, &argv);
  82
  83   /* create elements */
  84   pipeline = gst_pipeline_new ("my_pipeline");
  85   source = gst_element_factory_make ("filesrc", "source");
  86   g_object_set (source, "location", argv[1], NULL);
  87   demux = gst_element_factory_make ("oggdemux", "demuxer");
  88
  89   /* you would normally check that the elements were created properly */
  90
  91   /* put together a pipeline */
  92   gst_bin_add_many (GST_BIN (pipeline), source, demux, NULL);
  93   gst_element_link_pads (source, "src", demux, "sink");
  94
  95   /* listen for newly created pads */
  96   g_signal_connect (demux, "pad-added", G_CALLBACK (cb_new_pad), NULL);
  97
  98   /* start the pipeline */
  99   gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
 100   loop = g_main_loop_new (NULL, FALSE);
 101   g_main_loop_run (loop);
 102
 103 [..]
 104
 105 }
 106
 107 ```
 108
 109 It is not uncommon to add elements to the pipeline only from within the
 110 "pad-added" callback. If you do this, don't forget to set the state of
 111 the newly-added elements to the target state of the pipeline using
 112 `gst_element_set_state ()` or `gst_element_sync_state_with_parent ()`.
 113
 114 ### Request pads
 115
 116 An element can also have request pads. These pads are not created
 117 automatically but are only created on demand. This is very useful for
 118 multiplexers, aggregators and tee elements. Aggregators are elements
 119 that merge the content of several input streams together into one output
 120 stream. Tee elements are the reverse: they are elements that have one
 121 input stream and copy this stream to each of their output pads, which
 122 are created on request. Whenever an application needs another copy of
 123 the stream, it can simply request a new output pad from the tee element.
 124
 125 The following piece of code shows how you can request a new output pad
 126 from a “tee” element:
 127
 128 {{ snippets.c#some_function }}
 129
 130 The `gst_element_request_pad_simple ()` method can be used to get a pad
 131 from the element based on the name of the pad template. It is also
 132 possible to request a pad that is compatible with another pad template.
 133 This is very useful if you want to link an element to a multiplexer
 134 element and you need to request a pad that is compatible. The method
 135 `gst_element_get_compatible_pad ()` can be used to request a compatible
 136 pad, as shown in the next example. It will request a compatible pad from
 137 an Ogg multiplexer from any input.
 138
 139 {{ snippets.c#link_to_multiplexer }}
 140
 141 ## Capabilities of a pad
 142
 143 Since the pads play a very important role in how the element is viewed
 144 by the outside world, a mechanism is implemented to describe the data
 145 that can flow or currently flows through the pad by using capabilities.
 146 Here, we will briefly describe what capabilities are and how to use
 147 them, enough to get an understanding of the concept. For an in-depth
 148 look into capabilities and a list of all capabilities defined in
 149 GStreamer, see the [Plugin Writers Guide](plugin-development/index.md)
 150
 151 Capabilities are attached to pad templates and to pads. For pad
 152 templates, it will describe the types of media that may stream over a
 153 pad created from this template. For pads, it can either be a list of
 154 possible caps (usually a copy of the pad template's capabilities), in
 155 which case the pad is not yet negotiated, or it is the type of media
 156 that currently streams over this pad, in which case the pad has been
 157 negotiated already.
 158
 159 ### Dissecting capabilities
 160
 161 A pad's capabilities are described in a `GstCaps` object. Internally, a
 162 [`GstCaps`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstCaps.html)
 163 will contain one or more
 164 [`GstStructure`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstStructure.html)
 165 that will describe one media type. A negotiated pad will have
 166 capabilities set that contain exactly *one* structure. Also, this
 167 structure will contain only *fixed* values. These constraints are not
 168 true for unnegotiated pads or pad templates.
 169
 170 As an example, below is a dump of the capabilities of the “vorbisdec”
 171 element, which you will get by running `gst-inspect vorbisdec`. You will
 172 see two pads: a source and a sink pad. Both of these pads are always
 173 available, and both have capabilities attached to them. The sink pad
 174 will accept vorbis-encoded audio data, with the media type
 175 “audio/x-vorbis”. The source pad will be used to send raw (decoded)
 176 audio samples to the next element, with a raw audio media type (in this
 177 case, “audio/x-raw”). The source pad will also contain properties for
 178 the audio samplerate and the amount of channels, plus some more that you
 179 don't need to worry about for now.
 180
 181 ```
 182 Pad Templates:
 183   SRC template: 'src'
 184     Availability: Always
 185     Capabilities:
 186       audio/x-raw
 187                  format: F32LE
 188                    rate: [ 1, 2147483647 ]
 189                channels: [ 1, 256 ]
 190
 191   SINK template: 'sink'
 192     Availability: Always
 193     Capabilities:
 194       audio/x-vorbis
 195 ```
 196
 197 ### Properties and values
 198
 199 Properties are used to describe extra information for capabilities. A
 200 property consists of a key (a string) and a value. There are different
 201 possible value types that can be used:
 202
 203   - Basic types, this can be pretty much any `GType` registered with
 204     Glib. Those properties indicate a specific, non-dynamic value for
 205     this property. Examples include:
 206
 207       - An integer value (`G_TYPE_INT`): the property has this exact
 208         value.
 209
 210       - A boolean value (`G_TYPE_BOOLEAN`): the property is either `TRUE`
 211         or `FALSE`.
 212
 213       - A float value (`G_TYPE_FLOAT`): the property has this exact
 214         floating point value.
 215
 216       - A string value (`G_TYPE_STRING`): the property contains a UTF-8
 217         string.
 218
 219       - A fraction value (`GST_TYPE_FRACTION`): contains a fraction
 220         expressed by an integer numerator and denominator.
 221
 222   - Range types are `GType`s registered by GStreamer to indicate a range
 223     of possible values. They are used for indicating allowed audio
 224     samplerate values or supported video sizes. The two types defined in
 225     GStreamer are:
 226
 227       - An integer range value (`GST_TYPE_INT_RANGE`): the property
 228         denotes a range of possible integers, with a lower and an upper
 229         boundary. The “vorbisdec” element, for example, has a rate
 230         property that can be between 8000 and 50000.
 231
 232       - A float range value (`GST_TYPE_FLOAT_RANGE`): the property
 233         denotes a range of possible floating point values, with a lower
 234         and an upper boundary.
 235
 236       - A fraction range value (`GST_TYPE_FRACTION_RANGE`): the property
 237         denotes a range of possible fraction values, with a lower and an
 238         upper boundary.
 239
 240   - A list value (`GST_TYPE_LIST`): the property can take any value from
 241     a list of basic values given in this list.
 242
 243     Example: caps that express that either a sample rate of 44100 Hz and
 244     a sample rate of 48000 Hz is supported would use a list of integer
 245     values, with one value being 44100 and one value being 48000.
 246
 247   - An array value (`GST_TYPE_ARRAY`): the property is an array of
 248     values. Each value in the array is a full value on its own, too. All
 249     values in the array should be of the same elementary type. This
 250     means that an array can contain any combination of integers, lists
 251     of integers, integer ranges together, and the same for floats or
 252     strings, but it can not contain both floats and ints at the same
 253     time.
 254
 255     Example: for audio where there are more than two channels involved
 256     the channel layout needs to be specified (for one and two channel
 257     audio the channel layout is implicit unless stated otherwise in the
 258     caps). So the channel layout would be an array of integer enum
 259     values where each enum value represents a loudspeaker position.
 260     Unlike a `GST_TYPE_LIST`, the values in an array will be interpreted
 261     as a whole.
 262
 263 ## What capabilities are used for
 264
 265 Capabilities (short: caps) describe the type of data that is streamed
 266 between two pads, or that one pad (template) supports. This makes them
 267 very useful for various purposes:
 268
 269   - Autoplugging: automatically finding elements to link to a pad based
 270     on its capabilities. All autopluggers use this method.
 271
 272   - Compatibility detection: when two pads are linked, GStreamer can
 273     verify if the two pads are talking about the same media type. The
 274     process of linking two pads and checking if they are compatible is
 275     called “caps negotiation”.
 276
 277   - Metadata: by reading the capabilities from a pad, applications can
 278     provide information about the type of media that is being streamed
 279     over the pad, which is information about the stream that is
 280     currently being played back.
 281
 282   - Filtering: an application can use capabilities to limit the possible
 283     media types that can stream between two pads to a specific subset of
 284     their supported stream types. An application can, for example, use
 285     “filtered caps” to set a specific (fixed or non-fixed) video size
 286     that should stream between two pads. You will see an example of
 287     filtered caps later in this manual, in [Manually adding or removing
 288     data from/to a pipeline][inserting-or-extracting-data].
 289     You can do caps filtering by inserting a capsfilter element into
 290     your pipeline and setting its “caps” property. Caps filters are
 291     often placed after converter elements like audioconvert,
 292     audioresample, videoconvert or videoscale to force those converters
 293     to convert data to a specific output format at a certain point in a
 294     stream.
 295
 296 [inserting-or-extracting-data]: application-development/advanced/pipeline-manipulation.md#manually-adding-or-removing-data-fromto-a-pipeline
 297
 298 ### Using capabilities for metadata
 299
 300 A pad can have a set (i.e. one or more) of capabilities attached to it.
 301 Capabilities (`GstCaps`) are represented as an array of one or more
 302 `GstStructure`s, and each `GstStructure` is an array of fields where
 303 each field consists of a field name string (e.g. "width") and a typed
 304 value (e.g. `G_TYPE_INT` or `GST_TYPE_INT_RANGE`).
 305
 306 Note that there is a distinct difference between the *possible*
 307 capabilities of a pad (ie. usually what you find as caps of pad
 308 templates as they are shown in gst-inspect), the *allowed* caps of a pad
 309 (can be the same as the pad's template caps or a subset of them,
 310 depending on the possible caps of the peer pad) and lastly *negotiated*
 311 caps (these describe the exact format of a stream or buffer and contain
 312 exactly one structure and have no variable bits like ranges or lists,
 313 ie. they are fixed caps).
 314
 315 You can get values of properties in a set of capabilities by querying
 316 individual properties of one structure. You can get a structure from a
 317 caps using `gst_caps_get_structure ()` and the number of structures in a
 318 `GstCaps` using `gst_caps_get_size ()`.
 319
 320 Caps are called *simple caps* when they contain only one structure, and
 321 *fixed caps* when they contain only one structure and have no variable
 322 field types (like ranges or lists of possible values). Two other special
 323 types of caps are *ANY caps* and *empty caps*.
 324
 325 Here is an example of how to extract the width and height from a set of
 326 fixed video caps:
 327
 328 ``` c
 329 static void
 330 read_video_props (GstCaps *caps)
 331 {
 332   gint width, height;
 333   const GstStructure *str;
 334
 335   g_return_if_fail (gst_caps_is_fixed (caps));
 336
 337   str = gst_caps_get_structure (caps, 0);
 338   if (!gst_structure_get_int (str, "width", &width) ||
 339       !gst_structure_get_int (str, "height", &height)) {
 340     g_print ("No width/height available\n");
 341     return;
 342   }
 343
 344   g_print ("The video size of this set of capabilities is %dx%d\n",
 345        width, height);
 346 }
 347
 348 ```
 349
 350 ### Creating capabilities for filtering
 351
 352 While capabilities are mainly used inside a plugin to describe the media
 353 type of the pads, the application programmer often also has to have
 354 basic understanding of capabilities in order to interface with the
 355 plugins, especially when using filtered caps. When you're using filtered
 356 caps or fixation, you're limiting the allowed types of media that can
 357 stream between two pads to a subset of their supported media types. You
 358 do this using a `capsfilter` element in your pipeline. In order to do
 359 this, you also need to create your own `GstCaps`. The easiest way to do
 360 this is by using the convenience function `gst_caps_new_simple ()`:
 361
 362 ``` c
 363 static gboolean
 364 link_elements_with_filter (GstElement *element1, GstElement *element2)
 365 {
 366   gboolean link_ok;
 367   GstCaps *caps;
 368
 369   caps = gst_caps_new_simple ("video/x-raw",
 370           "format", G_TYPE_STRING, "I420",
 371           "width", G_TYPE_INT, 384,
 372           "height", G_TYPE_INT, 288,
 373           "framerate", GST_TYPE_FRACTION, 25, 1,
 374           NULL);
 375
 376   link_ok = gst_element_link_filtered (element1, element2, caps);
 377   gst_caps_unref (caps);
 378
 379   if (!link_ok) {
 380     g_warning ("Failed to link element1 and element2!");
 381   }
 382
 383   return link_ok;
 384 }
 385
 386 ```
 387
 388 This will force the data flow between those two elements to a certain
 389 video format, width, height and framerate (or the linking will fail if
 390 that cannot be achieved in the context of the elements involved). Keep
 391 in mind that when you use `
 392 gst_element_link_filtered ()` it will automatically create a
 393 `capsfilter` element for you and insert it into your bin or pipeline
 394 between the two elements you want to connect (this is important if you
 395 ever want to disconnect those elements because then you will have to
 396 disconnect both elements from the capsfilter instead).
 397
 398 In some cases, you will want to create a more elaborate set of
 399 capabilities to filter a link between two pads. Then, this function is
 400 too simplistic and you'll want to use the method `gst_caps_new_full ()`:
 401
 402 ``` c
 403 static gboolean
 404 link_elements_with_filter (GstElement *element1, GstElement *element2)
 405 {
 406   gboolean link_ok;
 407   GstCaps *caps;
 408
 409   caps = gst_caps_new_full (
 410       gst_structure_new ("video/x-raw",
 411              "width", G_TYPE_INT, 384,
 412              "height", G_TYPE_INT, 288,
 413              "framerate", GST_TYPE_FRACTION, 25, 1,
 414              NULL),
 415       gst_structure_new ("video/x-bayer",
 416              "width", G_TYPE_INT, 384,
 417              "height", G_TYPE_INT, 288,
 418              "framerate", GST_TYPE_FRACTION, 25, 1,
 419              NULL),
 420       NULL);
 421
 422   link_ok = gst_element_link_filtered (element1, element2, caps);
 423   gst_caps_unref (caps);
 424
 425   if (!link_ok) {
 426     g_warning ("Failed to link element1 and element2!");
 427   }
 428
 429   return link_ok;
 430 }
 431
 432 ```
 433
 434 See the API references for the full API of
 435 [`GstStructure`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstStructure.html)
 436 and
 437 [`GstCaps`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstCaps.html).
 438
 439 ## Ghost pads
 440
 441 You can see from [Visualisation of a GstBin element without ghost
 442 pads](#visualisation-of-a-gstbin-------element-without-ghost-pads) how a
 443 bin has no pads of its own. This is where "ghost pads" come into play.
 444
 445 ![Visualisation of a
 446 [`GstBin`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBin.html)
 447 element without ghost pads](images/bin-element-noghost.png "fig:")
 448
 449 A ghost pad is a pad from some element in the bin that can be accessed
 450 directly from the bin as well. Compare it to a symbolic link in UNIX
 451 filesystems. Using ghost pads on bins, the bin also has a pad and can
 452 transparently be used as an element in other parts of your code.
 453
 454 ![Visualisation of a
 455 [`GstBin`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBin.html)
 456 element with a ghost pad](images/bin-element-ghost.png "fig:")
 457
 458 [Visualisation of a GstBin element with a ghost
 459 pad](#visualisation-of-a-gstbin-------element-with-a-ghost-pad) is a
 460 representation of a ghost pad. The sink pad of element one is now also a
 461 pad of the bin. Because ghost pads look and work like any other pads,
 462 they can be added to any type of elements, not just to a `GstBin`, just
 463 like ordinary pads.
 464
 465 A ghostpad is created using the function `gst_ghost_pad_new ()`:
 466
 467 ``` c
 468 #include <gst/gst.h>
 469
 470 int
 471 main (int   argc,
 472       char *argv[])
 473 {
 474   GstElement *bin, *sink;
 475   GstPad *pad;
 476
 477   /* init */
 478   gst_init (&argc, &argv);
 479
 480   /* create element, add to bin */
 481   sink = gst_element_factory_make ("fakesink", "sink");
 482   bin = gst_bin_new ("mybin");
 483   gst_bin_add (GST_BIN (bin), sink);
 484
 485   /* add ghostpad */
 486   pad = gst_element_get_static_pad (sink, "sink");
 487   gst_element_add_pad (bin, gst_ghost_pad_new ("sink", pad));
 488   gst_object_unref (GST_OBJECT (pad));
 489
 490 [..]
 491
 492 }
 493
 494 ```
 495
 496 In the above example, the bin now also has a pad: the pad called “sink”
 497 of the given element. The bin can, from here on, be used as a substitute
 498 for the sink element. You could, for example, link another element to
 499 the bin.
 500
 501 1.  In reality, there is no objection to data flowing from a source pad
 502     to the sink pad of an element upstream (to the left of this element
 503     in drawings). Data will, however, always flow from a source pad of
 504     one element to the sink pad of another.