mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-26 06:54:49 +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> 2006-02-02 Tim-Philipp Müller <tim at centricular dot net>
* docs/gst/gstreamer-sections.txt: * 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; - sections should also include the chapter name;
for example in a chapter called chapter-example, a section would be for example in a chapter called chapter-example, a section would be
called section-example-hello-world 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 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 * 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 * ps and pdf are built in the current dir, in one file
SPELL CHECKING
DOCBOOK NOTES --------------
============= * with aspell
* spell checking with aspell
* aspell -b -c --mode=sgml --lang=en <file>.xml * aspell -b -c --mode=sgml --lang=en <file>.xml
unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags 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"> <chapter id="chapter-intro-basics">
<title>Foundations</title> <title>Foundations</title>
<para> <para><!-- synchronize with PWG -->
This chapter of the guide introduces the basic concepts of &GStreamer;. This chapter of the guide introduces the basic concepts of &GStreamer;.
Understanding these concepts will be important in reading any of the Understanding these concepts will be important in reading any of the
rest of this guide, all of them assume understanding of these basic 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 for example media playback or capture. &GStreamer; ships with a large
collection of elements by default, making the development of a large collection of elements by default, making the development of a large
variety of media applications possible. If needed, you can also write variety of media applications possible. If needed, you can also write
new elements. That topic is explained in great deal in the Plugin new elements. That topic is explained in great deal in the &GstPWG;.
Writer's Guide.
</para> </para>
</sect1> </sect1>

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

@ -1,11 +1,13 @@
<chapter id="chapter-intro"> <chapter id="chapter-intro">
<title>Introduction</title> <title>Preface</title>
<para> <para>
This chapter gives you an overview of the technologies described in this This chapter gives you an overview of the technologies described in this
book. book.
</para> </para>
<sect1 id="section-intro-what"> <!-- ############ sect1 ############# -->
<sect1 id="section-intro-what"><!-- synchronize with PWG -->
<title>What is &GStreamer;?</title> <title>What is &GStreamer;?</title>
<para> <para>
&GStreamer; is a framework for creating streaming media applications. &GStreamer; is a framework for creating streaming media applications.
@ -51,8 +53,10 @@
</para> </para>
</sect1> </sect1>
<sect1 id="section-intro-structure"> <!-- ############ sect1 ############# -->
<title>Structure of this Manual</title>
<sect1 id="section-intro-who" xreflabel="Who Should Read This Manual?">
<title>Who Should Read This Manual?</title>
<para> <para>
This book is about &GStreamer; from a developer's point of view; it This book is about &GStreamer; from a developer's point of view; it
describes how to write a &GStreamer; application using the &GStreamer; describes how to write a &GStreamer; application using the &GStreamer;
@ -60,15 +64,49 @@
suggest the <ulink type="http" suggest the <ulink type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
Writers Guide</ulink>. 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> <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. motivation design goals.
</para> </para>
<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 application programming. At the end of that chapter, you should be
able to build your own audio player using &GStreamer; able to build your own audio player using &GStreamer;
</para> </para>
@ -98,20 +136,5 @@
debugging help and general tips to improve and simplify &GStreamer; debugging help and general tips to improve and simplify &GStreamer;
programming. programming.
</para> </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> </sect1>
</chapter> </chapter>

11
docs/manual/manual.xml
View file

