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 &percnt;s\n", gst_pad_get_name (pad));
   
   pads = g_list_next (pads);
 }
    ...
    </programlisting>
    <sect2 id="sec-pads-functions">
      <title>Useful 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>
    <sect2 id="sec-pads-dynamic">
      <title>Dynamic pads</title>
      <para> 
        Some elements might not have their pads when they are created. This can, for 
	example, happen with an MPEG2 system demuxer. The demuxer will create its 
	pads at runtime when it detects the different elementary streams in the MPEG2
	system stream. 
      </para> 
      <para> 
        Running <application>gstreamer-inspect mpeg2parse</application> will show that
	the element has only one pad: a sink pad called 'sink'. The other pads are 
	"dormant" as you can see in the padtemplates from the 'Exists: Sometimes'
	property. Depending on the type of MPEG2 file you play, the pads are created. We
	will see that this is very important when you are going to create dynamic 
	pipelines later on in this manual.
      </para> 
      <para> 
        You can attach a signal to an element to inform you when the element has created
	a new pad from one of its padtemplates. The following piece of code is an example
	of how to do this:
      </para> 
      <programlisting>
static void
pad_connect_func (GstElement *parser, GstPad *pad, GstElement *pipeline)
{
  g_print("***** a new pad &percnt;s was created\n", gst_pad_get_name(pad));

  gst_element_set_state (pipeline, GST_STATE_PAUSED);

  if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) {
    // set up an AC3 decoder pipeline
    ...
    // connect pad to the AC3 decoder pipeline
    ...
  }
  gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY);
}

int 
main(int argc, char *argv[]) 
{
  GstElement *pipeline;
  GstElement *mpeg2parser;

  // create pipeline and do something usefull
  ...
  
  mpeg2parser = gst_elementfactory_make ("mpeg2parse", "mpeg2parse");
  g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_connect_func, pipeline);  
  ...

  // start the pipeline
  gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
  ...
}
      </programlisting>
      <note>
        <para> 
          You need to set the pipeline to READY or NULL if you want to change it.
        </para> 
      </note>
    </sect2>
    <sect2 id="sec-pads-request">
      <title>Request pads</title>
      <para> 
        An element can also have request pads. These pads are not created automatically
	but are only created on demand. This is very usefull for muxers, aggregators
	and tee elements.
      </para> 
      <para> 
        The tee element, for example, has one input pad and a request padtemplate for the
	output pads. Whenever an element wants to get an output pad from the tee element, it 
	has to request the pad.
      </para> 
      <para> 
        The following piece of code can be used to get a pad from the tee element. After
	the pad has been requested, it can be used to connect another element to it.
      </para> 
      <programlisting>
    ...
  GstPad *pad;
    ...
  element = gst_elementfactory_make ("tee", "element");

  pad = gst_element_request_pad_by_name (element, "src%d");
  g_print ("new pad %s\n", gst_pad_get_name (pad));
    ...
      </programlisting>
      <para> 
        The gst_element_request_pad_by_name method can be used to get a pad
	from the element based on the name_template of the padtemplate.
      </para> 
      <para> 
        It is also possible to request a pad that is compatible with another
	padtemplate. This is very usefull if you want to connect an element to
	a muxer element and you need to request a pad that is compatible. The
	gst_element_request_compatible_pad is used to request a compatible pad, as
	is shown in the next example.
      </para> 
      <programlisting>
    ...
  GstPadTemplate *templ;
  GstPad *pad;
    ...
  element = gst_elementfactory_make ("tee", "element");
  mp3parse = gst_elementfactory_make ("mp3parse", "mp3parse");

  templ = gst_element_get_padtemplate_by_name (mp3parse, "sink");

  pad = gst_element_request_compatible_pad (element, templ);
  g_print ("new pad %s\n", gst_pad_get_name (pad));
  ...
      </programlisting>
    </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) */

  guint refcount; 		/* caps are refcounted */

  GstProps *properties;         /* properties for this capability */

  GstCaps *next;		/* caps can be chained together */
};
      </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>
        <listitem>
          <para>
	    A float value: the property has this exact floating point value.
          </para>
        </listitem>
        <listitem>
          <para>
	    A float range value: denotes a range of possible floating point values.
          </para>
        </listitem>
        <listitem>
          <para>
	    A string value.
          </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 chain of capabilities attached to it. You can get the capabilities chain
	with:
      </para>
    <programlisting>
 GstCaps *caps;
    ...
 caps = gst_pad_get_caps (pad);

 g_print ("pad name &percnt;s\n", gst_pad_get_name (pad));
 
 while (caps) {
   g_print (" Capability name &percnt;s, MIME type &percnt;s\n", 
   				gst_caps_get_name (cap), 
                                gst_caps_get_mime (cap));
   
   caps = caps-&gt;next;
 }
    ...
    </programlisting>
    </sect2>
    <sect2 id="sec-pads-caps-create">
      <title>Creating capabilities structures</title>
      <para> 
        While the capabilities are mainly used inside the plugin to describe the media type of the
	pads, the application programmer also has to have basic understanding of caps in order to
	interface with the plugins, specially when using the autopluggers.
      </para>
      <para> 
        As we said, a capability has a name, a mime-type and some properties. The signature of the 
	function to create a new <classname>GstCaps *</classname> structure is like:
    <programlisting>
