+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:
- 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
----------------------
* 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
<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
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>
<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.
</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;
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>
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>
<!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
<!ENTITY GStreamer "<application>GStreamer</application>">
+<!ENTITY GstPWG "<emphasis>GStreamer Plugin Writer's Guide</emphasis>">
]>
<book id="index">
<!-- ############# 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
<!-- ############ 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;
<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.
- </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 < num_samples; j++) {
- float_data[j] *= example->volume;
- }
- ...
-}
- </programlisting>
- <para>
- To make this dparams aware, a couple of changes are needed.
- </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->dpman, num_samples, GST_BUFFER_TIMESTAMP(buf));
- ...
- while (GST_DPMAN_PROCESS_COUNTDOWN(example->dpman, frame_countdown, j)) {
- float_data[j++] *= example->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.
+ 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>
-#define GST_DPMAN_PROCESS_COUNTDOWN(dpman, frame_countdown, frame_count) \
- (frame_countdown-- || \
- (frame_countdown = GST_DPMAN_PROCESS(dpman, frame_count)))
+ gst_object_sync_values(element,timestamp);
</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).
+ 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>
- <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.
+ 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="chapter-dparam-loop-audio">
+ <title>The Data Processing Loop for Audio Elements</title>
<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 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>
- </sect2>
- <sect2 id="section-dparam-audio-video">
- <title>Dynamic Parameters for Video</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.
+ Elements that need a specific control-rate need to break their data
+ processing loop to synchronise every n-samples.
</para>
</sect2>
</sect1>
<!-- ############ 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
<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?">
<title>Who Should Read This Guide?</title>
<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>
<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
projects / platform / upstream / gstreamer.git / commitdiff