2 <!-- ############ chapter ############# -->
4 <chapter id="chapter-other-source" xreflabel="Writing a Source">
5 <title>Writing a Source</title>
7 Source elements are the start of a data streaming pipeline. Source
8 elements have no sink pads and have one or more source pads. We will
9 focus on single-sourcepad elements here, but the concepts apply equally
10 well to multi-sourcepad elements. This chapter will explain the essentials
11 of source elements, which features it should implement and which it
12 doesn't have to, and how source elements will interact with other
13 elements in a pipeline.
16 <sect1 id="section-source-getfn" xreflabel="The get()-function">
17 <title>The get()-function</title>
19 Source elements have the special option of having a
20 <function>_get ()</function>-function rather than a
21 <function>_loop ()</function>- or <function>_chain
22 ()</function>-function. A <function>_get ()</function>-function is
23 called by the scheduler every time the next elements needs data. Apart
24 from corner cases, every source element will want to be <function>_get
28 static GstData * gst_my_source_get (GstPad *pad);
31 gst_my_source_init (GstMySource *src)
34 gst_pad_set_get_function (src->srcpad, gst_my_source_get);
38 gst_my_source_get (GstPad *pad)
42 buffer = gst_buffer_new ();
43 GST_BUFFER_DATA (buf) = g_strdup ("hello pipeline!");
44 GST_BUFFER_SIZE (buf) = strlen (GST_BUFFER_DATA (buf));
45 /* terminating '/0' */
46 GST_BUFFER_MAZSIZE (buf) = GST_BUFFER_SIZE (buf) + 1;
48 return GST_DATA (buffer);
53 <sect1 id="section-source-padfn" xreflabel="Events, querying and converting">
54 <title>Events, querying and converting</title>
56 One of the most important functions of source elements is to
57 implement correct query, convert and event handling functions.
58 Those will continuously describe the current state of the stream.
59 Query functions can be used to get stream properties such as current
60 position and length. This can be used by fellow elements to convert
61 this same value into a different unit, or by applications to provide
62 information about the length/position of the stream to the user.
63 Conversion functions are used to convert such values from one unit
64 to another. Lastly, events are mostly used to seek to positions
65 inside the stream. Any function is essentially optional, but the
66 element should try to provide as much information as it knows. Note
67 that elements providing an event function should also list their
68 supported events in an <function>_get_event_mask ()</function>
69 function. Elements supporting query operations should list the
70 supported operations in a <function>_get_query_types
71 ()</function> function. Elements supporting either conversion
72 or query operations should also implement a <function>_get_formats
73 ()</function> function.
76 An example source element could, for example, be an element that
77 continuously generates a wave tone at 44,1 kHz, mono, 16-bit. This
78 element will generate 44100 audio samples per second or 88,2 kB/s.
79 This information can be used to implement such functions:
82 static GstFormat * gst_my_source_format_list (GstPad *pad);
83 static GstQueryType * gst_my_source_query_list (GstPad *pad);
85 static gboolean gst_my_source_convert (GstPad *pad,
90 static gboolean gst_my_source_query (GstPad *pad,
96 gst_my_source_init (GstMySource *src)
99 gst_pad_set_convert_function (src->srcpad, gst_my_source_convert);
100 gst_pad_set_formats_function (src->srcpad, gst_my_source_format_list);
101 gst_pad_set_query_function (src->srcpad, gst_my_source_query);
102 gst_pad_set_query_type_function (src->srcpad, gst_my_source_query_list);
106 * This function returns an enumeration of supported GstFormat
107 * types in the query() or convert() functions. See gst/gstformat.h
112 gst_my_source_format_list (GstPad *pad)
114 static const GstFormat formats[] = {
116 GST_FORMAT_DEFAULT, /* means "audio samples" */
125 * This function returns an enumeration of the supported query()
126 * operations. Since we generate audio internally, we only provide
127 * an indication of how many samples we've played so far. File sources
128 * or such elements could also provide GST_QUERY_TOTAL for the total
129 * stream length, or other things. See gst/gstquery.h for details.
132 static GstQueryType *
133 gst_my_source_query_list (GstPad *pad)
135 static const GstQueryType query_types[] = {
144 * And below are the logical implementations.
148 gst_my_source_convert (GstPad *pad,
155 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
158 case GST_FORMAT_TIME:
160 case GST_FORMAT_TIME:
164 case GST_FORMAT_BYTES:
165 *to_val = from_val / (GST_SECOND / (44100 * 2));
168 case GST_FORMAT_DEFAULT:
169 *to_val = from_val / (GST_SECOND / 44100);
178 case GST_FORMAT_BYTES:
180 case GST_FORMAT_TIME:
181 *to_val = from_val * (GST_SECOND / (44100 * 2));
184 case GST_FORMAT_BYTES:
188 case GST_FORMAT_DEFAULT:
189 *to_val = from_val / 2;
198 case GST_FORMAT_DEFAULT:
200 case GST_FORMAT_TIME:
201 *to_val = from_val * (GST_SECOND / 44100);
204 case GST_FORMAT_BYTES:
205 *to_val = from_val * 2;
208 case GST_FORMAT_DEFAULT:
227 gst_my_source_query (GstPad *pad,
232 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
236 case GST_QUERY_POSITION:
237 res = gst_pad_convert (pad, GST_FORMAT_BYTES, src->total_bytes,
250 Be sure to increase src->total_bytes after each call to your
251 <function>_get ()</function> function.
254 Event handling has already been explained previously in the events
259 <sect1 id="section-source-sync" xreflabel="Time, clocking and synchronization">
260 <title>Time, clocking and synchronization</title>
262 The above example does not provide any timing info, but will suffice
263 for elementary data sources such as a file source or network data
264 source element. Things become slightly more complicated, but still
265 very simple, if we create artificial video or audio data sources,
266 such as a video test image source or an artificial audio source (e.g.
267 <classname>audiotestsrc</classname>).
268 It will become more complicated if we want the element to be a
269 realtime capture source, such as a video4linux source (for reading
270 video frames from a TV card) or an ALSA source (for reading data
271 from soundcards supported by an ALSA-driver). Here, we will need to
272 make the element aware of timing and clocking.
275 Timestamps can essentially be generated from all the information
276 given above without any difficulty. We could add a very small amount
277 of code to generate perfectly timestamped buffers from our
278 <function>_get ()</function>-function:
282 gst_my_source_init (GstMySource *src)
285 src->total_bytes = 0;
289 gst_my_source_get (GstPad *pad)
291 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
293 GstFormat fmt = GST_FORMAT_TIME;
295 GST_BUFFER_DURATION (buf) = GST_BUFFER_SIZE (buf) * (GST_SECOND / (44100 * 2));
296 GST_BUFFER_TIMESTAMP (buf) = src->total_bytes * (GST_SECOND / (44100 * 2));
297 src->total_bytes += GST_BUFFER_SIZE (buf);
299 return GST_DATA (buf);
302 static GstStateChangeReturn
303 gst_my_source_change_state (GstElement *element, GstStateChange transition)
305 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
306 GstMySource *src = GST_MY_SOURCE (element);
308 /* First, handle upwards state changes */
309 switch (transition) {
310 case GST_STATE_READY_TO_PAUSED:
317 ret = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
318 if (ret == GST_STATE_CHANGE_FAILURE)
321 /* Now handle downwards state changes after chaining up */
322 switch (transition) {
323 case GST_STATE_PAUSED_TO_READY:
324 src->total_bytes = 0;
334 That wasn't too hard. Now, let's assume real-time elements. Those
335 can either have hardware-timing, in which case we can rely on backends
336 to provide sync for us (in which case you probably want to provide a
337 clock), or we will have to emulate that internally (e.g. to acquire
338 sync in artificial data elements such as
339 <classname>audiotestsrc</classname>).
340 Let's first look at the second option (software sync). The first option
341 (hardware sync + providing a clock) does not require any special code
342 with respect to timing, and the clocking section already explained how
354 gst_my_source_class_init (GstMySourceClass *klass)
356 GObjectClass *object_class = G_OBJECT_CLASS (klass);
358 g_object_class_install_property (object_class, ARG_SYNC,
359 g_param_spec_boolean ("sync", "Sync", "Synchronize to clock",
360 FALSE, G_PARAM_READWRITE |
361 G_PARAM_STATIC_STRINGS));
366 gst_my_source_init (GstMySource *src)
373 gst_my_source_get (GstPad *pad)
375 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
380 gst_element_wait (GST_ELEMENT (src), GST_BUFFER_TIMESTAMP (buf));
383 return GST_DATA (buf);
387 gst_my_source_get_property (GObject *object,
392 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
397 g_value_set_boolean (value, src->sync);
404 gst_my_source_get_property (GObject *object,
409 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
414 src->sync = g_value_get_boolean (value);
421 Most of this is GObject wrapping code. The actual code to do
422 software-sync (in the <function>_get ()</function>-function)
426 <sect1 id="section-source-buffers" xreflabel="Using special memory">
427 <title>Using special memory</title>
429 In some cases, it might be useful to use specially allocated memory
430 (e.g. <function>mmap ()</function>'ed DMA'able memory) in
431 your buffers, and those will require special handling when they are
432 being dereferenced. For this, &GStreamer; uses the concept of
433 buffer-free functions. Those are special functions pointers that an
434 element can set on buffers that it created itself. The given function
435 will be called when the buffer has been dereferenced, so that the
436 element can clean up or re-use memory internally rather than using
437 the default implementation (which simply calls
438 <function>g_free ()</function> on the data pointer).
442 gst_my_source_buffer_free (GstBuffer *buf)
444 GstMySource *src = GST_MY_SOURCE (GST_BUFFER_PRIVATE (buf));
446 /* do useful things here, like re-queueing the buffer which
447 * makes it available for DMA again. The default handler will
448 * not free this buffer because of the GST_BUFFER_DONTFREE
453 gst_my_source_get (GstPad *pad)
455 GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
458 buf = gst_buffer_new ();
459 GST_BUFFER_FREE_DATA_FUNC (buf) = gst_my_source_buffer_free;
460 GST_BUFFER_PRIVATE (buf) = src;
461 GST_BUFFER_FLAG_SET (buf, GST_BUFFER_READONLY | GST_BUFFER_DONTFREE);
464 return GST_DATA (buf);
468 Note that this concept should <emphasis>not</emphasis> be used to
469 decrease the number of calls made to functions such as
470 <function>g_malloc ()</function> inside your element. We
471 have better ways of doing that elsewhere (&GStreamer; core, Glib,
472 Glibc, Linux kernel, etc.).