docs/pwg/building-pads.xml

   1
   2 <!-- ############ chapter ############# -->
   3
   4 <chapter id="chapter-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 a <function>_setcaps
  12     ()</function>-functions to configure for a particular format and how to
  13     register functions to let data flow through the element.
  14   </para>
  15   <para>
  16     In the element <function>_init ()</function> function, you create the pad
  17     from the pad template that has been registered with the element class in
  18     the <function>_base_init ()</function> function. After creating the pad,
  19     you have to set a <function>_setcaps ()</function> function pointer and
  20     optionally a <function>_getcaps ()</function> function pointer. Also, you
  21     have to set a <function>_chain ()</function> function pointer.
  22     Alternatively, pads can also operate in looping mode, which means that they
  23     can pull data themselves. More on this topic later. After that, you have
  24     to register the pad with the element. This happens like this:
  25   </para>
  26   <programlisting><!-- example-begin init.func a --><!--
  27 #include "filter.h"
  28 #include &lt;string.h&gt;
  29
  30 static GstStateChangeReturn
  31 gst_my_filter_change_state (GstElement * element, GstStateChange transition);
  32
  33 GST_BOILERPLATE (GstMyFilter, gst_my_filter, GstElement, GST_TYPE_ELEMENT);
  34
  35 static void
  36 gst_my_filter_base_init (gpointer klass)
  37 {
  38   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
  39   static GstElementDetails my_filter_details = {
  40     "An example plugin",
  41     "Example/FirstExample",
  42     "Shows the basic structure of a plugin",
  43     "your name <your.name@your.isp>"
  44   };
  45   static GstStaticPadTemplate sink_factory =
  46   GST_STATIC_PAD_TEMPLATE (
  47     "sink",
  48     GST_PAD_SINK,
  49     GST_PAD_ALWAYS,
  50     GST_STATIC_CAPS ("ANY")
  51   );
  52   static GstStaticPadTemplate src_factory =
  53   GST_STATIC_PAD_TEMPLATE (
  54     "src",
  55     GST_PAD_SRC,
  56     GST_PAD_ALWAYS,
  57     GST_STATIC_CAPS ("ANY")
  58   );
  59
  60   gst_element_class_set_details (element_class, &my_filter_details);
  61   gst_element_class_add_pad_template (element_class,
  62         gst_static_pad_template_get (&src_factory));
  63   gst_element_class_add_pad_template (element_class,
  64         gst_static_pad_template_get (&sink_factory));
  65 }
  66
  67 static void
  68 gst_my_filter_class_init (GstMyFilterClass * klass)
  69 {
  70   GST_ELEMENT_CLASS (klass)->change_state = gst_my_filter_change_state;
  71 }
  72 --><!-- example-end init.func a -->
  73 <!-- example-begin init.func b -->
  74 static gboolean         gst_my_filter_setcaps   (GstPad        *pad,
  75                                                  GstCaps       *caps);
  76 static GstFlowReturn    gst_my_filter_chain     (GstPad        *pad,
  77                                                  GstBuffer     *buf);
  78 <!-- example-end init.func b -->
  79 <!-- example-begin init.func c --><!--
  80 static GstCaps *        gst_my_filter_getcaps   (GstPad        *pad);
  81 static gboolean         gst_my_filter_event     (GstPad        *pad,
  82                                                  GstEvent      *event);
  83 --><!-- example-end init.func c -->
  84 <!-- example-begin init.func d -->
  85
  86 static void
  87 gst_my_filter_init (GstMyFilter *filter, GstMyFilterClass *filter_klass)
  88 {
  89   GstElementClass *klass = GST_ELEMENT_CLASS (filter_klass);
  90
  91   /* pad through which data comes in to the element */
  92   filter-&gt;sinkpad = gst_pad_new_from_template (
  93         gst_element_class_get_pad_template (klass, "sink"), "sink");
  94   gst_pad_set_setcaps_function (filter-&gt;sinkpad, gst_my_filter_setcaps);
  95   gst_pad_set_chain_function (filter-&gt;sinkpad, gst_my_filter_chain);
  96 <!-- example-end init.func d -->
  97 <!-- example-begin init.func e --><!--
  98   gst_pad_set_getcaps_function (filter-&gt;sinkpad, gst_my_filter_getcaps);
  99   gst_pad_set_event_function (filter-&gt;sinkpad, gst_my_filter_event);
 100 --><!-- example-end init.func e -->
 101 <!-- example-begin init.func f -->
 102   gst_element_add_pad (GST_ELEMENT (filter), filter-&gt;sinkpad);
 103
 104   /* pad through which data goes out of the element */
 105   filter-&gt;srcpad = gst_pad_new_from_template (
 106         gst_element_class_get_pad_template (klass, "src"), "src");
 107 <!-- example-end init.func f -->
 108 <!-- example-begin init.func g --><!--
 109   gst_pad_set_getcaps_function (filter-&gt;srcpad, gst_my_filter_getcaps);
 110 --><!-- example-end init.func g -->
 111 <!-- example-begin init.func h -->
 112   gst_element_add_pad (GST_ELEMENT (filter), filter-&gt;srcpad);
 113
 114   /* properties initial value */
 115   filter->silent = FALSE;
 116 }
 117   <!-- example-end init.func h --></programlisting>
 118
 119   <sect1 id="section-pads-linkfn" xreflabel="The link function">
 120   <title>The setcaps-function</title>
 121   <para>
 122     The <function>_setcaps ()</function>-function is called during caps
 123     negotiation, which is discussed in great detail in <xref
 124     linkend="chapter-negotiation"/>. This is the process where the linked
 125     pads decide on the streamtype that will transfer between them. A full
 126     list of type-definitions can be found in <xref
 127     linkend="chapter-building-types"/>. A <function>_link ()</function>
 128     receives a pointer to a <ulink type="http"
 129     url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps</classname></ulink>
 130     struct that defines the proposed streamtype, and can respond with
 131     either <quote>yes</quote> (<symbol>TRUE</symbol>) or <quote>no</quote>
 132     (<symbol>FALSE</symbol>). If the element responds positively towards
 133     the streamtype, that type will be used on the pad. An example:
 134   </para>
 135   <programlisting><!-- example-begin caps.func a -->
 136 static gboolean
 137 gst_my_filter_setcaps (GstPad  *pad,
 138                        GstCaps *caps)
 139 {
 140   GstStructure *structure = gst_caps_get_structure (caps, 0);
 141   GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
 142   const gchar *mime;
 143
 144   /* Since we're an audio filter, we want to handle raw audio
 145    * and from that audio type, we need to get the samplerate and
 146    * number of channels. */
 147   mime = gst_structure_get_name (structure);
 148   if (strcmp (mime, "audio/x-raw-int") != 0) {
 149     GST_WARNING ("Wrong mimetype %s provided, we only support %s",
 150                  mime, "audio/x-raw-int");
 151     return FALSE;
 152   }
 153
 154   /* we're a filter and don't touch the properties of the data.
 155    * That means we can set the given caps unmodified on the next
 156    * element, and use that negotiation return value as ours. */
 157   if (!gst_pad_set_caps (filter-&gt;srcpad, caps))
 158     return FALSE;
 159
 160   /* Capsnego succeeded, get the stream properties for internal
 161    * usage and return success. */
 162   gst_structure_get_int (structure, "rate", &amp;filter-&gt;samplerate);
 163   gst_structure_get_int (structure, "channels", &amp;filter-&gt;channels);
 164
 165   g_print ("Caps negotiation succeeded with %d Hz @ %d channels\n",
 166            filter-&gt;samplerate, filter-&gt;channels);
 167
 168   return TRUE;
 169 }
 170 <!-- example-end caps.func a -->
 171 <!-- example-begin caps.func b --><!--
 172 static GstCaps *
 173 gst_my_filter_getcaps (GstPad * pad)
 174 {
 175   GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
 176   GstPad *otherpad = (pad == filter-&gt;srcpad) ? filter-&gt;sinkpad :
 177                                                   filter-&gt;srcpad;
 178   GstCaps *othercaps = gst_pad_get_allowed_caps (otherpad);
 179
 180   return othercaps;
 181 }
 182   --><!-- example-end caps.func b --></programlisting>
 183   <para>
 184     In here, we check the mimetype of the provided caps. Normally, you don't
 185     need to do that in your own plugin/element, because the core does that
 186     for you. We simply use it to show how to retrieve the mimetype from a
 187     provided set of caps. Types are stored in <ulink type="http"
 188     url="../../gstreamer/html/gstreamer-GstStructure.html"><classname>GstStructure
 189     </classname></ulink> internally. A <ulink
 190     type="http" url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps
 191     </classname></ulink> is nothing more than a small
 192     wrapper for 0 or more structures/types. From the structure, you can also
 193     retrieve properties, as is shown above with the function
 194     <function>gst_structure_get_int ()</function>.
 195   </para>
 196   <para>
 197     If your <function>_link ()</function> function does not need to perform
 198     any specific operation (i.e. it will only forward caps), you can set it
 199     to <function>gst_pad_proxy_link ()</function>. This is a link forwarding
 200     function implementation provided by the core. It is useful for elements
 201     such as <classname>identity</classname>.
 202   </para>
 203   </sect1>
 204 <!-- example-begin pads.c --><!--
 205 #include "init.func"
 206 #include "caps.func"
 207
 208 static gboolean
 209 gst_my_filter_event (GstPad * pad, GstEvent * event)
 210 {
 211   return gst_pad_event_default (pad, event);
 212 }
 213
 214 static GstFlowReturn
 215 gst_my_filter_chain (GstPad * pad, GstBuffer * buf)
 216 {
 217   return gst_pad_push (GST_MY_FILTER (GST_OBJECT_PARENT (pad))->srcpad, buf);
 218 }
 219
 220 static GstStateChangeReturn
 221 gst_my_filter_change_state (GstElement * element, GstStateChange transition)
 222 {
 223   return GST_CALL_PARENT_WITH_DEFAULT (GST_ELEMENT_CLASS,
 224       change_state, (element, transition), GST_STATE_CHANGE_SUCCESS);
 225 }
 226
 227 #include "register.func"
 228 --><!-- example-end pads.c -->
 229 </chapter>
 230