gstreamer/docs/manual/pads.sgml
Wim Taymans 3d34ce7b95 Updated the manual and the docs.
Original commit message from CVS:
Updated the manual and the docs.
Removed the esdsink in gst/elements/ we have a real one not in the
plugins dir.
Added more APIs to query the plugins, types and caps. more fields now
have a getter and a setter. This is needed to make gstreamer wrapper
fiendly.
Added gst_element_disconnect beacuse we also have a gst_element_connect
2001-01-06 02:35:17 +00:00

214 lines
6.6 KiB
Text

<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>