mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-13 11:34:10 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs/: describe dparams (controller) for plugins unify docs a little more

Browse source 
Original commit message from CVS:
* docs/README:
* docs/manual/intro-basics.xml:
* docs/manual/intro-preface.xml:
* docs/manual/manual.xml:
* docs/pwg/advanced-dparams.xml:
* docs/pwg/intro-basics.xml:
* docs/pwg/intro-preface.xml:
* docs/pwg/pwg.xml:
describe dparams (controller) for plugins
unify docs a little more
This commit is contained in:
Stefan Kost 2006-02-02 11:24:19 +00:00
parent cefc46ad7e
commit 523041b533
9 changed files with 164 additions and 198 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
ChangeLog
View file

@ -1,3 +1,16 @@
2006-02-02 Stefan Kost <ensonic@users.sf.net>
* docs/README:
* docs/manual/intro-basics.xml:
* docs/manual/intro-preface.xml:
* docs/manual/manual.xml:
* docs/pwg/advanced-dparams.xml:
* docs/pwg/intro-basics.xml:
* docs/pwg/intro-preface.xml:
* docs/pwg/pwg.xml:
describe dparams (controller) for plugins
unify docs a little more
2006-02-02 Tim-Philipp Müller <tim at centricular dot net>
* docs/gst/gstreamer-sections.txt:

11
docs/README
View file

@ -40,6 +40,9 @@ We stick to some simple conventions for writing docbook documentation.
- sections should also include the chapter name;
for example in a chapter called chapter-example, a section would be
called section-example-hello-world
* there are currently comments of the form <!-- synchronize with PWG -->
in the docbook file. Please check the relevant section of the other manual
when updating.
HOW IMAGES ARE HANDLED
----------------------
@ -86,11 +89,9 @@ HOW THE BUILD SYSTEM IS SET UP
* html is built in a subdir, with the png/ps images copied there
* ps and pdf are built in the current dir, in one file
DOCBOOK NOTES
=============
* spell checking with aspell
SPELL CHECKING
--------------
* with aspell
* aspell -b -c --mode=sgml --lang=en <file>.xml
unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags

5
docs/manual/intro-basics.xml
View file

@ -1,6 +1,6 @@
<chapter id="chapter-intro-basics">
<title>Foundations</title>
<para>
<para><!-- synchronize with PWG -->
This chapter of the guide introduces the basic concepts of &GStreamer;.
Understanding these concepts will be important in reading any of the
rest of this guide, all of them assume understanding of these basic
@ -20,8 +20,7 @@
for example media playback or capture. &GStreamer; ships with a large
collection of elements by default, making the development of a large
variety of media applications possible. If needed, you can also write
new elements. That topic is explained in great deal in the Plugin
Writer's Guide.
new elements. That topic is explained in great deal in the &GstPWG;.
</para>
</sect1>

67
docs/manual/intro-preface.xml
View file

@ -1,11 +1,13 @@
<chapter id="chapter-intro">
<title>Introduction</title>
<title>Preface</title>
<para>
This chapter gives you an overview of the technologies described in this
book.
</para>
<sect1 id="section-intro-what">
<!-- ############ sect1 ############# -->
<sect1 id="section-intro-what"><!-- synchronize with PWG -->
<title>What is &GStreamer;?</title>
<para>
&GStreamer; is a framework for creating streaming media applications.
@ -51,8 +53,10 @@
</para>
</sect1>
<sect1 id="section-intro-structure">
<title>Structure of this Manual</title>
<!-- ############ sect1 ############# -->
<sect1 id="section-intro-who" xreflabel="Who Should Read This Manual?">
<title>Who Should Read This Manual?</title>
<para>
This book is about &GStreamer; from a developer's point of view; it
describes how to write a &GStreamer; application using the &GStreamer;
@ -60,15 +64,49 @@
suggest the <ulink type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
Writers Guide</ulink>.
</para>
</para>
</sect1>
<!-- ############ sect1 ############# -->
<sect1 id="section-intro-reading" xreflabel="Preliminary Reading">
<title>Preliminary Reading</title>
<para><!-- synchronize with PWG -->
In order to understand this manual, you will need to have a basic
understanding of the C language.
Since &GStreamer; adheres to the GObject programming model, this guide
also assumes that you understand the basics of <ulink type="http"
url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
programming.
You may also want to have a look
at Eric Harlow's book <emphasis>Developing Linux Applications with
GTK+ and GDK</emphasis>.
</para>
<para>
In addition you might want to read the &GstPWG; after this manual.
Also check out the other documentation available on the <ulink type="http"
url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>.
</para>
</sect1>
<!-- ############ sect1 ############# -->
<sect1 id="section-intro-structure">
<title>Structure of this Manual</title>
<para>
To help you navigate through this guide, it is divided into several large
parts. Each part addresses a particular broad topic concerning &GStreamer;
appliction development. The parts of this guide are laid out in the following
order:
</para>
<para>
<xref linkend="part-overview"/> gives you an overview of &GStreamer;'s
<xref linkend="part-introduction"/> gives you an overview of &GStreamer;'s
motivation design goals.
</para>
<para>
<xref linkend="part-basics"/> rapidly covers the basics of &GStreamer;
<xref linkend="part-building"/> rapidly covers the basics of &GStreamer;
application programming. At the end of that chapter, you should be
able to build your own audio player using &GStreamer;
</para>
@ -98,20 +136,5 @@
debugging help and general tips to improve and simplify &GStreamer;
programming.
</para>
<para>
In order to understand this manual, you will need to have a basic
understanding of the C language. Since &GStreamer; uses <ulink
url="http://developer.gnome.org/arch/gtk/glib.html" type="http">GLib
2.0</ulink>, the reader is assumed to understand the basics of the
<ulink url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
type="http">GObject object model</ulink>. It is recommended to have
skimmed through the introduction of the <ulink type="http"
url="http://www.le-hacker.org/papers/gobject/index.html">GObject
tutorial</ulink> before reading this. You may also want to have a look
at Eric Harlow's book <emphasis>Developing Linux Applications with
GTK+ and GDK</emphasis>.
</para>
</sect1>
</chapter>

