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