gstreamer/docs/manual/pads.sgml

<chapter id="cha-pads">
  <title>GstPad</title>
  <para>
    As we have seen in the previous chapter (GstElement), the pads are the elements
    connections with the outside world. 
  </para>
  <para>
    The specific type of media that the element can handle will be exposed by the pads.
    The description of this media type is done with capabilities (<classname>GstCaps</classname>)
  </para>

  <sect1 id="sec-pads-get">
    <title>Getting pads from an element</title>
    <para> 
      Once you have created an element, you can get one of its pads with:
    </para>
    <programlisting>
 GstPad *srcpad;
    ...
 srcpad = gst_element_get_pad (element, "src");
    ...
    </programlisting>
    <para> 
      This function will get the pad named "src" from the given element. 
    </para>
    <para> 
      Alternatively, you can also request a GList of pads from the element. The following
      code example will print the names of all the pads of an element.
    </para>
    <programlisting>
 GList *pads;
    ...
 pads = gst_element_get_pad_list (element);
 while (pads) {
   GstPad *pad = GST_PAD (pads-&gt;data);

   g_print ("pad name %s\n", gst_pad_get_name (pad));
   
   pads = g_list_next (pads);
 }
    ...
    </programlisting>
    <sect2 id="sec-pads-functions">
      <title>Usefull pad functions</title>
      <para> 
        You can get the name of a pad with gst_pad_get_name () and set its name with
	get_pad_set_name();
      </para> 
      <para> 
        gst_pad_get_direction (GstPad *pad) can be used to query if the pad is a sink 
	or a src pad. Remember a src pad is a pad that can output data and a sink pad is 
	one that accepts data.
      </para> 
      <para> 
        You can get the parent of the pad, this is the element that this pad belongs to,
	with get_pad_set_parent(GstPad *pad). This function will return a pointer to a
	GstObject.
      </para> 
    </sect2>
  </sect1>
  <sect1 id="sec-pads-description">
    <title>Capabilities of a GstPad</title>
    <para> 
      Since the pads play a very important role in how the element is viewed by the
      outside world, a mechanism is implemented to describe the pad by using capabilities.
    </para>
    <para> 
      We will briefly describe what capabilities are, enough for you to get a basic understanding
      of the concepts. You will find more information on how to create capabilities in the 
      filter-writer-guide.
    </para>

    <sect2 id="sec-pads-caps">
      <title>What is a capability</title>
      <para> 
        A capability is attached to a pad in order to describe what type of media the pad
	can handle.
      </para>
      <para> 
        A capability is named and consists of a MIME type and a set of properties. Its data 
	structure is:
      </para>
      <programlisting>
struct _GstCaps {
  gchar *name;                  /* the name of this caps */

  guint16 id;                   /* type id (major type) */

  GstProps *properties;         /* properties for this capability */
};
      </programlisting>
      <para> 
        Below is a dump of the capabilities of the element mpg123, as shown by 
	<command>gstreamer-inspect</command>.    
	You can see two pads: sink and src. Both pads have capability information attached to them.
      </para>
      <para> 
	The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has
	three properties: layer, bitrate and framed.
      </para>
      <para> 
	The src pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has
	four properties: format, depth, rate and channels.
      </para>
      <programlisting>
Pads:
  SINK: 'sink'
    ....
      Capabilities:
      'mpg123_sink':
       MIME type: 'audio/mp3':
        layer: Integer range: 1 - 3
        bitrate: Integer range: 8 - 320
        framed: Boolean: TRUE

  SRC: 'src'
    ....
    Capabilities:
    'mpg123_src':
     MIME type: 'audio/raw':
      format: Integer: 16
      depth: Integer: 16
      rate: Integer range: 11025 - 48000
      channels: List:
        Integer: 1
        Integer: 2
      </programlisting>
    </sect2>
    <sect2 id="sec-pads-props">
      <title>What are properties</title>
      <para> 
        Properties are used to describe extra information for the capabilities. The properties
	basically exist of a key (a string) and a value. There are different possibile value types
	that can be used:
      </para> 

      <itemizedlist>
        <listitem>
          <para>
            An integer value: the property has this exact value. 
          </para>
        </listitem>
        <listitem>
          <para>
            An integer range value. The property denotes a range of possible values. In the case
	    of the mpg123 element: the src pad has a property rate that can go from 11025 to 48000.
          </para>
        </listitem>
        <listitem>
          <para>
	    A boolean value.
          </para>
        </listitem>
        <listitem>
          <para>
	    a fourcc value: this is a value that is commonly used to describe an encoding for video,
	    as used be the AVI specification.
          </para>
        </listitem>
        <listitem>
          <para>
	    A list value: the property can take any value from a list.
          </para>
        </listitem>
      </itemizedlist>

    </sect2>
    <sect2 id="sec-pads-caps-use">
      <title>What are the capabilities used for?</title>
      <para> 
        Capabilities describe in great detail the type of media that is handled by the pads.
	They are mostly used for:
      </para> 
      <itemizedlist>
        <listitem>
          <para>
            Autoplugging: automatically finding plugins for a set of capabilities
          </para>
        </listitem>
        <listitem>
          <para>
            Compatibility detection: when two pads are connected, <application>GStreamer</application>
	    can verify if the two pads are talking about the same media types.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="sec-pads-caps-get">
      <title>Getting the capabilities of a pad</title>
      <para> 
        A pad can have a GList of capabilities attached to it. You can get the capabilities list
	with:
      </para>
    <programlisting>
 GList *caps;
    ...
 caps = gst_pad_get_caps_list (pad);

 g_print ("pad name %s\n", gst_pad_get_name (pad));
 
 while (caps) {
   GstCaps *cap = (GstCaps *) caps-&gt;data;

   g_print (" Capability name %s, MIME type\n", gst_caps_get_name (cap), 
                                                gst_caps_get_mime (cap));
   
   caps = g_list_next (caps);
 }
    ...
    </programlisting>
    </sect2>

  </sect1>
</chapter>