mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-07 07:05:52 +00:00
7c24fc7450
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...
102 lines
3.7 KiB
XML
102 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>
|