docs/manual/basics-data.xml

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