GstCaps*    gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
    </programlisting>
      </para>
      <para>
        You can therefore create a new capability with no properties like this:
    <programlisting>
  GstCaps *newcaps;
  
  newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
    </programlisting>
      </para>
      <para>
        <classname>GstProps</classname> basically consist of a set of key-value pairs
	and are created with a function with this signature:
    <programlisting>
GstProps*     gst_props_new   (const gchar *firstname, ...);
    </programlisting>
      </para>
      <para>
        The keys are given as strings and the values are given with a set of macros:
        <itemizedlist>
          <listitem>
            <para>
              GST_PROPS_INT(a): An integer value
            </para>
          </listitem>
          <listitem>
            <para>
              GST_PROPS_FLOAT(a): A floating point value
            </para>
          </listitem>
          <listitem>
            <para>
              GST_PROPS_FOURCC(a): A fourcc value
            </para>
          </listitem>
          <listitem>
            <para>
              GST_PROPS_BOOLEAN(a): A boolean value
            </para>
          </listitem>
          <listitem>
            <para>
              GST_PROPS_STRING(a): A string value
            </para>
          </listitem>
        </itemizedlist>
        The values can also be specified as ranges with:
        <itemizedlist>
          <listitem>
            <para>
              GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b
            </para>
          </listitem>
          <listitem>
            <para>
              GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
            </para>
          </listitem>
        </itemizedlist>
        All of the above values can be given with a list too, using:
        <itemizedlist>
          <listitem>
            <para>
              GST_PROPS_LIST(a,...): A list of property values.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        A more complex capability with properties is created like this:
        <programlisting>
  GstCaps *newcaps;
  
  newcaps = gst_caps_new ("my_caps", 
                          "audio/wav", 
  			  gst_props_new (
			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
			    "depth",   GST_PROPS_INT (16),
			    "signed",  GST_PROPS_LIST (
			     		 GST_PROPS_BOOLEAN (TRUE),
			     		 GST_PROPS_BOOLEAN (FALSE)
				       ),
			    NULL
			  );
        </programlisting>
	Optionally the convenient shortcut macro can be used. The above complex 
	capability can be created with:
        <programlisting>
  GstCaps *newcaps;
  
  newcaps = GST_CAPS_NEW ("my_caps", 
                          "audio/wav", 
			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
			    "depth",   GST_PROPS_INT (16),
			    "signed",  GST_PROPS_LIST (
			     		 GST_PROPS_BOOLEAN (TRUE),
			     		 GST_PROPS_BOOLEAN (FALSE)
				       )
			  );
        </programlisting>
      </para>
    </sect2>

  </sect1>
</chapter>