mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-05 17:09:48 +00:00
4e0df2c413
Original commit message from CVS: * testsuite/caps/caps_strings : audio/ac3 => audio/x-ac3 * docs/manual/pads-api.xml : audio/wav => audio/x-wav * docs/random/uraeus/gstreamer_and_midi.txt : audio/wav => audio/x-wav
301 lines
9.3 KiB
XML
301 lines
9.3 KiB
XML
<chapter id="chapter-pads-api">
|
|
<title>Pads</title>
|
|
<para>
|
|
As we have seen in <xref linkend="chapter-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="section-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="section-pads-api-type">
|
|
<title>Types of pads</title>
|
|
|
|
<sect2 id="section-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="section-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="section-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="section-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="section-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->next;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="section-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/x-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/x-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/x-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>
|