mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-12 19:36:38 +00:00
276 lines
8.6 KiB
Text
276 lines
8.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->data);
|
|
|
|
g_print ("pad name %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-synamic">
|
|
<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 %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");
|
|
gtk_signal_connect (GTK_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>
|
|
</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->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>
|