gstreamer/docs/manual/basics-data.xml
Wim Taymans 7c24fc7450 manual: fix up the manual
MIME-type -> media types
Fix up the manual in various places with the 1.0 way of doing things
such as probes, static elements, scheduling, ...
Add porting from 0.10 to 1.0 chapter.
Add probe example to build.
Remove some docs for remove components such as GstMixer and
GstPropertyProbe, XML...
2012-09-25 14:45:15 +02:00

101 lines
3.7 KiB
XML

<chapter id="chapter-data">
<title>Buffers and Events</title>
<para>
The data flowing through a pipeline consists of a combination of
buffers and events. Buffers contain the actual media data. Events
contain control information, such as seeking information and
end-of-stream notifiers. All this will flow through the pipeline
automatically when it's running. This chapter is mostly meant to
explain the concept to you; you don't need to do anything for this.
</para>
<sect1 id="section-buffers">
<title>Buffers</title>
<para>
Buffers contain the data that will flow through the pipeline you have
created. A source element will typically create a new buffer and pass
it through a pad to the next element in the chain. When using the
GStreamer infrastructure to create a media pipeline you will not have
to deal with buffers yourself; the elements will do that for you.
</para>
<para>
A buffer consists, amongst others, of:
</para>
<itemizedlist>
<listitem>
<para>
Pointers to memory objects. Memory objects encapsulate a region
in the memory.
</para>
</listitem>
<listitem>
<para>
A timestamp for the buffer.
</para>
</listitem>
<listitem>
<para>
A refcount that indicates how many elements are using this
buffer. This refcount will be used to destroy the buffer when no
element has a reference to it.
</para>
</listitem>
<listitem>
<para>
Buffer flags.
</para>
</listitem>
</itemizedlist>
<para>
The simple case is that a buffer is created, memory allocated, data
put in it, and passed to the next element. That element reads the
data, does something (like creating a new buffer and decoding into
it), and unreferences the buffer. This causes the data to be free'ed
and the buffer to be destroyed. A typical video or audio decoder
works like this.
</para>
<para>
There are more complex scenarios, though. Elements can modify buffers
in-place, i.e. without allocating a new one. Elements can also write
to hardware memory (such as from video-capture sources) or memory
allocated from the X-server (using XShm). Buffers can be read-only,
and so on.
</para>
</sect1>
<sect1 id="section-events">
<title>Events</title>
<para>
Events are control particles that are sent both up- and downstream in
a pipeline along with buffers. Downstream events notify fellow elements
of stream states. Possible events include seeking, flushes,
end-of-stream notifications and so on. Upstream events are used both
in application-element interaction as well as element-element interaction
to request changes in stream state, such as seeks. For applications,
only upstream events are important. Downstream events are just
explained to get a more complete picture of the data concept.
</para>
<para>
Since most applications seek in time units, our example below does so
too:
</para>
<programlisting>
static void
seek_to_time (GstElement *element,
guint64 time_ns)
{
GstEvent *event;
event = gst_event_new_seek (1.0, GST_FORMAT_TIME,
GST_SEEK_FLAG_NONE,
GST_SEEK_METHOD_SET, time_ns,
GST_SEEK_TYPE_NONE, G_GUINT64_CONSTANT (0));
gst_element_send_event (element, event);
}
</programlisting>
<para>
The function <function>gst_element_seek ()</function> is a shortcut
for this. This is mostly just to show how it all works.
</para>
</sect1>
</chapter>