mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
99 lines
3.5 KiB
XML
99 lines
3.5 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 pipeline 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>
|
|
A pointer to a piece of memory.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The size of 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>
|
|
</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 discontinuities, flushes,
|
|
end-of-stream notifications and so on. Upstream events are used both
|
|
in application-element interaction as well as event-event 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 (GST_SEEK_METHOD_SET |
|
|
GST_FORMAT_TIME,
|
|
time_ns);
|
|
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>
|