markdown/pwg/building/chainfn.md

   1 ---
   2 title: The chain function
   3 ...
   4
   5 # The chain function
   6
   7 The chain function is the function in which all data processing takes
   8 place. In the case of a simple filter, `_chain ()` functions are mostly
   9 linear functions - so for each incoming buffer, one buffer will go out,
  10 too. Below is a very simple implementation of a chain function:
  11
  12 ``` c
  13
  14 static GstFlowReturn gst_my_filter_chain (GstPad    *pad,
  15                                           GstObject *parent,
  16                                           GstBuffer *buf);
  17
  18 [..]
  19
  20 static void
  21 gst_my_filter_init (GstMyFilter * filter)
  22 {
  23 [..]
  24   /* configure chain function on the pad before adding
  25    * the pad to the element */
  26   gst_pad_set_chain_function (filter->sinkpad,
  27       gst_my_filter_chain);
  28 [..]
  29 }
  30
  31 static GstFlowReturn
  32 gst_my_filter_chain (GstPad    *pad,
  33                      GstObject *parent,
  34              GstBuffer *buf)
  35 {
  36   GstMyFilter *filter = GST_MY_FILTER (parent);
  37
  38   if (!filter->silent)
  39     g_print ("Have data of size %" G_GSIZE_FORMAT" bytes!\n",
  40         gst_buffer_get_size (buf));
  41
  42   return gst_pad_push (filter->srcpad, buf);
  43 }
  44 ```
  45
  46 Obviously, the above doesn't do much useful. Instead of printing that
  47 the data is in, you would normally process the data there. Remember,
  48 however, that buffers are not always writeable.
  49
  50 In more advanced elements (the ones that do event processing), you may
  51 want to additionally specify an event handling function, which will be
  52 called when stream-events are sent (such as caps, end-of-stream,
  53 newsegment, tags, etc.).
  54
  55     static void
  56     gst_my_filter_init (GstMyFilter * filter)
  57     {
  58     [..]
  59       gst_pad_set_event_function (filter->sinkpad,
  60           gst_my_filter_sink_event);
  61     [..]
  62     }
  63
  64
  65
  66     static gboolean
  67     gst_my_filter_sink_event (GstPad    *pad,
  68                       GstObject *parent,
  69                       GstEvent  *event)
  70     {
  71       GstMyFilter *filter = GST_MY_FILTER (parent);
  72
  73       switch (GST_EVENT_TYPE (event)) {
  74         case GST_EVENT_CAPS:
  75           /* we should handle the format here */
  76           break;
  77         case GST_EVENT_EOS:
  78           /* end-of-stream, we should close down all stream leftovers here */
  79           gst_my_filter_stop_processing (filter);
  80           break;
  81         default:
  82           break;
  83       }
  84
  85       return gst_pad_event_default (pad, parent, event);
  86     }
  87
  88     static GstFlowReturn
  89     gst_my_filter_chain (GstPad    *pad,
  90                  GstObject *parent,
  91                  GstBuffer *buf)
  92     {
  93       GstMyFilter *filter = GST_MY_FILTER (parent);
  94       GstBuffer *outbuf;
  95
  96       outbuf = gst_my_filter_process_data (filter, buf);
  97       gst_buffer_unref (buf);
  98       if (!outbuf) {
  99         /* something went wrong - signal an error */
 100         GST_ELEMENT_ERROR (GST_ELEMENT (filter), STREAM, FAILED, (NULL), (NULL));
 101         return GST_FLOW_ERROR;
 102       }
 103
 104       return gst_pad_push (filter->srcpad, outbuf);
 105     }
 106
 107 In some cases, it might be useful for an element to have control over
 108 the input data rate, too. In that case, you probably want to write a
 109 so-called *loop-based* element. Source elements (with only source pads)
 110 can also be *get-based* elements. These concepts will be explained in
 111 the advanced section of this guide, and in the section that specifically
 112 discusses source pads.