mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-06-03 05:59:44 +00:00
018a6f381b
Original commit message from CVS: First draft of Chapter 1 (introduction) and Chapter 2 (basic concepts) of the GStreamer manual.
78 lines
3 KiB
Plaintext
78 lines
3 KiB
Plaintext
<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>
|