<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Specifying the pads</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Building a Filter"
HREF="part-building.html"><LINK
REL="PREVIOUS"
TITLE="The plugin_init function"
HREF="section-boiler-plugininit.html"><LINK
REL="NEXT"
TITLE="The getcaps function"
HREF="section-pads-getcapsfn.html"></HEAD
><BODY
CLASS="chapter"
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
> Plugin Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="section-boiler-plugininit.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="section-pads-getcapsfn.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-building-pads"
></A
>Chapter 4. Specifying the pads</H1
><P
> As explained before, pads are the port through which data goes in and out
of your element, and that makes them a very important item in the process
of element creation. In the boilerplate code, we have seen how static pad
templates take care of registering pad templates with the element class.
Here, we will see how to create actual elements, use <CODE
CLASS="function"
>_link ()</CODE
>
and <CODE
CLASS="function"
>_getcaps ()</CODE
> functions to let other elements know
their capabilities and how to register functions to let data flow through
the element.
</P
><P
> In the element <CODE
CLASS="function"
>_init ()</CODE
> function, you create the pad
from the pad template that has been registered with the element class in
the <CODE
CLASS="function"
>_base_init ()</CODE
> function. After creating the pad,
you have to set a <CODE
CLASS="function"
>_link ()</CODE
> function pointer and a
<CODE
CLASS="function"
>_getcaps ()</CODE
> function pointer. Optionally, you can
set a <CODE
CLASS="function"
>_chain ()</CODE
> function pointer (on sink pads in
filter and sink elements) through which data will come in to the element,
or (on source pads in source elements) a <CODE
CLASS="function"
>_get ()</CODE
>
function pointer through which data will be pulled from the element. After
that, you have to register the pad with the element. This happens like
this:
</P
><PRE
CLASS="programlisting"
> static GstPadLinkReturn gst_my_filter_link (GstPad *pad,
const GstCaps *caps);
static GstCaps * gst_my_filter_getcaps (GstPad *pad);
static void gst_my_filter_chain (GstPad *pad,
GstData *data);
static void
gst_my_filter_init (GstMyFilter *filter)
{
GstElementClass *klass = GST_ELEMENT_GET_CLASS (filter);
/* pad through which data comes in to the element */
filter->sinkpad = gst_pad_new_from_template (
gst_element_class_get_pad_template (klass, "sink"), "sink");
gst_pad_set_link_function (filter->sinkpad, gst_my_filter_link);
gst_pad_set_getcaps_function (filter->sinkpad, gst_my_filter_getcaps);
gst_pad_set_chain_function (filter->sinkpad, gst_my_filter_chain);
gst_element_add_pad (GST_ELEMENT (filter), filter->sinkpad);
/* pad through which data goes out of the element */
filter->srcpad = gst_pad_new_from_template (
gst_element_class_get_pad_template (klass, "src"), "src");
gst_pad_set_link_function (filter->srcpad, gst_my_filter_link);
gst_pad_set_getcaps_function (filter->srcpad, gst_my_filter_getcaps);
gst_element_add_pad (GST_ELEMENT (filter), filter->srcpad);
[..]
}
</PRE
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-pads-linkfn"
>4.1. The link function</A
></H1
><P
> The <CODE
CLASS="function"
>_link ()</CODE
> is called during caps negotiation. This
is the process where the linked pads decide on the streamtype that will
transfer between them. A full list of type-definitions can be found in
<A
HREF="chapter-building-types.html"
>Chapter 13</A
>. A <CODE
CLASS="function"
>_link ()</CODE
>
receives a pointer to a <CODE
CLASS="classname"
>GstCaps</CODE
> struct that
defines the proposed streamtype, and can respond with either
<SPAN
CLASS="QUOTE"
>"yes"</SPAN
> (<CODE
CLASS="classname"
>GST_PAD_LINK_OK</CODE
>),
<SPAN
CLASS="QUOTE"
>"no"</SPAN
> (<CODE
CLASS="classname"
>GST_PAD_LINK_REFUSED</CODE
>) or
<SPAN
CLASS="QUOTE"
>"don't know yet"</SPAN
> (<CODE
CLASS="classname"
>GST_PAD_LINK_DELAYED</CODE
>).
If the element responds positively towards the streamtype, that type
will be used on the pad. An example:
</P
><PRE
CLASS="programlisting"
> static GstPadLinkReturn
gst_my_filter_link (GstPad *pad,
const GstCaps *caps)
{
GstStructure *structure = gst_caps_get_structure (caps, 0);
GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
GstPad *otherpad = (pad == filter->srcpad) ? filter->sinkpad :
filter->srcpad;
GstPadLinkReturn ret;
const gchar *mime;
/* Since we're an audio filter, we want to handle raw audio
* and from that audio type, we need to get the samplerate and
* number of channels. */
mime = gst_structure_get_name (structure);
if (strcmp (mime, "audio/x-raw-int") != 0) {
GST_WARNING ("Wrong mimetype %s provided, we only support %s",
mime, "audio/x-raw-int");
return GST_PAD_LINK_REFUSED;
}
/* we're a filter and don't touch the properties of the data.
* That means we can set the given caps unmodified on the next
* element, and use that negotiation return value as ours. */
ret = gst_pad_try_set_caps (otherpad, gst_caps_copy (caps));
if (GST_PAD_LINK_FAILED (ret))
return ret;
/* Capsnego succeeded, get the stream properties for internal
* usage and return success. */
gst_structure_get_int (structure, "rate", &filter->samplerate);
gst_structure_get_int (structure, "channels", &filter->channels);
g_print ("Caps negotiation succeeded with %d Hz @ %d channels\n",
filter->samplerate, filter->channels);
return ret;
}
</PRE
><P
> In here, we check the mimetype of the provided caps. Normally, you don't
need to do that in your own plugin/element, because the core does that
for you. We simply use it to show how to retrieve the mimetype from a
provided set of caps. Types are stored in <CODE
CLASS="classname"
>GstStructure</CODE
>
internally. A <CODE
CLASS="classname"
>GstCaps</CODE
> is nothing more than a small
wrapper for 0 or more structures/types. From the structure, you can also
retrieve properties, as is shown above with the function
<CODE
CLASS="function"
>gst_structure_get_int ()</CODE
>.
</P
><P
> If your <CODE
CLASS="function"
>_link ()</CODE
> function does not need to perform
any specific operation (i.e. it will only forward caps), you can set it
to <CODE
CLASS="function"
>gst_pad_proxy_link</CODE
>. This is a link forwarding
function implementation provided by the core. It is useful for elements
such as <CODE
CLASS="classname"
>identity</CODE
>.
</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="section-boiler-plugininit.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="section-pads-getcapsfn.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>The plugin_init function</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-building.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>The getcaps function</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
