mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-20 07:16:55 +00:00
bd97601128
Original commit message from CVS: 2004-07-15 Zaheer Abbas Merali <zaheerabbas at merali dot> * docs/manual/pads.xml: * docs/manual/pads-api.xml: grammar fix
243 lines
8.5 KiB
XML
243 lines
8.5 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 <classname>GstCaps</classname>
|
|
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>
|