11
docs/manual/manual.xml
View file

@ -57,6 +57,7 @@
<!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
<!ENTITY GStreamer "<application>GStreamer</application>">
<!ENTITY GstPWG "<emphasis>GStreamer Plugin Writer's Guide</emphasis>">
]>
<book id="index">
@ -64,10 +65,10 @@
<!-- ############# Introduction & Overview - part ############### -->
<part id="part-overview">
<title>Overview</title>
<part id="part-introduction">
<title>Introduction</title>
<partintro>
<para>
<para><!-- synchronize with PWG -->
&GStreamer; is an exremely powerful and versatile framework for
creating streaming media applications. Many of the virtues of the
&GStreamer; framework come from its modularity: &GStreamer; can
@ -96,8 +97,8 @@
<!-- ############ Basic concepts - part ############# -->
<part id="part-basics">
<title>Basic Concepts</title>
<part id="part-building">
<title>Building an Application</title>
<partintro>
<para>
In these chapters, we will discuss the basic concepts of &GStreamer;

181
docs/pwg/advanced-dparams.xml
View file

@ -58,166 +58,47 @@
<sect1 id="chapter-dparam-loop">
<title>The Data Processing Loop</title>
<!-- FIXME -->
<para>
This is the most critical aspect of the dparams subsystem as it relates to
elements. In a traditional audio processing loop, a <filename>for</filename>
loop will usually iterate over each sample in the buffer, processing one
sample at a time until the buffer is finished. A simplified loop with no
error checking might look something like this.
In the last section we learned how to mark GObject params as controllable.
Application developers can then queue parameter changes for these parameters.
The approach the controller subsystem takes is to make plugins responsible
for pulling the changes in. This requires just one action:
</para>
<programlisting>
static void
example_chain (GstPad *pad, GstBuffer *buf)
{
...
gfloat *float_data;
int j;
GstExample *example = GST_EXAMPLE(GST_OBJECT_PARENT (pad));
int num_samples = GST_BUFFER_SIZE(buf)/sizeof(gfloat);
float_data = (gfloat *)GST_BUFFER_DATA(buf);
...
for (j = 0; j &lt; num_samples; j++) {
float_data[j] *= example-&gt;volume;
}
...
}
gst_object_sync_values(element,timestamp);
</programlisting>
<para>
To make this dparams aware, a couple of changes are needed.
This call makes all parameter-changes for the given timestamp active by
adjusting the GObject properties of the element. Its up to the element to
determine the synchronisation rate.
</para>
<programlisting>
static void
example_chain (GstPad *pad, GstBuffer *buf)
{
...
int j = 0;
GstExample *example = GST_EXAMPLE(GST_OBJECT_PARENT (pad));
int num_samples = GST_BUFFER_SIZE(buf)/sizeof(gfloat);
gfloat *float_data = (gfloat *)GST_BUFFER_DATA(buf);
int frame_countdown = GST_DPMAN_PREPROCESS(example-&gt;dpman, num_samples, GST_BUFFER_TIMESTAMP(buf));
...
while (GST_DPMAN_PROCESS_COUNTDOWN(example-&gt;dpman, frame_countdown, j)) {
float_data[j++] *= example-&gt;volume;
}
...
}
</programlisting>
<para>
The biggest changes here are 2 new macros,
<filename>GST_DPMAN_PREPROCESS</filename> and
<filename>GST_DPMAN_PROCESS_COUNTDOWN</filename>. You will also notice that
the for loop has become a while loop.
<filename>GST_DPMAN_PROCESS_COUNTDOWN</filename> is called as the condition
for the while loop so that any required dparams can be updated in the middle
of a buffer if required. This is because one of the required behaviours of
dparams is that they can be <emphasis>sample accurate</emphasis>. This means
that parameters change at the exact timestamp that they are supposed to -
not after the buffer has finished being processed.
</para>
<para>
It may be alarming to see a macro as the condition for a while loop, but it
is actually very efficient. The macro expands to the following.
</para>
<programlisting>
#define GST_DPMAN_PROCESS_COUNTDOWN(dpman, frame_countdown, frame_count) \
(frame_countdown-- || \
(frame_countdown = GST_DPMAN_PROCESS(dpman, frame_count)))
</programlisting>
<para>
So as long as <filename>frame_countdown</filename> is greater than 0,
<filename>GST_DPMAN_PROCESS</filename> will not be called at all. Also in
many cases, <filename>GST_DPMAN_PROCESS</filename> will do nothing and
simply return 0, meaning that there is no more data in the buffer to
process.
</para>
<para>
The macro <filename>GST_DPMAN_PREPROCESS</filename> will do the following:
<itemizedlist>
<listitem>
<para>
Update any dparams which are due to be updated.
</para>
</listitem>
<listitem>
<para>
Calculate how many samples should be processed before the next required
update
</para>
</listitem>
<listitem>
<para>
Return the number of samples until next update, or the number of samples
in the buffer - whichever is less.
</para>
</listitem>
</itemizedlist>
In fact <filename>GST_DPMAN_PROCESS</filename> may do the same things as
<filename>GST_DPMAN_PREPROCESS</filename> depending on the mode that the
dparam manager is running in (see below).
</para>
<sect2 id="section-dparam-modes">
<title>DParam Manager Modes</title>
<sect2 id="chapter-dparam-loop-video">
<title>The Data Processing Loop for Video Elements</title>
<para>
A brief explanation of dparam manager modes might be useful here even
though it doesn't generally affect the way your element is written. There
are different ways media applications will be used which require that an
element's parameters be updated in differently. These include:
<itemizedlist>
<listitem>
<para>
<emphasis>Timelined</emphasis> - all parameter changes are known in
advance before the pipeline is run.
</para>
</listitem>
<listitem>
<para>
<emphasis>Realtime low-latency</emphasis> - Nothing is known ahead of
time about when a parameter might change. Changes need to be
propagated to the element as soon as possible.
</para>
</listitem>
</itemizedlist>
When a dparam-aware application gets the dparam manager for an element,
the first thing it will do is set the dparam manager mode. Current modes
are <filename>"synchronous"</filename> and
<filename>"asynchronous"</filename>.
</para>
<para>
If you are in a realtime low-latency situation then the
<filename>"synchronous"</filename> mode is appropriate. During
<filename>GST_DPMAN_PREPROCESS</filename> this mode will poll all dparams
for required updates and propagate them.
<filename>GST_DPMAN_PROCESS</filename> will do nothing in this mode. To
then achieve the desired latency, the size of the buffers needs to be
reduced so that the dparams will be polled for updates at the desired
frequency.
</para>
<para>
In a timelined situation, the <filename>"asynchronous"</filename> mode
will be required. This mode hasn't actually been implemented yet but will
be described anyway. The <filename>GST_DPMAN_PREPROCESS</filename> call
will precalculate when and how often each dparam needs to update for the
duration of the current buffer. From then on
<filename>GST_DPMAN_PROCESS</filename> will propagate the calculated
updates each time it is called until end of the buffer. If the application
is rendering to disk in non-realtime, the render could be sped up by
increasing the buffer size. In the <filename>"asynchronous"</filename>
mode this could be done without affecting the sample accuracy of the
parameter updates
For video processing elements it is the best to synchonise for every frame.
That means one would add the <function>gst_object_sync_values()</function>
call described in the previous section to the data processing function of
the element.
</para>
</sect2>
<sect2 id="section-dparam-audio-video">
<title>Dynamic Parameters for Video</title>
<sect2 id="chapter-dparam-loop-audio">
<title>The Data Processing Loop for Audio Elements</title>
<para>
All of the explanation so far has presumed that the buffer contains audio
data with many samples. Video should be regarded differently since a video
buffer often contains only 1 frame. In this case some of the complexity of
dparams isn't required but the other benefits still make it useful for
video parameters. If a buffer only contains one frame of video, only a
single call to <filename>GST_DPMAN_PREPROCESS</filename> should be
required. For more than one frame per buffer, treat it the same as the
audio case.
For audio processing elements the case is not as easy as for video
processing elements. The problem here is that audio has a much higher rate.
For PAL video one will e.g. process 25 full frames per second, but for
standard audio it will be 44100 samples.
It is rarely useful to synchronise controllable parameters that often.
The easiest solution is also to have just one synchronisation call per
buffer processing. This makes the control-rate dependend on the buffer
size.
</para>
<para>
Elements that need a specific control-rate need to break their data
processing loop to synchronise every n-samples.
</para>
</sect2>
</sect1>

