docs/manual/basics-pads.xml

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