gstreamer/docs/manual/pads-api.xml
Thomas Vander Stichele abe422b141 reorganizing manual so that concepts are explained before code is shown.
Original commit message from CVS:
reorganizing manual so that concepts are explained before code is shown.
needs some proofreading, will get to it.
2003-12-29 14:15:02 +00:00

301 lines
9.2 KiB
XML

<chapter id="cha-pads-api">
<title>Pads</title>
<para>
As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
interface to 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(see
<xref linkend="sec-caps"/>)
</para>
<para>
Pads are either source or sink pads. The terminology is defined from the
view of the element itself: elements accept data on their sink pads, and
send data out on their source pads. Sink pads are drawn on the left,
while source pads are drawn on the right of an element. In general,
data flows from left to right in the graph.<footnote>
<para>
In reality, there is no objection to data flowing from a
source pad to the sink pad of an element upstream. Data will, however,
always flow from a source pad of one element to the sink pad of
another.
</para></footnote>
</para>
<sect1 id="sec-pads-api-type">
<title>Types of pads</title>
<sect2 id="sec-pads-api-dynamic">
<title>Dynamic pads</title>
<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_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline)
{
g_print("***** a new pad %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
...
// link 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 useful
...
mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux");
g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline);
...
// start the pipeline
gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
...
}
</programlisting>
<note>
<para>
A pipeline cannot be changed in the PLAYING state.
</para>
</note>
</sect2>
<sect2 id="sec-pads-api-request">
<title>Request pads</title>
<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 link another element to it.
</para>
<programlisting>
...
GstPad *pad;
...
element = gst_element_factory_make ("tee", "element");
pad = gst_element_get_request_pad (element, "src%d");
g_print ("new pad %s\n", gst_pad_get_name (pad));
...
</programlisting>
<para>
The gst_element_get_request_pad 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
pad template. This is very useful if you want to link an element
to a multiplexer element and you need to request a pad that is
compatible. The gst_element_get_compatible_pad is used to request
a compatible pad, as is shown in the next example.
</para>
<programlisting>
...
GstPadTemplate *templ;
GstPad *pad;
...
element = gst_element_factory_make ("tee", "element");
mad = gst_element_factory_make ("mad", "mad");
templ = gst_element_get_pad_template_by_name (mad, "sink");
pad = gst_element_get_compatible_pad (element, templ);
g_print ("new pad %s\n", gst_pad_get_name (pad));
...
</programlisting>
</sect2>
</sect1>
<sect1 id="sec-api-caps">
<title>Capabilities of a pad</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 data that can
flow through 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
Plugin Writer's Guide.
</para>
<sect2 id="sec-pads-api-caps">
<title>Capabilities</title>
<para>
Capabilities are attached to a pad in order to describe
what type of media the pad can handle.
</para>
<para>
Its 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>
</sect2>
<sect2 id="sec-pads-api-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 %s\n", gst_pad_get_name (pad));
while (caps) {
g_print (" Capability name %s, MIME type %s\n",
gst_caps_get_name (cap),
gst_caps_get_mime (cap));
caps = caps-&gt;next;
}
...
</programlisting>
</sect2>
<sect2 id="sec-pads-api-caps-create">
<title>Creating capability structures</title>
<para>
While capabilities are mainly used inside a plugin to describe the
media type of the pads, the application programmer also has to have
basic understanding of capabilities 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:
<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 range 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>