6
docs/pwg/intro-basics.xml
View file

@ -1,8 +1,8 @@
<!-- ############ chapter ############# -->
<chapter id="chapter-intro-basics" xreflabel="Basic Concepts">
<title>Basic Concepts</title>
<para>
<chapter id="chapter-intro-basics" xreflabel="Foundations">
<title>Foundations</title>
<para><!-- synchronize with AppDevMan -->
This chapter of the guide introduces the basic concepts of &GStreamer;.
Understanding these concepts will help you grok the issues involved in
extending &GStreamer;. Many of these concepts are explained in greater

66
docs/pwg/intro-preface.xml
View file

@ -4,6 +4,54 @@
<chapter id="chapter-intro-preface" xreflabel="Preface">
<title>Preface</title>
<!-- ############ sect1 ############# -->
<sect1 id="section-intro-what"><!-- synchronize with AppDevMan -->
<title>What is &GStreamer;?</title>
<para>
&GStreamer; is a framework for creating streaming media applications.
The fundamental design comes from the video pipeline at Oregon Graduate
Institute, as well as some ideas from DirectShow.
</para>
<para>
&GStreamer;'s development framework makes it possible to write any
type of streaming multimedia application. The &GStreamer; framework
is designed to make it easy to write applications that handle audio
or video or both. It isn't restricted to audio and video, and can
process any kind of data flow.
The pipeline design is made to have little overhead above what the
applied filters induce. This makes &GStreamer; a good framework for
designing even high-end audio applications which put high demands on
latency.
</para>
<para>
One of the the most obvious uses of &GStreamer; is using it to build
a media player. &GStreamer; already includes components for building a
media player that can support a very wide variety of formats, including
MP3, Ogg/Vorbis, MPEG-1/2, AVI, Quicktime, mod, and more. &GStreamer;,
however, is much more than just another media player. Its main advantages
are that the pluggable components can be mixed and matched into arbitrary
pipelines so that it's possible to write a full-fledged video or audio
editing application.
</para>
<para>
The framework is based on plugins that will provide the various codec
and other functionality. The plugins can be linked and arranged in
a pipeline. This pipeline defines the flow of the data. Pipelines can
also be edited with a GUI editor and saved as XML so that pipeline
libraries can be made with a minimum of effort.
</para>
<para>
The &GStreamer; core function is to provide a framework for plugins,
data flow and media type handling/negotiation. It also provides an
API to write applications using the various plugins.
</para>
</sect1>
<!-- ############ sect1 ############# -->
<sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?">
@ -57,20 +105,20 @@
<para>
This guide assumes that you are somewhat familiar with the basic workings
of &GStreamer;. For a gentle introduction to programming concepts in
&GStreamer;, you may wish to read the &GstAppDevMan; first. Also check out
the documentation available on the <ulink type="http"
&GStreamer;, you may wish to read the &GstAppDevMan; first.
Also check out the other documentation available on the <ulink type="http"
url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>.
</para>
<para>
<para><!-- synchronize with AppDevMan -->
In order to understand this manual, you will need to have a basic
understanding of the C language.
Since &GStreamer; adheres to the GObject programming model, this guide
also assumes that you understand the basics of <ulink type="http"
url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
programming. There are several good introductions to the GObject library,
including the <emphasis><ulink type="http"
url="http://www.gtk.org/tutorial/">GTK+ Tutorial</ulink></emphasis> and
the <emphasis><ulink type="http"
url="http://www.le-hacker.org/papers/gobject/index.html">Glib Object
system</ulink></emphasis>.
programming.
You may also want to have a look
at Eric Harlow's book <emphasis>Developing Linux Applications with
GTK+ and GDK</emphasis>.
</para>
</sect1>

2
docs/pwg/pwg.xml
View file

@ -59,7 +59,7 @@
<part id="part-introduction" xreflabel="Introduction">
<title>Introduction</title>
<partintro>
<para>
<para><!-- synchronize with AppDevMan -->
&GStreamer; is an exremely powerful and versatile framework for creating
streaming media applications. Many of the virtues of the &GStreamer;
framework come from its modularity: &GStreamer; can seamlessly