docs/pwg/other-source.xml

   1
   2 <!-- ############ chapter ############# -->
   3
   4 <chapter id="chapter-other-source" xreflabel="Writing a Source">
   5   <title>Writing a Source</title>
   6   <para>
   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.
  14   </para>
  15
  16   <sect1 id="section-source-getfn" xreflabel="The get()-function">
  17     <title>The get()-function</title>
  18     <para>
  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
  25       ()</function>-based.
  26     </para>
  27     <programlisting>
  28 static GstData *        gst_my_source_get       (GstPad *pad);
  29
  30 static void
  31 gst_my_source_init (GstMySource *src)
  32 {
  33 [..]
  34   gst_pad_set_get_function (src->srcpad, gst_my_source_get);
  35 }
  36
  37 static GstData *
  38 gst_my_source_get (GstPad *pad)
  39 {
  40   GstBuffer *buffer;
  41
  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;
  47
  48   return GST_DATA (buffer);
  49 }
  50     </programlisting>
  51   </sect1>
  52
  53   <sect1 id="section-source-padfn" xreflabel="Events, querying and converting">
  54     <title>Events, querying and converting</title>
  55     <para>
  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.
  74     </para>
  75     <para>
  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:
  80     </para>
  81     <programlisting>
  82 static GstFormat *      gst_my_source_format_list       (GstPad      *pad);
  83 static GstQueryType *   gst_my_source_query_list        (GstPad      *pad);
  84
  85 static gboolean         gst_my_source_convert           (GstPad      *pad,
  86                                                          GstFormat    from_fmt,
  87                                                          gint64       from_val,
  88                                                          GstFormat   *to_fmt,
  89                                                          gint64      *to_val);
  90 static gboolean         gst_my_source_query             (GstPad      *pad,
  91                                                          GstQueryType type,
  92                                                          GstFormat   *to_fmt,
  93                                                          gint64      *to_val);
  94
  95 static void
  96 gst_my_source_init (GstMySource *src)
  97 {
  98 [..]
  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);
 103 }
 104
 105 /*
 106  * This function returns an enumeration of supported GstFormat
 107  * types in the query() or convert() functions. See gst/gstformat.h
 108  * for a full list.
 109  */
 110
 111 static GstFormat *
 112 gst_my_source_format_list (GstPad *pad)
 113 {
 114   static const GstFormat formats[] = {
 115     GST_FORMAT_TIME,
 116     GST_FORMAT_DEFAULT, /* means "audio samples" */
 117     GST_FORMAT_BYTES,
 118     0
 119   };
 120
 121   return formats;
 122 }
 123
 124 /*
 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.
 130  */
 131
 132 static GstQueryType *
 133 gst_my_source_query_list (GstPad *pad)
 134 {
 135   static const GstQueryType query_types[] = {
 136     GST_QUERY_POSITION,
 137     0,
 138   };
 139
 140   return query_types;
 141 }
 142
 143 /*
 144  * And below are the logical implementations.
 145  */
 146
 147 static gboolean
 148 gst_my_source_convert (GstPad    *pad,
 149                        GstFormat  from_fmt,
 150                        gint64     from_val,
 151                        GstFormat *to_fmt,
 152                        gint64    *to_val)
 153 {
 154   gboolean res = TRUE;
 155   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 156
 157   switch (from_fmt) {
 158     case GST_FORMAT_TIME:
 159       switch (*to_fmt) {
 160         case GST_FORMAT_TIME:
 161           /* nothing */
 162           break;
 163
 164         case GST_FORMAT_BYTES:
 165           *to_val = from_val / (GST_SECOND / (44100 * 2));
 166           break;
 167
 168         case GST_FORMAT_DEFAULT:
 169           *to_val = from_val / (GST_SECOND / 44100);
 170           break;
 171
 172         default:
 173           res = FALSE;
 174           break;
 175       }
 176       break;
 177
 178     case GST_FORMAT_BYTES:
 179       switch (*to_fmt) {
 180         case GST_FORMAT_TIME:
 181           *to_val = from_val * (GST_SECOND / (44100 * 2));
 182           break;
 183
 184         case GST_FORMAT_BYTES:
 185           /* nothing */
 186           break;
 187
 188         case GST_FORMAT_DEFAULT:
 189           *to_val = from_val / 2;
 190           break;
 191
 192         default:
 193           res = FALSE;
 194           break;
 195       }
 196       break;
 197
 198     case GST_FORMAT_DEFAULT:
 199       switch (*to_fmt) {
 200         case GST_FORMAT_TIME:
 201           *to_val = from_val * (GST_SECOND / 44100);
 202           break;
 203
 204         case GST_FORMAT_BYTES:
 205           *to_val = from_val * 2;
 206           break;
 207
 208         case GST_FORMAT_DEFAULT:
 209           /* nothing */
 210           break;
 211
 212         default:
 213           res = FALSE;
 214           break;
 215       }
 216       break;
 217
 218     default:
 219       res = FALSE;
 220       break;
 221   }
 222
 223   return res;
 224 }
 225
 226 static gboolean
 227 gst_my_source_query (GstPad      *pad,
 228                      GstQueryType type,
 229                      GstFormat   *to_fmt,
 230                      gint64      *to_val)
 231 {
 232   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 233   gboolean res = TRUE;
 234
 235   switch (type) {
 236     case GST_QUERY_POSITION:
 237       res = gst_pad_convert (pad, GST_FORMAT_BYTES, src->total_bytes,
 238                              to_fmt, to_val);
 239       break;
 240
 241     default:
 242       res = FALSE;
 243       break;
 244   }
 245
 246   return res;
 247 }
 248     </programlisting>
 249     <para>
 250       Be sure to increase src->total_bytes after each call to your
 251       <function>_get ()</function> function.
 252     </para>
 253     <para>
 254       Event handling has already been explained previously in the events
 255       chapter.
 256     </para>
 257   </sect1>
 258
 259   <sect1 id="section-source-sync" xreflabel="Time, clocking and synchronization">
 260     <title>Time, clocking and synchronization</title>
 261     <para>
 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.
 273     </para>
 274     <para>
 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:
 279     </para>
 280     <programlisting>
 281 static void
 282 gst_my_source_init (GstMySource *src)
 283 {
 284 [..]
 285   src->total_bytes = 0;
 286 }
 287
 288 static GstData *
 289 gst_my_source_get (GstPad *pad)
 290 {
 291   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 292   GstBuffer *buf;
 293   GstFormat fmt = GST_FORMAT_TIME;
 294 [..]
 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);
 298
 299   return GST_DATA (buf);
 300 }
 301
 302 static GstStateChangeReturn
 303 gst_my_source_change_state (GstElement *element, GstStateChange transition)
 304 {
 305   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
 306   GstMySource *src = GST_MY_SOURCE (element);
 307
 308   /* First, handle upwards state changes */
 309   switch (transition) {
 310     case GST_STATE_READY_TO_PAUSED:
 311       /* do something */
 312       break;
 313     default:
 314       break;
 315   }
 316
 317   ret = GST_ELEMENT_CLASS (parent_class)-&gt;change_state (element, transition);
 318   if (ret == GST_STATE_CHANGE_FAILURE)
 319     return ret;
 320
 321   /* Now handle downwards state changes after chaining up */
 322   switch (transition) {
 323     case GST_STATE_PAUSED_TO_READY:
 324       src->total_bytes = 0;
 325       break;
 326     default:
 327       break;
 328   }
 329
 330   return ret;
 331 }
 332     </programlisting>
 333     <para>
 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
 343       to provide a clock.
 344     </para>
 345     <programlisting>
 346 enum {
 347   ARG_0,
 348 [..]
 349   ARG_SYNC,
 350 [..]
 351 };
 352
 353 static void
 354 gst_my_source_class_init (GstMySourceClass *klass)
 355 {
 356   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 357 [..]
 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));
 362 [..]
 363 }
 364
 365 static void
 366 gst_my_source_init (GstMySource *src)
 367 {
 368 [..]
 369   src->sync = FALSE;
 370 }
 371
 372 static GstData *
 373 gst_my_source_get (GstPad *pad)
 374 {
 375   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 376   GstBuffer *buf;
 377 [..]
 378   if (src->sync) {
 379     /* wait on clock */
 380     gst_element_wait (GST_ELEMENT (src), GST_BUFFER_TIMESTAMP (buf));
 381   }
 382
 383   return GST_DATA (buf);
 384 }
 385
 386 static void
 387 gst_my_source_get_property (GObject    *object,
 388                             guint       prop_id,
 389                             GParamSpec *pspec,
 390                             GValue     *value)
 391 {
 392   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 393
 394   switch (prop_id) {
 395 [..]
 396     case ARG_SYNC:
 397       g_value_set_boolean (value, src->sync);
 398       break;
 399 [..]
 400   }
 401 }
 402
 403 static void
 404 gst_my_source_get_property (GObject      *object,
 405                             guint         prop_id,
 406                             GParamSpec   *pspec,
 407                             const GValue *value)
 408 {
 409   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 410
 411   switch (prop_id) {
 412 [..]
 413     case ARG_SYNC:
 414       src->sync = g_value_get_boolean (value);
 415       break;
 416 [..]
 417   }
 418 }
 419     </programlisting>
 420     <para>
 421       Most of this is GObject wrapping code. The actual code to do
 422       software-sync (in the <function>_get ()</function>-function)
 423       is relatively small.
 424     </para>
 425   </sect1>
 426   <sect1 id="section-source-buffers" xreflabel="Using special memory">
 427     <title>Using special memory</title>
 428     <para>
 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).
 439     </para>
 440     <programlisting>
 441 static void
 442 gst_my_source_buffer_free (GstBuffer *buf)
 443 {
 444   GstMySource *src = GST_MY_SOURCE (GST_BUFFER_PRIVATE (buf));
 445
 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
 449    * flag. */
 450 }
 451
 452 static GstData *
 453 gst_my_source_get (GstPad *pad)
 454 {
 455   GstMySource *src = GST_MY_SOURCE (gst_pad_get_parent (pad));
 456   GstBuffer *buf;
 457 [..]
 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);
 462 [..]
 463
 464   return GST_DATA (buf);
 465 }
 466     </programlisting>
 467     <para>
 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.).
 473     </para>
 474   </sect1>
 475 </chapter>