<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Capabilities of a pad</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="GStreamer Application Development Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Pads"
HREF="chapter-pads.html"><LINK
REL="PREVIOUS"
TITLE="Pads"
HREF="chapter-pads.html"><LINK
REL="NEXT"
TITLE="Plugins"
HREF="chapter-plugins.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Application Development Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="chapter-pads.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 5. Pads</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-plugins.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-caps"
>5.2. Capabilities of a pad</A
></H1
><P
>
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.
</P
><P
>
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.
</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-pads-caps"
>5.2.1. Capabilities</A
></H2
><P
>
Capabilities are attached to a pad in order to describe
what type of media the pad can handle.
</P
><P
>
Capabilities is shorthand for "capability chain". A capability chain
is a chain of one capability or more.
</P
><P
> 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".
<A
NAME="AEN231"
HREF="#FTN.AEN231"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
>
</P
><P
>
Below is a dump of the capabilities of the element mad, as shown by
<B
CLASS="command"
>gst-inspect</B
>.
You can see two pads: sink and src. Both pads have capability information attached to them.
</P
><P
>
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.
</P
><P
>
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.
</P
><PRE
CLASS="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
</PRE
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-pads-props"
>5.2.2. What are properties ?</A
></H2
><P
>
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:
</P
><P
></P
><UL
><LI
><P
> basic types:
</P
><P
></P
><UL
><LI
><P
> an integer value: the property has this exact value.
</P
></LI
><LI
><P
> a boolean value: the property is either TRUE or FALSE.
</P
></LI
><LI
><P
> 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.
<A
NAME="AEN252"
HREF="#FTN.AEN252"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
>
</P
></LI
><LI
><P
> a float value: the property has this exact floating point value.
</P
></LI
><LI
><P
> a string value.
</P
></LI
></UL
></LI
><LI
><P
> range types:
</P
><P
></P
><UL
><LI
><P
> an integer range value: the property denotes a range of
possible integer. For example, the wavparse element has
a source pad where the "rate" property can go from 8000 to
48000.
</P
></LI
><LI
><P
> a float range value: the property denotes a range of possible
floating point values.
</P
></LI
></UL
></LI
><LI
><P
> a list value: the property can take any value from a list of
basic value types or range types.
</P
></LI
></UL
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-pads-caps-use"
>5.2.3. What capabilities are used for</A
></H2
><P
>
Capabilities describe in great detail the type of media that is handled by the pads.
They are mostly used for:
</P
><P
></P
><UL
><LI
><P
> Autoplugging: automatically finding plugins for a set of capabilities
</P
></LI
><LI
><P
> Compatibility detection: when two pads are linked, <SPAN
CLASS="application"
>GStreamer</SPAN
>
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".
</P
></LI
></UL
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN231"
HREF="section-caps.html#AEN231"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
> 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 <CODE
CLASS="classname"
>GstCaps</CODE
>
element.
</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN252"
HREF="section-caps.html#AEN252"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
> fourcc values consist of four bytes.
<A
HREF="http://www.fourcc.org"
TARGET="_top"
>The FOURCC
Definition List</A
> is the most complete resource
on the allowed fourcc values.
</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="chapter-pads.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="chapter-plugins.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Pads</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="chapter-pads.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Plugins</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
