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 media 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       <listitem>
  48         <para>
  49           Buffer flags.
  50         </para>
  51       </listitem>
  52     </itemizedlist>
  53     <para>
  54       The simple case is that a buffer is created, memory allocated, data
  55       put in it, and passed to the next element.  That element reads the
  56       data, does something (like creating a new buffer and decoding into
  57       it), and unreferences the buffer.  This causes the data to be free'ed
  58       and the buffer to be destroyed. A typical video or audio decoder
  59       works like this.
  60     </para>
  61     <para>
  62       There are more complex scenarios, though. Elements can modify buffers
  63       in-place, i.e. without allocating a new one. Elements can also write
  64       to hardware memory (such as from video-capture sources) or memory
  65       allocated from the X-server (using XShm). Buffers can be read-only,
  66       and so on.
  67     </para>
  68   </sect1>
  69
  70   <sect1 id="section-events">
  71     <title>Events</title>
  72     <para>
  73       Events are control particles that are sent both up- and downstream in
  74       a pipeline along with buffers. Downstream events notify fellow elements
  75       of stream states. Possible events include seeking, flushes,
  76       end-of-stream notifications and so on. Upstream events are used both
  77       in application-element interaction as well as element-element interaction
  78       to request changes in stream state, such as seeks. For applications,
  79       only upstream events are important. Downstream events are just
  80       explained to get a more complete picture of the data concept.
  81     </para>
  82     <para>
  83       Since most applications seek in time units, our example below does so
  84       too:
  85     </para>
  86     <programlisting>
  87 static void
  88 seek_to_time (GstElement *element,
  89               guint64     time_ns)
  90 {
  91   GstEvent *event;
  92
  93   event = gst_event_new_seek (1.0, GST_FORMAT_TIME,
  94                               GST_SEEK_FLAG_NONE,
  95                               GST_SEEK_METHOD_SET, time_ns,
  96                               GST_SEEK_TYPE_NONE, G_GUINT64_CONSTANT (0));
  97   gst_element_send_event (element, event);
  98 }
  99     </programlisting>
 100     <para>
 101       The function <function>gst_element_seek ()</function> is a shortcut
 102       for this. This is mostly just to show how it all works.
 103     </para>
 104   </sect1>
 105 </chapter>