@ -57,6 +57,7 @@
<!ENTITY QUOTES SYSTEM "appendix-quotes.xml"> <!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
<!ENTITY GStreamer "<application>GStreamer</application>"> <!ENTITY GStreamer "<application>GStreamer</application>">
<!ENTITY GstPWG "<emphasis>GStreamer Plugin Writer's Guide</emphasis>">
]> ]>
<book id="index"> <book id="index">
@ -64,10 +65,10 @@
<!-- ############# Introduction & Overview - part ############### --> <!-- ############# Introduction & Overview - part ############### -->
<part id="part-overview"> <part id="part-introduction">
<title>Overview</title> <title>Introduction</title>
<partintro> <partintro>
<para> <para><!-- synchronize with PWG -->
&GStreamer; is an exremely powerful and versatile framework for &GStreamer; is an exremely powerful and versatile framework for
creating streaming media applications. Many of the virtues of the creating streaming media applications. Many of the virtues of the
&GStreamer; framework come from its modularity: &GStreamer; can &GStreamer; framework come from its modularity: &GStreamer; can
@ -96,8 +97,8 @@
<!-- ############ Basic concepts - part ############# --> <!-- ############ Basic concepts - part ############# -->
<part id="part-basics"> <part id="part-building">
<title>Basic Concepts</title> <title>Building an Application</title>
<partintro> <partintro>
<para> <para>
In these chapters, we will discuss the basic concepts of &GStreamer; 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"> <sect1 id="chapter-dparam-loop">
<title>The Data Processing Loop</title> <title>The Data Processing Loop</title>
<!-- FIXME -->
<para> <para>
This is the most critical aspect of the dparams subsystem as it relates to In the last section we learned how to mark GObject params as controllable.
elements. In a traditional audio processing loop, a <filename>for</filename> Application developers can then queue parameter changes for these parameters.
loop will usually iterate over each sample in the buffer, processing one The approach the controller subsystem takes is to make plugins responsible
sample at a time until the buffer is finished. A simplified loop with no for pulling the changes in. This requires just one action:
error checking might look something like this.
</para> </para>
<programlisting> <programlisting>
static void gst_object_sync_values(element,timestamp);
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;
}
...
}
</programlisting> </programlisting>
<para> <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> </para>
<programlisting>
static void <sect2 id="chapter-dparam-loop-video">
example_chain (GstPad *pad, GstBuffer *buf) <title>The Data Processing Loop for Video Elements</title>
{
...
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>
<para> <para>
A brief explanation of dparam manager modes might be useful here even For video processing elements it is the best to synchonise for every frame.
though it doesn't generally affect the way your element is written. There That means one would add the <function>gst_object_sync_values()</function>
are different ways media applications will be used which require that an call described in the previous section to the data processing function of
element's parameters be updated in differently. These include: the element.
<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
</para> </para>
</sect2> </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> <para>
All of the explanation so far has presumed that the buffer contains audio For audio processing elements the case is not as easy as for video
data with many samples. Video should be regarded differently since a video processing elements. The problem here is that audio has a much higher rate.
buffer often contains only 1 frame. In this case some of the complexity of For PAL video one will e.g. process 25 full frames per second, but for
dparams isn't required but the other benefits still make it useful for standard audio it will be 44100 samples.
video parameters. If a buffer only contains one frame of video, only a It is rarely useful to synchronise controllable parameters that often.
single call to <filename>GST_DPMAN_PREPROCESS</filename> should be The easiest solution is also to have just one synchronisation call per
required. For more than one frame per buffer, treat it the same as the buffer processing. This makes the control-rate dependend on the buffer
audio case. size.
</para>
<para>
Elements that need a specific control-rate need to break their data
processing loop to synchronise every n-samples.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>

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

@ -1,8 +1,8 @@
<!-- ############ chapter ############# --> <!-- ############ chapter ############# -->
<chapter id="chapter-intro-basics" xreflabel="Basic Concepts"> <chapter id="chapter-intro-basics" xreflabel="Foundations">
<title>Basic Concepts</title> <title>Foundations</title>
<para> <para><!-- synchronize with AppDevMan -->
This chapter of the guide introduces the basic concepts of &GStreamer;. This chapter of the guide introduces the basic concepts of &GStreamer;.
Understanding these concepts will help you grok the issues involved in Understanding these concepts will help you grok the issues involved in
extending &GStreamer;. Many of these concepts are explained in greater 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"> <chapter id="chapter-intro-preface" xreflabel="Preface">
<title>Preface</title> <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 ############# -->
<sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?"> <sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?">
@ -57,20 +105,20 @@
<para> <para>
This guide assumes that you are somewhat familiar with the basic workings This guide assumes that you are somewhat familiar with the basic workings
of &GStreamer;. For a gentle introduction to programming concepts in of &GStreamer;. For a gentle introduction to programming concepts in
&GStreamer;, you may wish to read the &GstAppDevMan; first. Also check out &GStreamer;, you may wish to read the &GstAppDevMan; first.
the documentation available on the <ulink type="http" Also check out the other documentation available on the <ulink type="http"
url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>. url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>.
</para> </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 Since &GStreamer; adheres to the GObject programming model, this guide
also assumes that you understand the basics of <ulink type="http" 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> url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
programming. There are several good introductions to the GObject library, programming.
including the <emphasis><ulink type="http" You may also want to have a look
url="http://www.gtk.org/tutorial/">GTK+ Tutorial</ulink></emphasis> and at Eric Harlow's book <emphasis>Developing Linux Applications with
the <emphasis><ulink type="http" GTK+ and GDK</emphasis>.
url="http://www.le-hacker.org/papers/gobject/index.html">Glib Object
system</ulink></emphasis>.
</para> </para>
</sect1> </sect1>

2
docs/pwg/pwg.xml
View file

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