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 element's
   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 %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_get_parent(GstPad *pad). This function will return a pointer to a
  57         GstElement.
  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>gst-inspect mpegdemux</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 %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_element_factory_make ("mpegdemux", "mpegdemux");
 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_element_factory_make ("tee", "element");
 143
 144   pad = gst_element_get_request_pad (element, "src%d");
 145   g_print ("new pad %s\n", gst_pad_get_name (pad));
 146     ...
 147       </programlisting>
 148       <para>
 149         The gst_element_get_request_pad 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_get_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_element_factory_make ("tee", "element");
 165   mad = gst_element_factory_make ("mad", "mad");
 166
 167   templ = gst_element_get_pad_template_by_name (mad, "sink");
 168
 169   pad = gst_element_get_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       Plugin Writer's 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 mad, as shown by
 211         <command>gst-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 template: 'sink'
 225     Availability: Always
 226     Capabilities:
 227       'mad_sink':
 228         MIME type: 'audio/mp3':
 229
 230   SRC template: 'src'
 231     Availability: Always
 232     Capabilities:
 233       'mad_src':
 234         MIME type: 'audio/raw':
 235         format: String: int
 236         endianness: Integer: 1234
 237         width: Integer: 16
 238         depth: Integer: 16
 239         channels: Integer range: 1 - 2
 240         law: Integer: 0
 241         signed: Boolean: TRUE
 242         rate: Integer range: 11025 - 48000
 243       </programlisting>
 244     </sect2>
 245     <sect2 id="sec-pads-props">
 246       <title>What are properties</title>
 247       <para>
 248         Properties are used to describe extra information for the capabilities. The properties
 249         basically exist of a key (a string) and a value. There are different possibile value types
 250         that can be used:
 251       </para>
 252
 253       <itemizedlist>
 254         <listitem>
 255           <para>
 256             An integer value: the property has this exact value.
 257           </para>
 258         </listitem>
 259         <listitem>
 260           <para>
 261             An integer range value. The property denotes a range of possible values. In the case
 262             of the mad element: the src pad has a property rate that can go from 11025 to 48000.
 263           </para>
 264         </listitem>
 265         <listitem>
 266           <para>
 267             A boolean value.
 268           </para>
 269         </listitem>
 270         <listitem>
 271           <para>
 272             a fourcc value: this is a value that is commonly used to describe an encoding for video,
 273             as used be the AVI specification.
 274           </para>
 275         </listitem>
 276         <listitem>
 277           <para>
 278             A list value: the property can take any value from a list.
 279           </para>
 280         </listitem>
 281         <listitem>
 282           <para>
 283             A float value: the property has this exact floating point value.
 284           </para>
 285         </listitem>
 286         <listitem>
 287           <para>
 288             A float range value: denotes a range of possible floating point values.
 289           </para>
 290         </listitem>
 291         <listitem>
 292           <para>
 293             A string value.
 294           </para>
 295         </listitem>
 296       </itemizedlist>
 297
 298     </sect2>
 299     <sect2 id="sec-pads-caps-use">
 300       <title>What are the capabilities used for?</title>
 301       <para>
 302         Capabilities describe in great detail the type of media that is handled by the pads.
 303         They are mostly used for:
 304       </para>
 305       <itemizedlist>
 306         <listitem>
 307           <para>
 308             Autoplugging: automatically finding plugins for a set of capabilities
 309           </para>
 310         </listitem>
 311         <listitem>
 312           <para>
 313             Compatibility detection: when two pads are connected, <application>GStreamer</application>
 314             can verify if the two pads are talking about the same media types.
 315           </para>
 316         </listitem>
 317       </itemizedlist>
 318     </sect2>
 319     <sect2 id="sec-pads-caps-get">
 320       <title>Getting the capabilities of a pad</title>
 321       <para>
 322         A pad can have a chain of capabilities attached to it. You can get the capabilities chain
 323         with:
 324       </para>
 325     <programlisting>
 326  GstCaps *caps;
 327     ...
 328  caps = gst_pad_get_caps (pad);
 329
 330  g_print ("pad name %s\n", gst_pad_get_name (pad));
 331
 332  while (caps) {
 333    g_print (" Capability name %s, MIME type %s\n",
 334                                 gst_caps_get_name (cap),
 335                                 gst_caps_get_mime (cap));
 336
 337    caps = caps-&gt;next;
 338  }
 339     ...
 340     </programlisting>
 341     </sect2>
 342     <sect2 id="sec-pads-caps-create">
 343       <title>Creating capabilities structures</title>
 344       <para>
 345         While the capabilities are mainly used inside the plugin to describe the media type of the
 346         pads, the application programmer also has to have basic understanding of caps in order to
 347         interface with the plugins, specially when using the autopluggers.
 348       </para>
 349       <para>
 350         As we said, a capability has a name, a mime-type and some properties. The signature of the
 351         function to create a new <classname>GstCaps</classname> structure is like:
 352     <programlisting>
 353 GstCaps*    gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
 354     </programlisting>
 355       </para>
 356       <para>
 357         You can therefore create a new capability with no properties like this:
 358     <programlisting>
 359   GstCaps *newcaps;
 360
 361   newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
 362     </programlisting>
 363       </para>
 364       <para>
 365         <classname>GstProps</classname> basically consist of a set of key-value pairs
 366         and are created with a function with this signature:
 367     <programlisting>
 368 GstProps*     gst_props_new   (const gchar *firstname, ...);
 369     </programlisting>
 370       </para>
 371       <para>
 372         The keys are given as strings and the values are given with a set of macros:
 373         <itemizedlist>
 374           <listitem>
 375             <para>
 376               GST_PROPS_INT(a): An integer value
 377             </para>
 378           </listitem>
 379           <listitem>
 380             <para>
 381               GST_PROPS_FLOAT(a): A floating point value
 382             </para>
 383           </listitem>
 384           <listitem>
 385             <para>
 386               GST_PROPS_FOURCC(a): A fourcc value
 387             </para>
 388           </listitem>
 389           <listitem>
 390             <para>
 391               GST_PROPS_BOOLEAN(a): A boolean value
 392             </para>
 393           </listitem>
 394           <listitem>
 395             <para>
 396               GST_PROPS_STRING(a): A string value
 397             </para>
 398           </listitem>
 399         </itemizedlist>
 400         The values can also be specified as ranges with:
 401         <itemizedlist>
 402           <listitem>
 403             <para>
 404               GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b
 405             </para>
 406           </listitem>
 407           <listitem>
 408             <para>
 409               GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
 410             </para>
 411           </listitem>
 412         </itemizedlist>
 413         All of the above values can be given with a list too, using:
 414         <itemizedlist>
 415           <listitem>
 416             <para>
 417               GST_PROPS_LIST(a,...): A list of property values.
 418             </para>
 419           </listitem>
 420         </itemizedlist>
 421       </para>
 422       <para>
 423         A more complex capability with properties is created like this:
 424         <programlisting>
 425   GstCaps *newcaps;
 426
 427   newcaps = gst_caps_new ("my_caps",
 428                           "audio/wav",
 429                           gst_props_new (
 430                             "bitrate", GST_PROPS_INT_RANGE (11025,22050),
 431                             "depth",   GST_PROPS_INT (16),
 432                             "signed",  GST_PROPS_LIST (
 433                                          GST_PROPS_BOOLEAN (TRUE),
 434                                          GST_PROPS_BOOLEAN (FALSE)
 435                                        ),
 436                             NULL
 437                           );
 438         </programlisting>
 439         Optionally the convenient shortcut macro can be used. The above complex
 440         capability can be created with:
 441         <programlisting>
 442   GstCaps *newcaps;
 443
 444   newcaps = GST_CAPS_NEW ("my_caps",
 445                           "audio/wav",
 446                             "bitrate", GST_PROPS_INT_RANGE (11025,22050),
 447                             "depth",   GST_PROPS_INT (16),
 448                             "signed",  GST_PROPS_LIST (
 449                                          GST_PROPS_BOOLEAN (TRUE),
 450                                          GST_PROPS_BOOLEAN (FALSE)
 451                                        )
 452                           );
 453         </programlisting>
 454       </para>
 455     </sect2>
 456
 457   </sect1>
 458 </chapter>