mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-18 07:47:17 +00:00
626cbdc8b2
Original commit message from CVS: cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to README
244 lines
8.6 KiB
XML
244 lines
8.6 KiB
XML
<chapter id="chapter-pads">
|
|
<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-type">
|
|
<title>Types of pad</title>
|
|
|
|
<sect2 id="section-pads-dynamic">
|
|
<title>Dynamic pads</title>
|
|
<para>
|
|
Some elements might not have all of their pads when the element is
|
|
created. This
|
|
can happen, for example, with an MPEG system demultiplexer. The
|
|
demultiplexer will create its pads at runtime when it detects the
|
|
different elementary streams in the MPEG system stream.
|
|
</para>
|
|
<para>
|
|
Running <application>gst-inspect mpegdemux</application> will show that
|
|
the element has only one pad: a sink pad called 'sink'. The other pads are
|
|
"dormant". You can see this in the pad template because there is
|
|
an 'Exists: Sometimes'
|
|
property. Depending on the type of MPEG file you play, the pads will
|
|
be created. We
|
|
will see that this is very important when you are going to create dynamic
|
|
pipelines later on in this manual.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="section-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 useful
|
|
for multiplexers, 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>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="section-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-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>
|
|
Capabilities is shorthand for "capability chain". A capability chain
|
|
is a chain of one capability or more.
|
|
</para>
|
|
<para>
|
|
The basic entity is a capability, and is defined by a name, a MIME
|
|
type and a set of properties. A capability can be chained to
|
|
another capability, which is why we commonly refer to a chain of
|
|
capability entities as "capabilities".
|
|
<footnote>
|
|
<para>
|
|
It is important to understand that the term "capabilities" refers
|
|
to a chain of one capability or more. This will be clearer when
|
|
you see the structure definition of a <ulink type="http"
|
|
url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps
|
|
</classname></ulink>element.
|
|
</para>
|
|
</footnote>
|
|
</para>
|
|
<para>
|
|
Below is a dump of the capabilities of the element mad, as shown by
|
|
<command>gst-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 source 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 template: 'sink'
|
|
Availability: Always
|
|
Capabilities:
|
|
'mad_sink':
|
|
MIME type: 'audio/mp3':
|
|
|
|
SRC template: 'src'
|
|
Availability: Always
|
|
Capabilities:
|
|
'mad_src':
|
|
MIME type: 'audio/raw':
|
|
format: String: int
|
|
endianness: Integer: 1234
|
|
width: Integer: 16
|
|
depth: Integer: 16
|
|
channels: Integer range: 1 - 2
|
|
law: Integer: 0
|
|
signed: Boolean: TRUE
|
|
rate: Integer range: 11025 - 48000
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="section-pads-props">
|
|
<title>What are properties ?</title>
|
|
<para>
|
|
Properties are used to describe extra information for
|
|
capabilities. A property consists of a key (a string) and
|
|
a value. There are different possible value types that can be used:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
basic types:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
an integer value: the property has this exact value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a boolean value: the property is either TRUE or FALSE.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a fourcc value: this is a value that is commonly used to
|
|
describe an encoding for video,
|
|
as used for example by the AVI specification.
|
|
<footnote><para>
|
|
fourcc values consist of four bytes.
|
|
<ulink url="http://www.fourcc.org" type="http">The FOURCC
|
|
Definition List</ulink> is the most complete resource
|
|
on the allowed fourcc values.
|
|
</para></footnote>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a float value: the property has this exact floating point value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a string value.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
range types:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
an integer range value: the property denotes a range of
|
|
possible integers. For example, the wavparse element has
|
|
a source pad where the "rate" property can go from 8000 to
|
|
48000.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a float range value: the property denotes a range of possible
|
|
floating point values.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a list value: the property can take any value from a list of
|
|
basic value types or range types.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect2>
|
|
<sect2 id="section-pads-caps-use">
|
|
<title>What capabilities are 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 linked, <application>GStreamer</application>
|
|
can verify if the two pads are talking about the same media types.
|
|
The process of linking two pads and checking if they are compatible
|
|
is called "caps negotiation".
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|