docs/pwg/building-chainfn.xml

   1
   2 <!-- ############ chapter ############# -->
   3
   4 <chapter id="chapter-building-chainfn">
   5   <title>The chain function</title>
   6   <para>
   7     The chain function is the function in which all data processing takes
   8     place. In the case of a simple filter, <function>_chain ()</function>
   9     functions are mostly lineair functions - so for each incoming buffer,
  10     one buffer will go out, too. Below is a very simple implementation of
  11     a chain function:
  12   </para>
  13   <programlisting>
  14 static void
  15 gst_my_filter_chain (GstPad  *pad,
  16                      GstData *data)
  17 {
  18   GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
  19   GstBuffer *buf = GST_BUFFER (data);
  20
  21   if (!filter->silent)
  22     g_print ("Have data of size %u bytes!\n", GST_BUFFER_SIZE (buf));
  23
  24   gst_pad_push (filter->srcpad, GST_DATA (buf));
  25 }
  26   </programlisting>
  27   <para>
  28     Obviously, the above doesn't do much useful. Instead of printing that the
  29     data is in, you would normally process the data there. Remember, however,
  30     that buffers are not always writable. In more advanced elements (the ones
  31     that do event processing), the incoming data might not even be a buffer.
  32   </para>
  33   <programlisting>
  34 static void
  35 gst_my_filter_chain (GstPad  *pad,
  36                      GstData *data)
  37 {
  38   GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
  39   GstBuffer *buf, *outbuf;
  40
  41   if (GST_IS_EVENT (data)) {
  42     GstEvent *event = GST_EVENT (data);
  43
  44     switch (GST_EVENT_TYPE (event)) {
  45       case GST_EVENT_EOS:
  46         /* end-of-stream, we should close down all stream leftovers here */
  47         gst_my_filter_stop_processing (filter);
  48         /* fall-through to default event handling */
  49       default:
  50         gst_pad_event_default (pad, event);
  51         break;
  52     }
  53     return;
  54   }
  55
  56   buf = GST_BUFFER (data);
  57   outbuf = gst_my_filter_process_data (buf);
  58   gst_buffer_unref (buf);
  59   if (!outbuf) {
  60     /* something went wrong - signal an error */
  61     gst_element_error (GST_ELEMENT (filter), STREAM, FAILED, (NULL), (NULL));
  62     return;
  63   }
  64
  65   gst_pad_push (filter->srcpad, GST_DATA (outbuf));
  66 }
  67   </programlisting>
  68   <para>
  69     In some cases, it might be useful for an element to have control over the
  70     input data rate, too. In that case, you probably want to write a so-called
  71     <emphasis>loop-based</emphasis> element. Source elements (with only source
  72     pads) can also be <emphasis>get-based</emphasis> elements. These concepts
  73     will be explained in the advanced section of this guide, and in the section
  74     that specifically discusses source pads.
  75   </para>
  76 </chapter>