gstreamer/docs/manual/buffers.sgml
Wim Taymans 018a6f381b First draft of Chapter 1 (introduction) and Chapter 2 (basic concepts) of the GStreamer manual.
Original commit message from CVS:
First draft of Chapter 1 (introduction) and Chapter 2 (basic concepts)
of the GStreamer manual.
2000-08-16 21:38:57 +00:00

77 lines
3 KiB
Text

<chapter id="cha-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 the 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>
The most important information in the buffer is:
<itemizedlist>
<listitem>
<para>
A pointer to a piece of memory.
</para>
</listitem>
<listitem>
<para>
The size of the memory.
</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 is having a reference to it.
</para>
</listitem>
<listitem>
<para>
A list of metadata that describes the context of the buffers memory. In the case
of audio data, for example, it would provide the samplerate, depth and channel
count.
</para>
<para>
GStreamer provides a registry where different metadata types can be registered
so that everybody is talking about the same data.
</para>
</listitem>
</itemizedlist>
</para>
<para>
GStreamer provides functions to create custom buffer create/destroy algorithms, called
a <classname>GstBufferPool</classname>. This makes it possible to efficiently
allocate and destroy buffer memory. It also makes it possible to exchange memory between
elements by passing the <classname>GstBufferPool</classname>. A video element can,
for example, create a custom buffer allocation algorithm that creates buffers with XSHM
as the buffer memory. An element can use this algorithm to create and fill the buffer
with data.
</para>
<para>
The simple case is that a buffer is created, memory allocated, data put
in it, and passed to the next filter. That filter reads the data, does
something (like creating a new buffer and decoding into it), and
unreferences the buffer. This causes the data to be freed and the buffer
to be destroyed. A typical MPEG audio decoder works like this.
</para>
<para>
A more complex case is when the filter modifies the data in place. It
does so and simply passes on the buffer to the next element. This is just
as easy to deal with. An element that works in place has to be carefull when
the buffer is used in more than one element; a copy on write has to made in this
situation.
</para>
<para>
Before an element can operate on the buffers memory, is has to check the metadata
attached to it (if any). An MPEG audio decoder has to ignore a buffer with video
metadata (in which case the pipeline is probably constructed by connecting the
wrong elements, anyway).
</para>
</chapter>