docs/pwg/building-pads.xml

   1
   2 <!-- ############ chapter ############# -->
   3
   4 <chapter id="cha-building-pads">
   5   <title>Specifying the pads</title>
   6   <para>
   7     As explained before, pads are the port through which data goes in and out
   8     of your element, and that makes them a very important item in the process
   9     of element creation. In the boilerplate code, we have seen how static pad
  10     templates take care of registering pad templates with the element class.
  11     Here, we will see how to create actual elements, use <function>_link ()</function>
  12     and <function>_getcaps ()</function> functions to let other elements know
  13     their capabilities and how to register functions to let data flow through
  14     the element.
  15   </para>
  16   <para>
  17     In the element <function>_init ()</function> function, you create the pad
  18     from the pad template that has been registered with the element class in
  19     the <function>_base_init ()</function> function. After creating the pad,
  20     you have to set a <function>_link ()</function> function pointer and a
  21     <function>_getcaps ()</function> function pointer. Optionally, you can
  22     set a <function>_chain ()</function> function pointer (on sink pads in
  23     filter and sink elements) through which data will come in to the element,
  24     or (on source pads in source elements) a <function>_get ()</function>
  25     function pointer through which data will be pulled from the element. After
  26     that, you have to register the pad with the element. This happens like
  27     this:
  28   </para>
  29   <programlisting>
  30 static GstPadLinkReturn gst_my_filter_link      (GstPad        *pad,
  31                                                  const GstCaps *caps);
  32 static GstCaps *        gst_my_filter_getcaps   (GstPad        *pad);
  33 static void             gst_my_filter_chain     (GstPad        *pad,
  34                                                  GstData       *data);
  35
  36 static void
  37 gst_my_filter_init (GstMyFilter *filter)
  38 {
  39   GstElementClass *klass = GST_ELEMENT_GET_CLASS (filter);
  40
  41   /* pad through which data comes in to the element */
  42   filter-&gt;sinkpad = gst_pad_new_from_template (
  43         gst_element_class_get_pad_template (klass, "sink"), "sink");
  44   gst_pad_set_link_function (filter-&gt;sinkpad, gst_my_filter_link);
  45   gst_pad_set_getcaps_function (filter-&gt;sinkpad, gst_my_filter_getcaps);
  46   gst_pad_set_chain_function (filter-&gt;sinkpad, gst_my_filter_chain);
  47   gst_element_add_pad (GST_ELEMENT (filter), filter-&gt;sinkpad);
  48
  49   /* pad through which data goes out of the element */
  50   filter-&gt;srcpad = gst_pad_new_from_template (
  51         gst_element_class_get_pad_template (klass, "src"), "src");
  52   gst_pad_set_link_function (filter-&gt;srcpad, gst_my_filter_link);
  53   gst_pad_set_getcaps_function (filter-&gt;srcpad, gst_my_filter_getcaps);
  54   gst_element_add_pad (GST_ELEMENT (filter), filter-&gt;srcpad);
  55 [..]
  56 }
  57   </programlisting>
  58
  59   <sect1 id="sect-pads-linkfn" xreflabel="The link function">
  60   <title>The link function</title>
  61   <para>
  62     The <function>_link ()</function> is called during caps negotiation. This
  63     is the process where the linked pads decide on the streamtype that will
  64     transfer between them. A full list of type-definitions can be found in
  65     <xref linkend="cha-building-types"/>. A <function>_link ()</function>
  66     receives a pointer to a <classname>GstCaps</classname> struct that
  67     defines the proposed streamtype, and can respond with either
  68     <quote>yes</quote> (<classname>GST_PAD_LINK_OK</classname>),
  69     <quote>no</quote> (<classname>GST_PAD_LINK_REFUSED</classname>) or
  70     <quote>don't know yet</quote> (<classname>GST_PAD_LINK_DELAYED</classname>).
  71     If the element responds positively towards the streamtype, that type
  72     will be used on the pad. An example:
  73   </para>
  74   <programlisting>
  75 static GstPadLinkReturn
  76 gst_my_filter_link (GstPad        *pad,
  77                     const GstCaps *caps)
  78 {
  79   GstStructure *structure = gst_caps_get_structure (caps, 0);
  80   GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
  81   GstPad *otherpad = (pad == filter-&gt;srcpad) ? filter-&gt;sinkpad :
  82                                                filter-&gt;srcpad;
  83   GstPadLinkReturn ret;
  84   const gchar *mime;
  85
  86   /* Since we're an audio filter, we want to handle raw audio
  87    * and from that audio type, we need to get the samplerate and
  88    * number of channels. */
  89   mime = gst_structure_get_name (structure);
  90   if (strcmp (mime, "audio/x-raw-int") != 0) {
  91     GST_WARNING ("Wrong mimetype %s provided, we only support %s",
  92                  mime, "audio/x-raw-int");
  93     return GST_PAD_LINK_REFUSED;
  94   }
  95
  96   /* we're a filter and don't touch the properties of the data.
  97    * That means we can set the given caps unmodified on the next
  98    * element, and use that negotiation return value as ours. */
  99   ret = gst_pad_try_set_caps (otherpad, gst_caps_copy (caps));
 100   if (GST_PAD_LINK_FAILED (ret))
 101     return ret;
 102
 103   /* Capsnego succeeded, get the stream properties for internal
 104    * usage and return success. */
 105   gst_structure_get_int (structure, "rate", &amp;filter-&gt;samplerate);
 106   gst_structure_get_int (structure, "channels", &amp;filter-&gt;channels);
 107
 108   g_print ("Caps negotiation succeeded with %d Hz @ %d channels\n",
 109            filter-&gt;samplerate, filter-&gt;channels);
 110
 111   return ret;
 112 }
 113   </programlisting>
 114   <para>
 115     In here, we check the mimetype of the provided caps. Normally, you don't
 116     need to do that in your own plugin/element, because the core does that
 117     for you. We simply use it to show how to retrieve the mimetype from a
 118     provided set of caps. Types are stored in <classname>GstStructure</classname>
 119     internally. A <classname>GstCaps</classname> is nothing more than a small
 120     wrapper for 0 or more structures/types. From the structure, you can also
 121     retrieve properties, as is shown above with the function
 122     <function>gst_structure_get_int ()</function>.
 123   </para>
 124   <para>
 125     If your <function>_link ()</function> function does not need to perform
 126     any specific operation (i.e. it will only forward caps), you can set it
 127     to <function>gst_pad_proxy_link</function>. This is a link forwarding
 128     function implementation provided by the core. It is useful for elements
 129     such as <classname>identity</classname>.
 130   </para>
 131   </sect1>
 132
 133   <sect1 id="sect-pads-getcapsfn" xreflabel="The getcaps function">
 134   <title>The getcaps function</title>
 135   <para>
 136     The <function>_getcaps ()</function> funtion is used to request the list
 137     of supported formats and properties from the element. In some cases, this
 138     will be equal to the formats provided by the pad template, in which case
 139     this function can be omitted. In some cases, too, it will not depend on
 140     anything inside this element, but it will rather depend on the input from
 141     another element linked to this element's sink or source pads. In that case,
 142     you can use <function>gst_pad_proxy_getcaps</function> as implementation,
 143     it provides getcaps forwarding in the core. However, in many cases, the
 144     format supported by this element cannot be defined externally, but is
 145     more specific than those provided by the pad template. In this case, you
 146     should use a <function>_getcaps ()</function> function. In the case as
 147     specified below, we assume that our filter is able to resample sound, so
 148     it would be able to provide any samplerate (indifferent from the samplerate
 149     specified on the other pad) on both pads. It explains how a
 150     <function>_getcaps ()</function> can be used to do this.
 151   </para>
 152   <programlisting>
 153 static GstCaps *
 154 gst_my_filter_getcaps (GstPad *pad)
 155 {
 156   GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
 157   GstPad *otherpad = (pad == filter-&gt;srcpad) ? filter-&gt;sinkpad :
 158                                                filter-&gt;srcpad;
 159   GstCaps *othercaps = gst_pad_get_allowed_caps (otherpad), *caps;
 160   gint n;
 161
 162   if (gst_caps_is_empty (othercaps))
 163     return othercaps;
 164
 165   /* We support *any* samplerate, indifferent from the samplerate
 166    * supported by the linked elements on both sides. */
 167   for (i = 0; i &lt; gst_caps_get_size (othercaps); i++) {
 168     GstStructure *structure = gst_caps_get_structure (othercaps, i);
 169
 170     gst_structure_remove_field (structure, "rate");
 171   }
 172   caps = gst_caps_intersect (othercaps, gst_pad_get_pad_template_caps (pad));
 173   gst_caps_free (othercaps);
 174
 175   return caps;
 176 }
 177   </programlisting>
 178   </sect1>
 179
 180   <sect1 id="sect-pads-explicitcaps" xreflabel="Explicit caps">
 181   <title>Explicit caps</title>
 182   <para>
 183     Obviously, many elements will not need this complex mechanism, because they
 184     are much simpler than that. They only support one format, or their format
 185     is fixed but the contents of the format depend on the stream or something
 186     else. In those cases, <emphasis>explicit caps</emphasis> are an easy way
 187     of handling caps. Explicit caps are an easy way of specifying one, fixed,
 188     supported format on a pad. Pads using explicit caps do not implement their
 189     own <function>_getcaps ()</function> or <function>_link ()</function>
 190     functions. When the exact format is known, an elements uses
 191     <function>gst_pad_set_explicit_caps ()</function> to specify the exact
 192     format. This is very useful for demuxers, for example.
 193   </para>
 194   <programlisting>
 195 static void
 196 gst_my_filter_init (GstMyFilter *filter)
 197 {
 198   GstElementClass *klass = GST_ELEMENT_GET_CLASS (filter);
 199 [..]
 200   filter-&gt;srcpad = gst_pad_new_from_template (
 201         gst_element_class_get_pad_template (klass, "src"), "src");
 202   gst_pad_use_explicit_caps (filter-&gt;srcpad);
 203 [..]
 204 }
 205
 206 static void
 207 gst_my_filter_somefunction (GstMyFilter *filter)
 208 {
 209   GstCaps *caps = ..;
 210 [..]
 211   gst_pad_set_explicit_caps (filter-&gt;srcpad, caps);
 212 [..]
 213 }
 214   </programlisting>
 215   </sect1>
 216 </chapter>
 217