<!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-api.html"><LINK
REL="PREVIOUS"
TITLE="Pads"
HREF="chapter-pads-api.html"><LINK
REL="NEXT"
TITLE="Plugins"
HREF="chapter-plugins-api.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-api.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 13. Pads</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-plugins-api.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-api-caps"
>13.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-api-caps"
>13.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
> Its structure is:
</P
><PRE
CLASS="programlisting"
> struct _GstCaps {
gchar *name; /* the name of this caps */
guint16 id; /* type id (major type) */
guint refcount; /* caps are refcounted */
GstProps *properties; /* properties for this capability */
GstCaps *next; /* caps can be chained together */
};
</PRE
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-pads-api-caps-get"
>13.2.2. Getting the capabilities of a pad</A
></H2
><P
>
A pad can have a chain of capabilities attached to it. You can get the capabilities chain
with:
</P
><PRE
CLASS="programlisting"
> GstCaps *caps;
...
caps = gst_pad_get_caps (pad);
g_print ("pad name %s\n", gst_pad_get_name (pad));
while (caps) {
g_print (" Capability name %s, MIME type %s\n",
gst_caps_get_name (cap),
gst_caps_get_mime (cap));
caps = caps->next;
}
...
</PRE
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-pads-api-caps-create"
>13.2.3. Creating capability structures</A
></H2
><P
>
While capabilities are mainly used inside a plugin to describe the
media type of the pads, the application programmer also has to have
basic understanding of capabilities in order to interface with the
plugins, specially when using the autopluggers.
</P
><P
>
As we said, a capability has a name, a mime-type and some
properties. The signature of the function to create a new
<CODE
CLASS="classname"
>GstCaps</CODE
> structure is:
<PRE
CLASS="programlisting"
> GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
</PRE
>
</P
><P
> You can therefore create a new capability with no properties like this:
<PRE
CLASS="programlisting"
> GstCaps *newcaps;
newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
</PRE
>
</P
><P
> <CODE
CLASS="classname"
>GstProps</CODE
> basically consist of a set of key-value pairs
and are created with a function with this signature:
<PRE
CLASS="programlisting"
> GstProps* gst_props_new (const gchar *firstname, ...);
</PRE
>
</P
><P
> The keys are given as strings and the values are given with a set of macros:
<P
></P
><UL
><LI
><P
> GST_PROPS_INT(a): An integer value
</P
></LI
><LI
><P
> GST_PROPS_FLOAT(a): A floating point value
</P
></LI
><LI
><P
> GST_PROPS_FOURCC(a): A fourcc value
</P
></LI
><LI
><P
> GST_PROPS_BOOLEAN(a): A boolean value
</P
></LI
><LI
><P
> GST_PROPS_STRING(a): A string value
</P
></LI
></UL
>
The values can also be specified as ranges with:
<P
></P
><UL
><LI
><P
> GST_PROPS_INT_RANGE(a,b): An integer range from a to b
</P
></LI
><LI
><P
> GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
</P
></LI
></UL
>
All of the above values can be given with a list too, using:
<P
></P
><UL
><LI
><P
> GST_PROPS_LIST(a,...): A list of property values.
</P
></LI
></UL
>
</P
><P
> A more complex capability with properties is created like this:
<PRE
CLASS="programlisting"
> GstCaps *newcaps;
newcaps = gst_caps_new ("my_caps",
"audio/wav",
gst_props_new (
"bitrate", GST_PROPS_INT_RANGE (11025,22050),
"depth", GST_PROPS_INT (16),
"signed", GST_PROPS_LIST (
GST_PROPS_BOOLEAN (TRUE),
GST_PROPS_BOOLEAN (FALSE)
),
NULL
);
</PRE
>
Optionally, the convenient shortcut macro can be used. The above complex
capability can be created with:
<PRE
CLASS="programlisting"
> GstCaps *newcaps;
newcaps = GST_CAPS_NEW ("my_caps",
"audio/wav",
"bitrate", GST_PROPS_INT_RANGE (11025,22050),
"depth", GST_PROPS_INT (16),
"signed", GST_PROPS_LIST (
GST_PROPS_BOOLEAN (TRUE),
GST_PROPS_BOOLEAN (FALSE)
)
);
</PRE
>
</P
></DIV
></DIV
><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-api.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-api.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-api.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Plugins</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
