docs/manual/basics-pads.xml

   1 <chapter id="cha-pads">
   2   <title>Pads</title>
   3   <para>
   4     As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
   5     interface to the outside world.
   6   </para>
   7   <para>
   8     The specific type of media that the element can handle will be exposed by the pads.
   9     The description of this media type is done with capabilities(see
  10     <xref linkend="sec-caps"/>)
  11   </para>
  12
  13   <para>
  14     Pads are either source or sink pads.  The terminology is defined from the
  15     view of the element itself: elements accept data on their sink pads, and
  16     send data out on their source pads.  Sink pads are drawn on the left,
  17     while source pads are drawn on the right of an element.  In general,
  18     data flows from left to right in the graph.<footnote>
  19       <para>
  20         In reality, there is no objection to data flowing from a
  21         source pad to the sink pad of an element upstream.  Data will, however,
  22         always flow from a source pad of one element to the sink pad of
  23         another.
  24       </para></footnote>
  25   </para>
  26
  27   <sect1 id="sec-pads-get">
  28     <title>Getting pads from an element</title>
  29     <para>
  30       Once you have created an element, you can get one of its pads with:
  31     </para>
  32     <programlisting>
  33  GstPad *srcpad;
  34     ...
  35  srcpad = gst_element_get_pad (element, "src");
  36     ...
  37     </programlisting>
  38     <para>
  39       This function will get the pad named "src" from the given element.
  40     </para>
  41     <para>
  42       Alternatively, you can request a GList of pads from the element. The
  43       following code example will print the names of all the pads of an
  44       element.
  45     </para>
  46     <programlisting>
  47  GList *pads;
  48     ...
  49  pads = gst_element_get_pad_list (element);
  50  while (pads) {
  51    GstPad *pad = GST_PAD (pads-&gt;data);
  52
  53    g_print ("pad name %s\n", gst_pad_get_name (pad));
  54
  55    pads = g_list_next (pads);
  56  }
  57     ...
  58     </programlisting>
  59     <sect2 id="sec-pads-functions">
  60       <title>Useful pad functions</title>
  61       <para>
  62         You can get the name of a pad with gst_pad_get_name () and set its name with
  63         get_pad_set_name().
  64       </para>
  65       <para>
  66         gst_pad_get_direction (GstPad *pad) can be used to query if the pad
  67         is a sink or a source pad. Remember that a source pad is a pad that
  68         can output data and a sink pad is one that accepts data.
  69       </para>
  70       <para>
  71         You can get the parent of the pad, this is the element that this pad belongs to,
  72         with get_pad_get_parent(GstPad *pad). This function will return a pointer to a
  73         GstElement.
  74       </para>
  75     </sect2>
  76   </sect1>
  77
  78   <sect1 id="sec-pads-type">
  79     <title>Types of pads</title>
  80
  81     <sect2 id="sec-pads-dynamic">
  82       <title>Dynamic pads</title>
  83       <para>
  84         Some elements might not have all of their pads when the element is
  85         created. This
  86         can happen, for example, with an MPEG system demultiplexer. The
  87         demultiplexer will create its pads at runtime when it detects the
  88         different elementary streams in the MPEG system stream.
  89       </para>
  90       <para>
  91         Running <application>gst-inspect mpegdemux</application> will show that
  92         the element has only one pad: a sink pad called 'sink'. The other pads are
  93         "dormant".  You can see this in the pad template because there is
  94         an 'Exists: Sometimes'
  95         property. Depending on the type of MPEG file you play, the pads will
  96         be created. We
  97         will see that this is very important when you are going to create dynamic
  98         pipelines later on in this manual.
  99       </para>
 100       <para>
 101         You can attach a signal to an element to inform you when the element has created
 102         a new pad from one of its padtemplates. The following piece of code is an example
 103         of how to do this:
 104       </para>
 105       <programlisting>
 106 static void
 107 pad_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline)
 108 {
 109   g_print("***** a new pad %s was created\n", gst_pad_get_name(pad));
 110
 111   gst_element_set_state (pipeline, GST_STATE_PAUSED);
 112
 113   if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) {
 114     // set up an AC3 decoder pipeline
 115     ...
 116     // link pad to the AC3 decoder pipeline
 117     ...
 118   }
 119   gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY);
 120 }
 121
 122 int
 123 main(int argc, char *argv[])
 124 {
 125   GstElement *pipeline;
 126   GstElement *mpeg2parser;
 127
 128   // create pipeline and do something useful
 129   ...
 130
 131   mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux");
 132   g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline);
 133   ...
 134
 135   // start the pipeline
 136   gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
 137   ...
 138 }
 139       </programlisting>
 140       <note>
 141         <para>
 142           A pipeline cannot be changed in the PLAYING state.
 143         </para>
 144       </note>
 145     </sect2>
 146     <sect2 id="sec-pads-request">
 147       <title>Request pads</title>
 148       <para>
 149         An element can also have request pads. These pads are not created
 150         automatically but are only created on demand. This is very useful
 151         for multiplexers, aggregators and tee elements.
 152       </para>
 153       <para>
 154         The tee element, for example, has one input pad and a request padtemplate for the
 155         output pads. Whenever an element wants to get an output pad from the tee element, it
 156         has to request the pad.
 157       </para>
 158       <para>
 159         The following piece of code can be used to get a pad from the tee element. After
 160         the pad has been requested, it can be used to link another element to it.
 161       </para>
 162       <programlisting>
 163     ...
 164   GstPad *pad;
 165     ...
 166   element = gst_element_factory_make ("tee", "element");
 167
 168   pad = gst_element_get_request_pad (element, "src%d");
 169   g_print ("new pad %s\n", gst_pad_get_name (pad));
 170     ...
 171       </programlisting>
 172       <para>
 173         The gst_element_get_request_pad method can be used to get a pad
 174         from the element based on the name_template of the padtemplate.
 175       </para>
 176       <para>
 177         It is also possible to request a pad that is compatible with another
 178         pad template. This is very useful if you want to link an element
 179         to a multiplexer element and you need to request a pad that is
 180         compatible. The gst_element_get_compatible_pad is used to request
 181         a compatible pad, as is shown in the next example.
 182       </para>
 183       <programlisting>
 184     ...
 185   GstPadTemplate *templ;
 186   GstPad *pad;
 187     ...
 188   element = gst_element_factory_make ("tee", "element");
 189   mad = gst_element_factory_make ("mad", "mad");
 190
 191   templ = gst_element_get_pad_template_by_name (mad, "sink");
 192
 193   pad = gst_element_get_compatible_pad (element, templ);
 194   g_print ("new pad %s\n", gst_pad_get_name (pad));
 195   ...
 196       </programlisting>
 197     </sect2>
 198
 199   </sect1>
 200
 201   <sect1 id="sec-caps">
 202     <title>Capabilities of a pad</title>
 203     <para>
 204       Since the pads play a very important role in how the element is viewed by the
 205       outside world, a mechanism is implemented to describe the data that can
 206       flow through the pad by using capabilities.
 207     </para>
 208     <para>
 209       We will briefly describe what capabilities are, enough for you to get a basic understanding
 210       of the concepts. You will find more information on how to create capabilities in the
 211       Plugin Writer's Guide.
 212     </para>
 213
 214     <sect2 id="sec-pads-caps">
 215       <title>What are capabilities ?</title>
 216       <para>
 217         Capabilities are attached to a pad in order to describe
 218         what type of media the pad can handle.
 219       </para>
 220       <para>
 221         Capabilities is shorthand for "capability chain".  A capability chain
 222         is a chain of one capability or more.
 223       </para>
 224       <para>
 225         The basic entity is a capability, and is defined by a name, a MIME
 226         type and a set of properties.  A capability can be chained to
 227         another capability, which is why we commonly refer to a chain of
 228         capability entities as "capabilities".<footnote>
 229           <para>
 230             It is important to understand that the term "capabilities" refers
 231             to a chain of one capability or more.  This will be clearer when
 232             you see the structure definition of a <classname>GstCaps</classname>
 233             element.
 234           </para></footnote>
 235       </para>
 236       <para>
 237         Its structure is:
 238       </para>
 239       <programlisting>
 240 struct _GstCaps {
 241   gchar *name;                  /* the name of this caps */
 242   guint16 id;                   /* type id (major type) */
 243
 244   guint refcount;               /* caps are refcounted */
 245
 246   GstProps *properties;         /* properties for this capability */
 247
 248   GstCaps *next;                /* caps can be chained together */
 249 };
 250       </programlisting>
 251       <para>
 252         Below is a dump of the capabilities of the element mad, as shown by
 253         <command>gst-inspect</command>.
 254         You can see two pads: sink and src. Both pads have capability information attached to them.
 255       </para>
 256       <para>
 257         The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has
 258         three properties: layer, bitrate and framed.
 259       </para>
 260       <para>
 261         The source pad (output pad) is called 'src' and outputs data of
 262         MIME type 'audio/raw'. It also has four properties: format, depth,
 263         rate and channels.
 264       </para>
 265       <programlisting>
 266 Pads:
 267   SINK template: 'sink'
 268     Availability: Always
 269     Capabilities:
 270       'mad_sink':
 271         MIME type: 'audio/mp3':
 272
 273   SRC template: 'src'
 274     Availability: Always
 275     Capabilities:
 276       'mad_src':
 277         MIME type: 'audio/raw':
 278         format: String: int
 279         endianness: Integer: 1234
 280         width: Integer: 16
 281         depth: Integer: 16
 282         channels: Integer range: 1 - 2
 283         law: Integer: 0
 284         signed: Boolean: TRUE
 285         rate: Integer range: 11025 - 48000
 286       </programlisting>
 287     </sect2>
 288     <sect2 id="sec-pads-props">
 289       <title>What are properties ?</title>
 290       <para>
 291         Properties are used to describe extra information for
 292         capabilities. A property consists of a key (a string) and
 293         a value. There are different possible value types that can be used:
 294       </para>
 295
 296       <itemizedlist>
 297         <listitem>
 298           <para>
 299             basic types:
 300           </para>
 301           <itemizedlist>
 302             <listitem>
 303               <para>
 304                 an integer value: the property has this exact value.
 305               </para>
 306             </listitem>
 307             <listitem>
 308               <para>
 309                 a boolean value: the property is either TRUE or FALSE.
 310               </para>
 311             </listitem>
 312             <listitem>
 313               <para>
 314                 a fourcc value: this is a value that is commonly used to
 315                 describe an encoding for video,
 316                 as used for example by the AVI specification.
 317                 <footnote><para>
 318                   fourcc values consist of four bytes.
 319                   <ulink url="http://www.fourcc.org" type="http">The FOURCC
 320                   Definition List</ulink> is the most complete resource
 321                   on the allowed fourcc values.
 322                 </para></footnote>
 323               </para>
 324             </listitem>
 325             <listitem>
 326               <para>
 327                 a float value: the property has this exact floating point value.
 328               </para>
 329             </listitem>
 330             <listitem>
 331               <para>
 332                 a string value.
 333               </para>
 334             </listitem>
 335           </itemizedlist>
 336         </listitem>
 337
 338         <listitem>
 339           <para>
 340             range types:
 341           </para>
 342           <itemizedlist>
 343            <listitem>
 344               <para>
 345                 an integer range value: the property denotes a range of
 346                 possible integer. For example, the wavparse element has
 347                 a source pad where the "rate" property can go from 8000 to
 348                 48000.
 349               </para>
 350             </listitem>
 351             <listitem>
 352               <para>
 353                 a float range value: the property denotes a range of possible
 354                 floating point values.
 355               </para>
 356             </listitem>
 357           </itemizedlist>
 358         </listitem>
 359         <listitem>
 360           <para>
 361             a list value: the property can take any value from a list of
 362             basic value types or range types.
 363           </para>
 364         </listitem>
 365       </itemizedlist>
 366
 367     </sect2>
 368     <sect2 id="sec-pads-caps-use">
 369       <title>What capabilities are used for</title>
 370       <para>
 371         Capabilities describe in great detail the type of media that is handled by the pads.
 372         They are mostly used for:
 373       </para>
 374       <itemizedlist>
 375         <listitem>
 376           <para>
 377             Autoplugging: automatically finding plugins for a set of capabilities
 378           </para>
 379         </listitem>
 380         <listitem>
 381           <para>
 382             Compatibility detection: when two pads are linked, <application>GStreamer</application>
 383             can verify if the two pads are talking about the same media types.
 384             The process of linking two pads and checking if they are compatible
 385             is called "caps negotiation".
 386           </para>
 387         </listitem>
 388       </itemizedlist>
 389     </sect2>
 390     <sect2 id="sec-pads-caps-get">
 391       <title>Getting the capabilities of a pad</title>
 392       <para>
 393         A pad can have a chain of capabilities attached to it. You can get the capabilities chain
 394         with:
 395       </para>
 396     <programlisting>
 397  GstCaps *caps;
 398     ...
 399  caps = gst_pad_get_caps (pad);
 400
 401  g_print ("pad name %s\n", gst_pad_get_name (pad));
 402
 403  while (caps) {
 404    g_print (" Capability name %s, MIME type %s\n",
 405                                 gst_caps_get_name (cap),
 406                                 gst_caps_get_mime (cap));
 407
 408    caps = caps-&gt;next;
 409  }
 410     ...
 411     </programlisting>
 412     </sect2>
 413     <sect2 id="sec-pads-caps-create">
 414       <title>Creating capability structures</title>
 415       <para>
 416         While capabilities are mainly used inside a plugin to describe the
 417         media type of the pads, the application programmer also has to have
 418         basic understanding of capabilities in order to interface with the
 419         plugins, specially when using the autopluggers.
 420       </para>
 421       <para>
 422         As we said, a capability has a name, a mime-type and some
 423         properties. The signature of the function to create a new
 424         <classname>GstCaps</classname> structure is:
 425
 426     <programlisting>
 427 GstCaps*    gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
 428     </programlisting>
 429       </para>
 430       <para>
 431         You can therefore create a new capability with no properties like this:
 432     <programlisting>
 433   GstCaps *newcaps;
 434
 435   newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
 436     </programlisting>
 437       </para>
 438       <para>
 439         <classname>GstProps</classname> basically consist of a set of key-value pairs
 440         and are created with a function with this signature:
 441     <programlisting>
 442 GstProps*     gst_props_new   (const gchar *firstname, ...);
 443     </programlisting>
 444       </para>
 445       <para>
 446         The keys are given as strings and the values are given with a set of macros:
 447         <itemizedlist>
 448           <listitem>
 449             <para>
 450               GST_PROPS_INT(a): An integer value
 451             </para>
 452           </listitem>
 453           <listitem>
 454             <para>
 455               GST_PROPS_FLOAT(a): A floating point value
 456             </para>
 457           </listitem>
 458           <listitem>
 459             <para>
 460               GST_PROPS_FOURCC(a): A fourcc value
 461             </para>
 462           </listitem>
 463           <listitem>
 464             <para>
 465               GST_PROPS_BOOLEAN(a): A boolean value
 466             </para>
 467           </listitem>
 468           <listitem>
 469             <para>
 470               GST_PROPS_STRING(a): A string value
 471             </para>
 472           </listitem>
 473         </itemizedlist>
 474         The values can also be specified as ranges with:
 475         <itemizedlist>
 476           <listitem>
 477             <para>
 478               GST_PROPS_INT_RANGE(a,b): An integer range from a to b
 479             </para>
 480           </listitem>
 481           <listitem>
 482             <para>
 483               GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
 484             </para>
 485           </listitem>
 486         </itemizedlist>
 487         All of the above values can be given with a list too, using:
 488         <itemizedlist>
 489           <listitem>
 490             <para>
 491               GST_PROPS_LIST(a,...): A list of property values.
 492             </para>
 493           </listitem>
 494         </itemizedlist>
 495       </para>
 496       <para>
 497         A more complex capability with properties is created like this:
 498         <programlisting>
 499   GstCaps *newcaps;
 500
 501   newcaps = gst_caps_new ("my_caps",
 502                           "audio/wav",
 503                           gst_props_new (
 504                             "bitrate", GST_PROPS_INT_RANGE (11025,22050),
 505                             "depth",   GST_PROPS_INT (16),
 506                             "signed",  GST_PROPS_LIST (
 507                                          GST_PROPS_BOOLEAN (TRUE),
 508                                          GST_PROPS_BOOLEAN (FALSE)
 509                                        ),
 510                             NULL
 511                           );
 512         </programlisting>
 513         Optionally, the convenient shortcut macro can be used. The above complex
 514         capability can be created with:
 515         <programlisting>
 516   GstCaps *newcaps;
 517
 518   newcaps = GST_CAPS_NEW ("my_caps",
 519                           "audio/wav",
 520                             "bitrate", GST_PROPS_INT_RANGE (11025,22050),
 521                             "depth",   GST_PROPS_INT (16),
 522                             "signed",  GST_PROPS_LIST (
 523                                          GST_PROPS_BOOLEAN (TRUE),
 524                                          GST_PROPS_BOOLEAN (FALSE)
 525                                        )
 526                           );
 527         </programlisting>
 528       </para>
 529     </sect2>
 530
 531   </sect1>
 532 </chapter>