manual-data.md

   1 ---
   2 title: Buffers and Events
   3 ...
   4
   5 # Buffers and Events
   6
   7 The data flowing through a pipeline consists of a combination of buffers
   8 and events. Buffers contain the actual media data. Events contain
   9 control information, such as seeking information and end-of-stream
  10 notifiers. All this will flow through the pipeline automatically when
  11 it's running. This chapter is mostly meant to explain the concept to
  12 you; you don't need to do anything for this.
  13
  14 ## Buffers
  15
  16 Buffers contain the data that will flow through the pipeline you have
  17 created. A source element will typically create a new buffer and pass it
  18 through a pad to the next element in the chain. When using the GStreamer
  19 infrastructure to create a media pipeline you will not have to deal with
  20 buffers yourself; the elements will do that for you.
  21
  22 A buffer consists, amongst others, of:
  23
  24   - Pointers to memory objects. Memory objects encapsulate a region in
  25     the memory.
  26
  27   - A timestamp for the buffer.
  28
  29   - A refcount that indicates how many elements are using this buffer.
  30     This refcount will be used to destroy the buffer when no element has
  31     a reference to it.
  32
  33   - Buffer flags.
  34
  35 The simple case is that a buffer is created, memory allocated, data put
  36 in it, and passed to the next element. That element reads the data, does
  37 something (like creating a new buffer and decoding into it), and
  38 unreferences the buffer. This causes the data to be free'ed and the
  39 buffer to be destroyed. A typical video or audio decoder works like
  40 this.
  41
  42 There are more complex scenarios, though. Elements can modify buffers
  43 in-place, i.e. without allocating a new one. Elements can also write to
  44 hardware memory (such as from video-capture sources) or memory allocated
  45 from the X-server (using XShm). Buffers can be read-only, and so on.
  46
  47 ## Events
  48
  49 Events are control particles that are sent both up- and downstream in a
  50 pipeline along with buffers. Downstream events notify fellow elements of
  51 stream states. Possible events include seeking, flushes, end-of-stream
  52 notifications and so on. Upstream events are used both in
  53 application-element interaction as well as element-element interaction
  54 to request changes in stream state, such as seeks. For applications,
  55 only upstream events are important. Downstream events are just explained
  56 to get a more complete picture of the data concept.
  57
  58 Since most applications seek in time units, our example below does so
  59 too:
  60
  61 ``` c
  62 static void
  63 seek_to_time (GstElement *element,
  64           guint64     time_ns)
  65 {
  66   GstEvent *event;
  67
  68   event = gst_event_new_seek (1.0, GST_FORMAT_TIME,
  69                   GST_SEEK_FLAG_NONE,
  70                   GST_SEEK_METHOD_SET, time_ns,
  71                   GST_SEEK_TYPE_NONE, G_GUINT64_CONSTANT (0));
  72   gst_element_send_event (element, event);
  73 }
  74
  75 ```
  76
  77 The function `gst_element_seek ()` is a shortcut for this. This is
  78 mostly just to show how it all works.
  79