2004-01-28 Thomas Vander Stichele <thomas at apestaart dot org>
+ * docs/manual/autoplugging.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/init-api.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/xml.xml:
+ use chapter, part, section or misc as id starts for all bits
+
+2004-01-28 Thomas Vander Stichele <thomas at apestaart dot org>
+
* docs/gst/gstreamer-sections.txt:
Fix up TITLE of the sections
-<chapter id="cha-factories">
+<chapter id="chapter-factories">
<title>More on factories</title>
<para>
The small application we created in the previous chapter used the
We will first explain the concepts involved before we move on
to the reworked helloworld example using autoplugging.
</para>
- <sect1>
+ <sect1 id="section-factories-helloworld-problems">
<title>The problems with the helloworld example</title>
<para>
If we take a look at how the elements were created in the previous
</para>
</sect1>
- <sect1>
+ <sect1 id="section-factories-mime">
<title>More on MIME Types</title>
<para>
GStreamer uses MIME types to identify the different types of data
</para>
<para>
- <xref linkend="sec-mime-img"/> shows the MIME types associated with
+ <xref linkend="section-mime-img"/> shows the MIME types associated with
each pad from the "hello world" example.
</para>
- <figure float="1" id="sec-mime-img">
+ <figure float="1" id="section-mime-img">
<title>The Hello world pipeline with MIME types</title>
<mediaobject>
<imageobject>
</sect1>
- <sect1>
+ <sect1 id="section-factories-gstreamer-types">
<title>GStreamer types</title>
<para>
GStreamer assigns a unique number to all registered MIME types.
This function will return 0 if the extension was not known.
</para>
<para>
- For more information, see <xref linkend="cha-autoplug"/>.
+ For more information, see <xref linkend="chapter-autoplug"/>.
</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="section-factories-create">
<title>Creating elements with the factory</title>
<para>
In the previous section we described how you could obtain
</para>
</sect1>
- <sect1>
+ <sect1 id="section-factories-basic-types">
<title>GStreamer basic types</title>
<para>
GStreamer only has two builtin types:
+++ /dev/null
-<chapter id="cha-clocks">
- <title>Clocks in GStreamer</title>
- <para>
- </para>
-</chapter>
-<chapter id="cha-dparams">
+<chapter id="chapter-dparams">
<title>Dynamic Parameters</title>
- <sect1>
+ <sect1 id="section-dparams-getting-started">
<title>Getting Started</title>
<para>
The Dynamic Parameters subsystem is contained within the
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-dparams-creating">
<title>Creating and Attaching Dynamic Parameters</title>
<para>
Once you have created your elements you can create and attach dparams to them.
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-dparams-changing">
<title>Changing Dynamic Parameter Values</title>
<para>
All interaction with dparams to actually set the dparam value is done through simple GObject properties.
</sect1>
- <sect1>
+ <sect1 id="section-dparams-types">
<title>Different Types of Dynamic Parameter</title>
<para>
There are currently only two implementations of dparams so far. They are both for real-time use so
-<chapter id="cha-scheduler">
+<chapter id="chapter-scheduler">
<title>Understanding schedulers</title>
<para>
The scheduler is responsible for managing the plugins at runtime. Its
-<chapter id="cha-threads">
+<chapter id="chapter-threads">
<title>Threads</title>
<para>
GStreamer has support for multithreading through the use of
itself. You never need to explicitly iterate a thread.
</para>
- <sect1>
+ <sect1 id="section-threads-constraints">
<title>Constraints placed on the pipeline by the GstThread</title>
<para>
Within the pipeline, everything is the same as in any other bin. The
fundamentally buffer-oriented rather than byte-oriented, the natural
solution to this problem is an element that can "buffer" the buffers
between the threads, in a thread-safe fashion. This element is the
- queue, described more fully in <xref linkend="cha-queues"/>. It doesn't
+ queue, described more fully in <xref linkend="chapter-queues"/>. It doesn't
matter if the queue is placed in the containing bin or in the thread
itself, but it needs to be present on one side or the other to enable
inter-thread communication.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-threads-when">
<title>When would you want to use a thread?</title>
<para>
If you are writing a GUI application, making the top-level bin a thread will make your GUI
an audio pipeline.
</para>
<para>
- <xref linkend="sec-threads-img"/> shows how a thread can be visualised.
+ <xref linkend="section-threads-img"/> shows how a thread can be visualised.
</para>
- <figure float="1" id="sec-threads-img">
+ <figure float="1" id="section-threads-img">
<title>A thread</title>
<mediaobject>
<imageobject>
-<chapter id="cha-debugging">
+<chapter id="chapter-debugging">
<title>Debugging</title>
<para>
GStreamer has an extensive set of debugging tools for
plugin developers.
</para>
- <sect1>
+ <sect1 id="section-debugging-command-line">
<title>Command line options</title>
<para>
Applications using the GStreamer libraries accept the following set
0x02000000 / REFCOUNTING
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-debugging-adding-handler">
<title>Adding a custom debug handler</title>
<para>
</para>
-<chapter id="cha-debugging">
+<chapter id="chapter-debugging">
<title>Debugging</title>
<para>
GStreamer has an extensive set of debugging tools for
plugin developers.
</para>
- <sect1>
+ <sect1 id="section-debugging-command-line">
<title>Command line options</title>
<para>
Applications using the GStreamer libraries accept the following set
0x02000000 / REFCOUNTING
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-debugging-adding-handler">
<title>Adding a custom debug handler</title>
<para>
</para>
-<chapter id="cha-gnome">
+<chapter id="chapter-gnome">
<title>GNOME integration</title>
<para>
GStreamer is fairly easy to integrate with GNOME applications.
-<chapter id="cha-gnome">
+<chapter id="chapter-gnome">
<title>GNOME integration</title>
<para>
GStreamer is fairly easy to integrate with GNOME applications.
-<chapter id="cha-programs">
+<chapter id="chapter-programs">
<title>Programs</title>
<para>
</para>
- <sect1>
+ <sect1 id="section-programs-gst-register">
<title><command>gst-register</command></title>
<para>
<command>gst-register</command> is used to rebuild the database of plugins.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-programs-gst-launch">
<title><command>gst-launch</command></title>
<para>
This is a tool that will construct pipelines based on a command-line
</sect2>
</sect1>
- <sect1>
+ <sect1 id="section-programs-gst-inspect">
<title><command>gst-inspect</command></title>
<para>
This is a tool to query a plugin or an element about its properties.
-<chapter id="cha-quotes">
+<chapter id="chapter-quotes">
<title>Quotes from the Developers</title>
<para>
As well as being a cool piece of software,
-<chapter id="cha-autoplug">
+<chapter id="chapter-autoplug">
<title>Autoplugging</title>
<para>
<application>GStreamer</application> provides an API to automatically
</programlisting>
</para>
</sect1>
- <sect1>
+ <sect1 id="section-autoplug-cache">
<title>Using the <classname>GstAutoplugCache</classname> element</title>
<para>
The <classname>GstAutoplugCache</classname> element is used to cache the
media stream when performing typedetection. As we have seen in
- <xref linkend="cha-typedetection"/>, the typefind function consumes a
+ <xref linkend="chapter-typedetection"/>, the typefind function consumes a
buffer to determine its media type. After we have set up the pipeline
to play the media stream we should be able to 'replay' the previous buffer(s).
This is what the autoplugcache is used for.
autoplugger, the autoplugcache and the typefind element.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-autoplugging-spider">
<title>Another approach to autoplugging</title>
<para>
The autoplug API is interesting, but often impractical. It is static;
+++ /dev/null
-<chapter id="cha-bins">
- <title>Bins</title>
- <para>
- A bin is a container element. You can add elements to a bin. Since a bin is
- an element itself, it can also be added to another bin.
- </para>
- <para>
- Bins allow you to combine a group of linked elements into one logical element. You do
- not deal with the individual elements anymore but with just one element, the bin.
- We will see that this is extremely powerful when you are going to construct
- complex pipelines since it allows you to break up the pipeline in smaller chunks.
- </para>
- <para>
- The bin will also manage the elements contained in it. It will figure out how
- the data will flow in the bin and generate an optimal plan for that data flow. Plan
- generation is one of the most complicated procedures in GStreamer.
- </para>
-
- <figure float="1" id="sec-bin-img">
- <title>Visualisation of a bin with some elements in it</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/bin-element.ℑ" format="&IMAGE;" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- There are two specialized bins available to the GStreamer programmer:
-
- <itemizedlist>
- <listitem>
- <para>
- a pipeline: a generic container that allows scheduling of the
- containing elements. The toplevel bin has to be a pipeline.
- Every application thus needs at least one of these.
- </para>
- </listitem>
- <listitem>
- <para>
- a thread: a bin that will be run in a separate execution thread.
- You will have to use this bin if you have to carefully
- synchronize audio and video, or for buffering. You will learn
- more about threads in <xref linkend="cha-threads"/>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-</chapter>
-<chapter id="cha-buffers">
+<chapter id="chapter-buffers">
<title>Buffers</title>
<para>
Buffers contain the data that will flow through the pipeline you have
-<chapter id="cha-elements">
+<chapter id="chapter-elements">
<title>Elements</title>
<para>
The most important object in <application>GStreamer</application> for the
application programmer is the <classname>GstElement</classname> object.
</para>
- <sect1 id="sec-elements-design">
+ <sect1 id="section-elements-design">
<title>What is an element ?</title>
<para>
An element is the basic building block for the media pipeline.
<para>
Elements, from the perspective of GStreamer, are viewed as "black boxes"
with a number of different aspects. One of these aspects is the presence
- of "pads" (see <xref linkend="cha-pads"/>), or link points. This terminology arises from soldering;
+ of "pads" (see <xref linkend="chapter-pads"/>), or link points. This terminology arises from soldering;
pads are where wires can be attached.
</para>
</sect1>
- <sect1 id="sec-elements-types">
+ <sect1 id="section-elements-types">
<title>Types of elements</title>
- <sect2 id="sec-elements-src">
+ <sect2 id="section-elements-src">
<title>Source elements</title>
<para>
Source elements generate data for use by a pipeline, for example
reading from disk or from a sound card.
</para>
<para>
- <xref linkend="sec-element-srcimg"/> shows how we will visualise
+ <xref linkend="section-element-srcimg"/> shows how we will visualise
a source element.
We always draw a source pad to the right of the element.
</para>
- <figure float="1" id="sec-element-srcimg">
+ <figure float="1" id="section-element-srcimg">
<title>Visualisation of a source element</title>
<mediaobject>
<imageobject>
</para>
</sect2>
- <sect2 id="sec-elements-filter">
+ <sect2 id="section-elements-filter">
<title>Filters and codecs</title>
<para>
Filter elements have both input and output pads. They operate on
for example, a video mixer might have two input pads (the images of
the two different video streams) and one output pad.
</para>
- <figure float="1" id="sec-element-filterimg">
+ <figure float="1" id="section-element-filterimg">
<title>Visualisation of a filter element</title>
<mediaobject>
<imageobject>
</mediaobject>
</figure>
<para>
- <xref linkend="sec-element-filterimg"/> shows how we will visualise
+ <xref linkend="section-element-filterimg"/> shows how we will visualise
a filter element.
This element has one sink (input) pad and one source (output) pad.
Sink pads are drawn on the left of the element.
</para>
- <figure float="1" id="sec-element-multifilterimg">
+ <figure float="1" id="section-element-multifilterimg">
<title>Visualisation of a filter element with
more than one output pad</title>
<mediaobject>
</mediaobject>
</figure>
<para>
- <xref linkend="sec-element-filterimg"/> shows the visualisation of a filter element with
+ <xref linkend="section-element-filterimg"/> shows the visualisation of a filter element with
more than one output pad. An example of such a filter is the AVI
demultiplexer. This element will parse the input data and
extract the audio and video data. Most of these filters dynamically
</para>
</sect2>
- <sect2 id="sec-elements-sink">
+ <sect2 id="section-elements-sink">
<title>Sink elements</title>
<para>
Sink elements are end points in a media pipeline. They accept
data but do not produce anything. Disk writing, soundcard playback,
and video output would all be implemented by sink elements.
- <xref linkend="sec-element-sinkimg"/> shows a sink element.
+ <xref linkend="section-element-sinkimg"/> shows a sink element.
</para>
- <figure float="1" id="sec-element-sinkimg">
+ <figure float="1" id="section-element-sinkimg">
<title>Visualisation of a sink element</title>
<mediaobject>
<imageobject>
-<chapter id="cha-hello">
+<chapter id="chapter-hello-world">
<title>Your first application</title>
<para>
This chapter describes the most rudimentary aspects of a
pausing and stopping the pipeline.
</para>
- <sect1>
+ <sect1 id="section-hello-world">
<title>Hello world</title>
<para>
We will create a simple first application, a complete MP3 player, using
We now have a created a complete pipeline. We can visualise the
pipeline as follows:
</para>
- <figure float="1" id="sec-hello-img">
+ <figure float="1" id="section-hello-img">
<title>The "hello world" pipeline</title>
<mediaobject>
<imageobject>
</sect1>
- <sect1>
+ <sect1 id="section-hello-world-compile">
<title>Compiling helloworld.c</title>
<para>
To compile the helloworld example, use:
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-hello-world-conclusion">
<title>Conclusion</title>
<para>
This concludes our first example. As you see, setting up a pipeline
-<chapter id="cha-initialisation">
+<chapter id="chapter-initialisation">
<title>Initializing <application>GStreamer</application></title>
<para>
When writing a <application>GStreamer</application> application, you can
-<chapter id="cha-pads">
+<chapter id="chapter-pads">
<title>Pads</title>
<para>
- As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
+ As we have seen in <xref linkend="chapter-elements"/>, the pads are the element's
interface to the outside world.
</para>
<para>
The specific type of media that the element can handle will be exposed by the pads.
The description of this media type is done with capabilities(see
- <xref linkend="sec-caps"/>)
+ <xref linkend="section-caps"/>)
</para>
<para>
</para></footnote>
</para>
- <sect1 id="sec-pads-type">
+ <sect1 id="section-pads-type">
<title>Types of pads</title>
- <sect2 id="sec-pads-dynamic">
+ <sect2 id="section-pads-dynamic">
<title>Dynamic pads</title>
<para>
Some elements might not have all of their pads when the element is
pipelines later on in this manual.
</para>
</sect2>
- <sect2 id="sec-pads-request">
+ <sect2 id="section-pads-request">
<title>Request pads</title>
<para>
An element can also have request pads. These pads are not created
</sect1>
- <sect1 id="sec-caps">
+ <sect1 id="section-caps">
<title>Capabilities of a pad</title>
<para>
Since the pads play a very important role in how the element is viewed by the
Plugin Writer's Guide.
</para>
- <sect2 id="sec-pads-caps">
+ <sect2 id="section-pads-caps">
<title>Capabilities</title>
<para>
Capabilities are attached to a pad in order to describe
rate: Integer range: 11025 - 48000
</programlisting>
</sect2>
- <sect2 id="sec-pads-props">
+ <sect2 id="section-pads-props">
<title>What are properties ?</title>
<para>
Properties are used to describe extra information for
</itemizedlist>
</sect2>
- <sect2 id="sec-pads-caps-use">
+ <sect2 id="section-pads-caps-use">
<title>What capabilities are used for</title>
<para>
Capabilities describe in great detail the type of media that is handled by the pads.
+++ /dev/null
-<chapter id="cha-plugins">
- <title>Plugins</title>
- <!-- FIXME: introduce type definitions before this chapter -->
- <para>
- A plugin is a shared library that contains at least one of the following
- items:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- one or more element factories
- </para>
- </listitem>
- <listitem>
- <para>
- one or more type definitions
- </para>
- </listitem>
- <listitem>
- <para>
- one or more auto-pluggers
- </para>
- </listitem>
- <listitem>
- <para>
- exported symbols for use in other plugins
- </para>
- </listitem>
- </itemizedlist>
-</chapter>
-<chapter id="cha-bins-api">
+<chapter id="chapter-bins-api">
<title>Bins</title>
- <sect1 id="sec-bin-create">
+ <sect1 id="section-bin-create">
<title>Creating a bin</title>
<para>
Bins are created in the same way that other elements are created. ie.
</programlisting>
</sect1>
- <sect1 id="sec-bin-adding">
+ <sect1 id="section-bin-adding">
<title>Adding elements to a bin</title>
<para>
Elements are added to a bin with the following code sample:
</programlisting>
</sect1>
- <sect1 id="sec-bin-custom">
+ <sect1 id="section-bin-custom">
<title>Custom bins</title>
<para>
The application programmer can create custom bins packed with elements
Note that the above code assumes that the mp3player bin derives itself
from a <classname>GstThread</classname>, which begins to play as soon
as its state is set to PLAYING. Other bin types may need explicit
- iteration. For more information, see <xref linkend="cha-threads"/>.
+ iteration. For more information, see <xref linkend="chapter-threads"/>.
</para>
<para>
Custom bins can be created with a plugin or an XML description. You
</para>
</sect1>
- <sect1 id="sec-bin-ghostpads">
+ <sect1 id="section-bin-ghostpads">
<title>Ghost pads</title>
<para>
- You can see from <xref linkend="sec-bin-noghost-img"/> how a bin has no pads of its own.
+ You can see from <xref linkend="section-bin-noghost-img"/> how a bin has no pads of its own.
This is where "ghost pads" come into play.
</para>
- <figure float="1" id="sec-bin-noghost-img">
+ <figure float="1" id="section-bin-noghost-img">
<title>Visualisation of a <classname>GstBin</classname> element without ghost pads</title>
<mediaobject>
<imageobject>
for creating custom bins.
</para>
- <figure float="1" id="sec-bin-ghost-img">
+ <figure float="1" id="section-bin-ghost-img">
<title>Visualisation of a <classname>GstBin</classname> element with a ghost pad</title>
<mediaobject>
<imageobject>
</mediaobject>
</figure>
<para>
- <xref linkend="sec-bin-ghost-img"/>
+ <xref linkend="section-bin-ghost-img"/>
is a representation of a ghost pad. The sink pad of element one is now also a pad
of the bin.
</para>
-<chapter id="cha-bins">
+<chapter id="chapter-bins">
<title>Bins</title>
<para>
A bin is a container element. You can add elements to a bin. Since a bin is
generation is one of the most complicated procedures in GStreamer.
</para>
- <figure float="1" id="sec-bin-img">
+ <figure float="1" id="section-bin-img">
<title>Visualisation of a bin with some elements in it</title>
<mediaobject>
<imageobject>
a thread: a bin that will be run in a separate execution thread.
You will have to use this bin if you have to carefully
synchronize audio and video, or for buffering. You will learn
- more about threads in <xref linkend="cha-threads"/>.
+ more about threads in <xref linkend="chapter-threads"/>.
</para>
</listitem>
</itemizedlist>
-<chapter id="cha-buffers-api">
+<chapter id="chapter-buffers-api">
<title>Buffers</title>
<para>
</para>
-<chapter id="cha-buffers">
+<chapter id="chapter-buffers">
<title>Buffers</title>
<para>
Buffers contain the data that will flow through the pipeline you have
-<chapter id="cha-clocks">
+<chapter id="chapter-clocks">
<title>Clocks in GStreamer</title>
<para>
</para>
-<chapter id="cha-components">
+<chapter id="chapter-components">
<title>Components</title>
<para>
in their programs.
</para>
- <sect1>
+ <sect1 id="section-components-gst-play">
<title>GstPlay</title>
<para>
GstPlay is a GtkWidget with a simple API to play, pause and stop a media file.
</sect1>
- <sect1>
+ <sect1 id="section-components-gst-media-play">
<title>GstMediaPlay</title>
<para>
- GstMediaply is a complete player widget.
+ GstMediaPlay is a complete player widget.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-components-gst-editor">
<title>GstEditor</title>
<para>
GstEditor is a set of widgets to display a graphical representation of a
-<chapter id="cha-cothreads">
+<chapter id="chapter-cothreads">
<title>Cothreads</title>
<para>
Cothreads are user-space threads that greatly reduce context switching overhead introduced by
explain the chain-based elements.
</para>
- <sect1 id="sec-chain-based">
+ <sect1 id="section-chain-based">
<title>Chain-based elements</title>
<para>
Chain based elements receive a buffer of data and are supposed
</sect1>
- <sect1 id="sec-loop-based">
+ <sect1 id="section-loop-based">
<title>Loop-based elements</title>
<para>
As opposed to chain-based elements, loop-based elements enter an
-<chapter id="cha-debugging">
+<chapter id="chapter-debugging">
<title>Debugging</title>
<para>
GStreamer has an extensive set of debugging tools for
plugin developers.
</para>
- <sect1>
+ <sect1 id="section-debugging-command-line">
<title>Command line options</title>
<para>
Applications using the GStreamer libraries accept the following set
0x02000000 / REFCOUNTING
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-debugging-adding-handler">
<title>Adding a custom debug handler</title>
<para>
</para>
-<chapter id="cha-dparams">
+<chapter id="chapter-dparams">
<title>Dynamic Parameters</title>
- <sect1>
+ <sect1 id="section-dparams-getting-started">
<title>Getting Started</title>
<para>
The Dynamic Parameters subsystem is contained within the
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-dparams-creating">
<title>Creating and Attaching Dynamic Parameters</title>
<para>
Once you have created your elements you can create and attach dparams to them.
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-dparams-changing">
<title>Changing Dynamic Parameter Values</title>
<para>
All interaction with dparams to actually set the dparam value is done through simple GObject properties.
</sect1>
- <sect1>
+ <sect1 id="section-dparams-types">
<title>Different Types of Dynamic Parameter</title>
<para>
There are currently only two implementations of dparams so far. They are both for real-time use so
-<chapter id="cha-dynamic">
+<chapter id="chapter-dynamic">
<title>Dynamic pipelines</title>
<para>
In this chapter we will see how you can create a dynamic pipeline. A
-<chapter id="cha-elements-api">
+<chapter id="chapter-elements-api">
<title>Elements</title>
- <sect1 id="sec-elements-create">
+ <sect1 id="section-elements-create">
<title>Creating a GstElement</title>
<para>
A <classname>GstElement</classname> object is created from
gst_element_unref (element);
</programlisting>
</sect1>
- <sect1 id="sec-elements-properties">
+ <sect1 id="section-elements-properties">
<title>GstElement properties</title>
<para>
A <classname>GstElement</classname> can have several properties
</para>
</sect1>
- <sect1 id="sec-elements-signals">
+ <sect1 id="section-elements-signals">
<title>GstElement signals</title>
<para>
A <classname>GstElement</classname> also provides various
</para>
</sect1>
- <sect1 id="sec-elements-factories">
+ <sect1 id="section-elements-factories">
<title>More about GstElementFactory</title>
<para>
We talk some more about the GstElementFactory object.
</para>
- <sect2 id="sec-elements-factories-details">
+ <sect2 id="section-elements-factories-details">
<title>Getting information about an element using the factory details</title>
<para>
</para>
</sect2>
- <sect2 id="sec-elements-factories-padtemplates">
+ <sect2 id="section-elements-factories-padtemplates">
<title>Finding out what pads an element can contain</title>
<para>
</para>
</sect2>
- <sect2 id="sec-elements-factories-query">
+ <sect2 id="section-elements-factories-query">
<title>Different ways of querying the factories</title>
<para>
</para>
-<chapter id="cha-elements">
+<chapter id="chapter-elements">
<title>Elements</title>
<para>
The most important object in <application>GStreamer</application> for the
application programmer is the <classname>GstElement</classname> object.
</para>
- <sect1 id="sec-elements-design">
+ <sect1 id="section-elements-design">
<title>What is an element ?</title>
<para>
An element is the basic building block for the media pipeline.
<para>
Elements, from the perspective of GStreamer, are viewed as "black boxes"
with a number of different aspects. One of these aspects is the presence
- of "pads" (see <xref linkend="cha-pads"/>), or link points. This terminology arises from soldering;
+ of "pads" (see <xref linkend="chapter-pads"/>), or link points. This terminology arises from soldering;
pads are where wires can be attached.
</para>
</sect1>
- <sect1 id="sec-elements-types">
+ <sect1 id="section-elements-types">
<title>Types of elements</title>
- <sect2 id="sec-elements-src">
+ <sect2 id="section-elements-src">
<title>Source elements</title>
<para>
Source elements generate data for use by a pipeline, for example
reading from disk or from a sound card.
</para>
<para>
- <xref linkend="sec-element-srcimg"/> shows how we will visualise
+ <xref linkend="section-element-srcimg"/> shows how we will visualise
a source element.
We always draw a source pad to the right of the element.
</para>
- <figure float="1" id="sec-element-srcimg">
+ <figure float="1" id="section-element-srcimg">
<title>Visualisation of a source element</title>
<mediaobject>
<imageobject>
</para>
</sect2>
- <sect2 id="sec-elements-filter">
+ <sect2 id="section-elements-filter">
<title>Filters and codecs</title>
<para>
Filter elements have both input and output pads. They operate on
for example, a video mixer might have two input pads (the images of
the two different video streams) and one output pad.
</para>
- <figure float="1" id="sec-element-filterimg">
+ <figure float="1" id="section-element-filterimg">
<title>Visualisation of a filter element</title>
<mediaobject>
<imageobject>
</mediaobject>
</figure>
<para>
- <xref linkend="sec-element-filterimg"/> shows how we will visualise
+ <xref linkend="section-element-filterimg"/> shows how we will visualise
a filter element.
This element has one sink (input) pad and one source (output) pad.
Sink pads are drawn on the left of the element.
</para>
- <figure float="1" id="sec-element-multifilterimg">
+ <figure float="1" id="section-element-multifilterimg">
<title>Visualisation of a filter element with
more than one output pad</title>
<mediaobject>
</mediaobject>
</figure>
<para>
- <xref linkend="sec-element-filterimg"/> shows the visualisation of a filter element with
+ <xref linkend="section-element-filterimg"/> shows the visualisation of a filter element with
more than one output pad. An example of such a filter is the AVI
demultiplexer. This element will parse the input data and
extract the audio and video data. Most of these filters dynamically
</para>
</sect2>
- <sect2 id="sec-elements-sink">
+ <sect2 id="section-elements-sink">
<title>Sink elements</title>
<para>
Sink elements are end points in a media pipeline. They accept
data but do not produce anything. Disk writing, soundcard playback,
and video output would all be implemented by sink elements.
- <xref linkend="sec-element-sinkimg"/> shows a sink element.
+ <xref linkend="section-element-sinkimg"/> shows a sink element.
</para>
- <figure float="1" id="sec-element-sinkimg">
+ <figure float="1" id="section-element-sinkimg">
<title>Visualisation of a sink element</title>
<mediaobject>
<imageobject>
-<chapter id="cha-factories">
+<chapter id="chapter-factories">
<title>More on factories</title>
<para>
The small application we created in the previous chapter used the
We will first explain the concepts involved before we move on
to the reworked helloworld example using autoplugging.
</para>
- <sect1>
+ <sect1 id="section-factories-helloworld-problems">
<title>The problems with the helloworld example</title>
<para>
If we take a look at how the elements were created in the previous
</para>
</sect1>
- <sect1>
+ <sect1 id="section-factories-mime">
<title>More on MIME Types</title>
<para>
GStreamer uses MIME types to identify the different types of data
</para>
<para>
- <xref linkend="sec-mime-img"/> shows the MIME types associated with
+ <xref linkend="section-mime-img"/> shows the MIME types associated with
each pad from the "hello world" example.
</para>
- <figure float="1" id="sec-mime-img">
+ <figure float="1" id="section-mime-img">
<title>The Hello world pipeline with MIME types</title>
<mediaobject>
<imageobject>
</sect1>
- <sect1>
+ <sect1 id="section-factories-gstreamer-types">
<title>GStreamer types</title>
<para>
GStreamer assigns a unique number to all registered MIME types.
This function will return 0 if the extension was not known.
</para>
<para>
- For more information, see <xref linkend="cha-autoplug"/>.
+ For more information, see <xref linkend="chapter-autoplug"/>.
</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="section-factories-create">
<title>Creating elements with the factory</title>
<para>
In the previous section we described how you could obtain
</para>
</sect1>
- <sect1>
+ <sect1 id="section-factories-basic-types">
<title>GStreamer basic types</title>
<para>
GStreamer only has two builtin types:
-<chapter id="cha-gnome">
+<chapter id="chapter-gnome">
<title>GNOME integration</title>
<para>
GStreamer is fairly easy to integrate with GNOME applications.
-<chapter id="cha-goals">
+<chapter id="chapter-goals">
<title>Goals</title>
<para>
GStreamer was designed to provide a solution to the current Linux media
problems.
</para>
- <sect1 id="sec-goals-design">
+ <sect1 id="section-goals-design">
<title>The design goals</title>
<para>
We describe what we try to achieve with GStreamer.
</para>
- <sect2 id="sec-goals-clean">
+ <sect2 id="section-goals-clean">
<title>Clean and powerful</title>
<para>
GStreamer wants to provide a clean interface to:
</itemizedlist>
</sect2>
- <sect2 id="sec-goals-object">
+ <sect2 id="section-goals-object">
<title>Object oriented</title>
<para>
GStreamer adheres to the GLib 2.0 object model. A programmer familiar with GLib 2.0 or older versions
</para>
</sect2>
- <sect2 id="sec-goals-extensible">
+ <sect2 id="section-goals-extensible">
<title>Extensible</title>
<para>
All GStreamer Objects can be extended using the GObject inheritance methods.
</para>
</sect2>
- <sect2 id="sec-goals-binary">
+ <sect2 id="section-goals-binary">
<title>Allow binary only plugins</title>
<para>
Plugins are shared libraries that are loaded at runtime. Since all the properties of the
</para>
</sect2>
- <sect2 id="sec-goals-performance">
+ <sect2 id="section-goals-performance">
<title>High performance</title>
<para>
High performance is obtained by:
</itemizedlist>
</sect2>
- <sect2 id="sec-goals-separation">
+ <sect2 id="section-goals-separation">
<title>Clean core/plugins separation</title>
<para>
The core of GStreamer is essentially media-agnostic. It only knows
</para>
</sect2>
- <sect2 id="sec-goals-testbed">
+ <sect2 id="section-goals-testbed">
<title>Provide a framework for codec experimentation</title>
<para>
GStreamer also wants to be an easy framework where codec
-<chapter id="cha-hello">
+<chapter id="chapter-hello-world">
<title>Your first application</title>
<para>
This chapter describes the most rudimentary aspects of a
pausing and stopping the pipeline.
</para>
- <sect1>
+ <sect1 id="section-hello-world">
<title>Hello world</title>
<para>
We will create a simple first application, a complete MP3 player, using
We now have a created a complete pipeline. We can visualise the
pipeline as follows:
</para>
- <figure float="1" id="sec-hello-img">
+ <figure float="1" id="section-hello-img">
<title>The "hello world" pipeline</title>
<mediaobject>
<imageobject>
</sect1>
- <sect1>
+ <sect1 id="section-hello-world-compile">
<title>Compiling helloworld.c</title>
<para>
To compile the helloworld example, use:
</programlisting>
</sect1>
- <sect1>
+ <sect1 id="section-hello-world-conclusion">
<title>Conclusion</title>
<para>
This concludes our first example. As you see, setting up a pipeline
-<chapter id="cha-hello2">
+<chapter id="chapter-hello2">
<title>Your second application</title>
<para>
FIXME: delete this section, talk more about the spider. In a previous chapter we created a first
+++ /dev/null
-<chapter id="cha-components">
- <title>Components</title>
-
- <para>
- FIXME: This chapter is way out of date.
- </para>
-
- <para>
- <application>GStreamer</application> includes components that people can include
- in their programs.
- </para>
-
- <sect1>
- <title>GstPlay</title>
- <para>
- GstPlay is a GtkWidget with a simple API to play, pause and stop a media file.
- </para>
-
- </sect1>
-
- <sect1>
- <title>GstMediaPlay</title>
- <para>
- GstMediaply is a complete player widget.
- </para>
-
- </sect1>
-
- <sect1>
- <title>GstEditor</title>
- <para>
- GstEditor is a set of widgets to display a graphical representation of a
- pipeline.
- </para>
- </sect1>
-
-</chapter>
+++ /dev/null
-<chapter id="cha-xml">
- <title>XML in <application>GStreamer</application></title>
- <para>
- <application>GStreamer</application> uses XML to store and load
- its pipeline definitions. XML is also used internally to manage the
- plugin registry. The plugin registry is a file that contains the definition
- of all the plugins <application>GStreamer</application> knows about to have
- quick access to the specifics of the plugins.
- </para>
-
- <para>
- We will show you how you can save a pipeline to XML and how you can reload that
- XML file again for later use.
- </para>
-
- <sect1 id="sec-xml-write">
- <title>Turning GstElements into XML</title>
-
- <para>
- We create a simple pipeline and write it to stdout with
- gst_xml_write_file (). The following code constructs an MP3 player
- pipeline with two threads and then writes out the XML both to stdout
- and to a file. Use this program with one argument: the MP3 file on disk.
- </para>
-
- <programlisting>
-/* example-begin xml-mp3.c */
-#include <stdlib.h>
-#include <gst/gst.h>
-
-gboolean playing;
-
-int
-main (int argc, char *argv[])
-{
- GstElement *filesrc, *osssink, *queue, *queue2, *decode;
- GstElement *bin;
- GstElement *thread, *thread2;
-
- gst_init (&argc,&argv);
-
- if (argc != 2) {
- g_print ("usage: %s <mp3 filename>\n", argv[0]);
- exit (-1);
- }
-
- /* create a new thread to hold the elements */
- thread = gst_element_factory_make ("thread", "thread");
- g_assert (thread != NULL);
- thread2 = gst_element_factory_make ("thread", "thread2");
- g_assert (thread2 != NULL);
-
- /* create a new bin to hold the elements */
- bin = gst_bin_new ("bin");
- g_assert (bin != NULL);
-
- /* create a disk reader */
- filesrc = gst_element_factory_make ("filesrc", "disk_source");
- g_assert (filesrc != NULL);
- g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
-
- queue = gst_element_factory_make ("queue", "queue");
- queue2 = gst_element_factory_make ("queue", "queue2");
-
- /* and an audio sink */
- osssink = gst_element_factory_make ("osssink", "play_audio");
- g_assert (osssink != NULL);
-
- decode = gst_element_factory_make ("mad", "decode");
- g_assert (decode != NULL);
-
- /* add objects to the main bin */
- gst_bin_add_many (GST_BIN (bin), filesrc, queue, NULL);
-
- gst_bin_add_many (GST_BIN (thread), decode, queue2, NULL);
-
- gst_bin_add (GST_BIN (thread2), osssink);
-
- gst_element_link_many (filesrc, queue, decode, queue2, osssink, NULL);
-
- gst_bin_add_many (GST_BIN (bin), thread, thread2, NULL);
-
- /* write the bin to stdout */
- gst_xml_write_file (GST_ELEMENT (bin), stdout);
-
- /* write the bin to a file */
- gst_xml_write_file (GST_ELEMENT (bin), fopen ("xmlTest.gst", "w"));
-
- exit (0);
-}
-/* example-end xml-mp3.c */
- </programlisting>
- <para>
- The most important line is:
- </para>
- <programlisting>
- gst_xml_write_file (GST_ELEMENT (bin), stdout);
- </programlisting>
- <para>
- gst_xml_write_file () will turn the given element into an xmlDocPtr that
- is then formatted and saved to a file. To save to disk, pass the result
- of a fopen(2) as the second argument.
- </para>
- <para>
- The complete element hierarchy will be saved along with the inter element
- pad links and the element parameters. Future <application>GStreamer</application>
- versions will also allow you to store the signals in the XML file.
- </para>
- </sect1>
-
- <sect1 id="sec-xml-load">
- <title>Loading a GstElement from an XML file</title>
- <para>
- Before an XML file can be loaded, you must create a GstXML object.
- A saved XML file can then be loaded with the
- gst_xml_parse_file (xml, filename, rootelement) method.
- The root element can optionally left NULL. The following code example loads
- the previously created XML file and runs it.
- </para>
- <programlisting>
-#include <stdlib.h>
-#include <gst/gst.h>
-
-int
-main(int argc, char *argv[])
-{
- GstXML *xml;
- GstElement *bin;
- gboolean ret;
-
- gst_init (&argc, &argv);
-
- xml = gst_xml_new ();
-
- ret = gst_xml_parse_file(xml, "xmlTest.gst", NULL);
- g_assert (ret == TRUE);
-
- bin = gst_xml_get_element (xml, "bin");
- g_assert (bin != NULL);
-
- gst_element_set_state (bin, GST_STATE_PLAYING);
-
- while (gst_bin_iterate(GST_BIN(bin)));
-
- gst_element_set_state (bin, GST_STATE_NULL);
-
- exit (0);
-}
- </programlisting>
- <para>
- gst_xml_get_element (xml, "name") can be used to get a specific element
- from the XML file.
- </para>
- <para>
- gst_xml_get_topelements (xml) can be used to get a list of all toplevel elements
- in the XML file.
- </para>
- <para>
- In addition to loading a file, you can also load a from a xmlDocPtr and
- an in memory buffer using gst_xml_parse_doc and gst_xml_parse_memory
- respectively. Both of these methods return a gboolean indicating
- success or failure of the requested action.
- </para>
- </sect1>
- <sect1 id="sec-xml-custom">
- <title>Adding custom XML tags into the core XML data</title>
-
- <para>
- It is possible to add custom XML tags to the core XML created with
- gst_xml_write. This feature can be used by an application to add more
- information to the save plugins. The editor will for example insert
- the position of the elements on the screen using the custom XML tags.
- </para>
- <para>
- It is strongly suggested to save and load the custom XML tags using
- a namespace. This will solve the problem of having your XML tags
- interfere with the core XML tags.
- </para>
- <para>
- To insert a hook into the element saving procedure you can link
- a signal to the GstElement using the following piece of code:
- </para>
- <programlisting>
-xmlNsPtr ns;
-
- ...
- ns = xmlNewNs (NULL, "http://gstreamer.net/gst-test/1.0/", "test");
- ...
- thread = gst_element_factory_make ("thread", "thread");
- g_signal_connect (G_OBJECT (thread), "object_saved",
- G_CALLBACK (object_saved), g_strdup ("decoder thread"));
- ...
- </programlisting>
- <para>
- When the thread is saved, the object_save method will be called. Our example
- will insert a comment tag:
- </para>
- <programlisting>
-static void
-object_saved (GstObject *object, xmlNodePtr parent, gpointer data)
-{
- xmlNodePtr child;
-
- child = xmlNewChild (parent, ns, "comment", NULL);
- xmlNewChild (child, ns, "text", (gchar *)data);
-}
- </programlisting>
- <para>
- Adding the custom tag code to the above example you will get an XML file
- with the custom tags in it. Here's an excerpt:
- </para>
- <programlisting>
- ...
- <gst:element>
- <gst:name>thread</gst:name>
- <gst:type>thread</gst:type>
- <gst:version>0.1.0</gst:version>
- ...
- </gst:children>
- <test:comment>
- <test:text>decoder thread</test:text>
- </test:comment>
- </gst:element>
- ...
- </programlisting>
- <para>
- To retrieve the custom XML again, you need to attach a signal to
- the GstXML object used to load the XML data. You can then parse your
- custom XML from the XML tree whenever an object is loaded.
- </para>
-
- <para>
- We can extend our previous example with the following piece of
- code.
- </para>
-
- <programlisting>
- xml = gst_xml_new ();
-
- g_signal_connect (G_OBJECT (xml), "object_loaded",
- G_CALLBACK (xml_loaded), xml);
-
- ret = gst_xml_parse_file (xml, "xmlTest.gst", NULL);
- g_assert (ret == TRUE);
- </programlisting>
-
- <para>
- Whenever a new object has been loaded, the xml_loaded function will
- be called. This function looks like:
- </para>
- <programlisting>
-static void
-xml_loaded (GstXML *xml, GstObject *object, xmlNodePtr self, gpointer data)
-{
- xmlNodePtr children = self->xmlChildrenNode;
-
- while (children) {
- if (!strcmp (children->name, "comment")) {
- xmlNodePtr nodes = children->xmlChildrenNode;
-
- while (nodes) {
- if (!strcmp (nodes->name, "text")) {
- gchar *name = g_strdup (xmlNodeGetContent (nodes));
- g_print ("object %s loaded with comment '%s'\n",
- gst_object_get_name (object), name);
- }
- nodes = nodes->next;
- }
- }
- children = children->next;
- }
-}
- </programlisting>
- <para>
- As you can see, you'll get a handle to the GstXML object, the
- newly loaded GstObject and the xmlNodePtr that was used to create
- this object. In the above example we look for our special tag inside
- the XML tree that was used to load the object and we print our
- comment to the console.
- </para>
- </sect1>
-
-</chapter>
-<chapter id="cha-initialisation">
+<chapter id="chapter-initialisation">
<title>Initializing <application>GStreamer</application></title>
<para>
When writing a <application>GStreamer</application> application, you can
-<chapter id="cha-motivation">
+<chapter id="chapter-motivation">
<title>Motivation</title>
<para>
Linux has historically lagged behind other operating systems in the multimedia
with the professional level of software available for MS Windows and MacOS.
</para>
- <sect1 id="sec-motivation-problems">
+ <sect1 id="section-motivation-problems">
<title>Current problems</title>
<para>
We describe the typical problems in today's media handling on Linux.
</para>
- <sect2 id="sec-motivation-duplicate">
+ <sect2 id="section-motivation-duplicate">
<title>Multitude of duplicate code</title>
<para>
The Linux user who wishes to hear a sound file must hunt through their collection of
</para>
</sect2>
- <sect2 id="sec-motivation-goal">
+ <sect2 id="section-motivation-goal">
<title>'One goal' media players/libraries</title>
<para>
Your typical MPEG player was designed to play MPEG video and audio. Most of
</para>
</sect2>
- <sect2 id="sec-motivation-plugin">
+ <sect2 id="section-motivation-plugin">
<title>Non unified plugin mechanisms</title>
<para>
Your typical media player might have a plugin for different media
</para>
</sect2>
- <sect2 id="sec-motivation-network">
+ <sect2 id="section-motivation-network">
<title>Provision for network transparency</title>
<para>
No infrastructure is present to allow network transparent media
</para>
</sect2>
- <sect2 id="sec-motivation-catchup">
+ <sect2 id="section-motivation-catchup">
<title>Catch up with the <trademark>Windows</trademark> world</title>
<para>
We need solid media handling if we want to see Linux succeed on
+++ /dev/null
-<chapter id="cha-intro">
- <title>Introduction</title>
- <para>
- This chapter gives you an overview of the technologies described in this
- book.
- </para>
-
- <sect1 id="sec-intro-what">
- <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, MPEG1, MPEG2, 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>
-
- <para>
- This book is about GStreamer from a developer's point of view; it describes
- how to write a GStreamer application using the GStreamer libraries and tools.
- For an explanation about writing plugins, we suggest the Plugin Writers Guide.
- </para>
-
- </sect1>
-</chapter>
-<chapter id="cha-intro">
+<chapter id="chapter-intro">
<title>Introduction</title>
<para>
This chapter gives you an overview of the technologies described in this
book.
</para>
- <sect1 id="sec-intro-what">
+ <sect1 id="section-intro-what">
<title>What is GStreamer?</title>
<para>
GStreamer is a framework for creating streaming media applications.
-<chapter id="cha-links-api">
+<chapter id="chapter-links-api">
<title>Linking elements</title>
- <sect1 id="sec-link-basic">
+ <sect1 id="section-link-basic">
<title>Making simple links</title>
<para>
You can link two pads with:
</para>
</sect1>
- <sect1 id="sec-link-filtered">
+ <sect1 id="section-link-filtered">
<title>Making filtered links</title>
<para>
You can also force a specific media type on the link by using gst_pad_link_filtered ()
and gst_element_link_filtered () with capabilities.
- See <xref linkend="sec-caps"/> for
+ See <xref linkend="section-caps"/> for
an explanation of capabilities.
</para>
</sect1>
-<chapter id="cha-links">
+<chapter id="chapter-links">
<title>Linking elements</title>
<para>
You can link the different pads of elements together so that the elements
form a chain.
</para>
- <figure float="1" id="sec-link">
+ <figure float="1" id="section-link">
<title>Visualisation of three linked elements</title>
<mediaobject>
<imageobject>
</author>
</authorgroup>
- <legalnotice id="legalnotice">
+ <legalnotice id="misc-legalnotice">
<para>
This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or later (the
<!-- ############# Overview - part ############### -->
- <part id="overview"><title>Overview</title>
+ <part id="part-overview"><title>Overview</title>
<partintro>
<para>
- <xref linkend="overview"/> gives you an overview of
+ <xref linkend="part-overview"/> gives you an overview of
<application>GStreamer</application> design goals.
- <xref linkend="basic-concepts"/> rapidly covers the basics of
+ <xref linkend="part-basic-concepts"/> rapidly covers the basics of
<application>GStreamer</application> programming.
- In <xref linkend="build-app"/> we will move on to the
+ In <xref linkend="part-build-app"/> we will move on to the
examples. Since <application>GStreamer</application> 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
<!-- ############ Basic concepts - part ############# -->
- <part id="basic-concepts"><title>Basic Concepts</title>
+ <part id="part-basic-concepts"><title>Basic Concepts</title>
<partintro>
<para>
We will first describe the basics of
</part>
<!-- ############ Basic API - part ############# -->
- <part id="basic-api"><title>Basic API</title>
+ <part id="part-basic-api"><title>Basic API</title>
&INIT-API;
&ELEMENTS-API;
<!-- ############ Building Apps - part ############# -->
- <part id="build-app"><title>Building an application</title>
+ <part id="part-build-app"><title>Building an application</title>
<partintro>
<para>
<!-- ############ Advanced GStreamer - part ############# -->
- <part id="advanced"><title>Advanced <application>GStreamer</application> concepts</title>
+ <part id="
part-advanced"><title>Advanced <application>GStreamer</application> concepts</title>
<partintro>
<para>
<!-- ############ XML in GStreamer - part ############# -->
- <part id="xml-gstreamer"><title>XML in <application>GStreamer</application></title>
+ <part id="
part-xml-gstreamer"><title>XML in <application>GStreamer</application></title>
<partintro>
<para>
<!-- ############ Appendices - part ############# -->
- <part id="appendices">
+ <part id="part-appendices">
<title>Appendices</title>
<partintro>
-<chapter id="cha-motivation">
+<chapter id="chapter-motivation">
<title>Motivation</title>
<para>
Linux has historically lagged behind other operating systems in the multimedia
with the professional level of software available for MS Windows and MacOS.
</para>
- <sect1 id="sec-motivation-problems">
+ <sect1 id="section-motivation-problems">
<title>Current problems</title>
<para>
We describe the typical problems in today's media handling on Linux.
</para>
- <sect2 id="sec-motivation-duplicate">
+ <sect2 id="section-motivation-duplicate">
<title>Multitude of duplicate code</title>
<para>
The Linux user who wishes to hear a sound file must hunt through their collection of
</para>
</sect2>
- <sect2 id="sec-motivation-goal">
+ <sect2 id="section-motivation-goal">
<title>'One goal' media players/libraries</title>
<para>
Your typical MPEG player was designed to play MPEG video and audio. Most of
</para>
</sect2>
- <sect2 id="sec-motivation-plugin">
+ <sect2 id="section-motivation-plugin">
<title>Non unified plugin mechanisms</title>
<para>
Your typical media player might have a plugin for different media
</para>
</sect2>
- <sect2 id="sec-motivation-network">
+ <sect2 id="section-motivation-network">
<title>Provision for network transparency</title>
<para>
No infrastructure is present to allow network transparent media
</para>
</sect2>
- <sect2 id="sec-motivation-catchup">
+ <sect2 id="section-motivation-catchup">
<title>Catch up with the <trademark>Windows</trademark> world</title>
<para>
We need solid media handling if we want to see Linux succeed on
-<chapter id="cha-pads-api">
+<chapter id="chapter-pads-api">
<title>Pads</title>
<para>
- As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
+ As we have seen in <xref linkend="chapter-elements"/>, the pads are the element's
interface to the outside world.
</para>
<para>
The specific type of media that the element can handle will be exposed by the pads.
The description of this media type is done with capabilities(see
- <xref linkend="sec-caps"/>)
+ <xref linkend="section-caps"/>)
</para>
<para>
</para></footnote>
</para>
- <sect1 id="sec-pads-api-type">
+ <sect1 id="section-pads-api-type">
<title>Types of pads</title>
- <sect2 id="sec-pads-api-dynamic">
+ <sect2 id="section-pads-api-dynamic">
<title>Dynamic pads</title>
<para>
You can attach a signal to an element to inform you when the element has created
</para>
</note>
</sect2>
- <sect2 id="sec-pads-api-request">
+ <sect2 id="section-pads-api-request">
<title>Request pads</title>
<para>
The following piece of code can be used to get a pad from the tee element. After
</sect1>
- <sect1 id="sec-api-caps">
+ <sect1 id="section-api-caps">
<title>Capabilities of a pad</title>
<para>
Since the pads play a very important role in how the element is viewed by the
Plugin Writer's Guide.
</para>
- <sect2 id="sec-pads-api-caps">
+ <sect2 id="section-pads-api-caps">
<title>Capabilities</title>
<para>
Capabilities are attached to a pad in order to describe
</programlisting>
</sect2>
- <sect2 id="sec-pads-api-caps-get">
+ <sect2 id="section-pads-api-caps-get">
<title>Getting the capabilities of a pad</title>
<para>
A pad can have a chain of capabilities attached to it. You can get the capabilities chain
...
</programlisting>
</sect2>
- <sect2 id="sec-pads-api-caps-create">
+ <sect2 id="section-pads-api-caps-create">
<title>Creating capability structures</title>
<para>
While capabilities are mainly used inside a plugin to describe the
-<chapter id="cha-pads">
+<chapter id="chapter-pads">
<title>Pads</title>
<para>
- As we have seen in <xref linkend="cha-elements"/>, the pads are the element's
+ As we have seen in <xref linkend="chapter-elements"/>, the pads are the element's
interface to the outside world.
</para>
<para>
The specific type of media that the element can handle will be exposed by the pads.
The description of this media type is done with capabilities(see
- <xref linkend="sec-caps"/>)
+ <xref linkend="section-caps"/>)
</para>
<para>
</para></footnote>
</para>
- <sect1 id="sec-pads-type">
+ <sect1 id="section-pads-type">
<title>Types of pads</title>
- <sect2 id="sec-pads-dynamic">
+ <sect2 id="section-pads-dynamic">
<title>Dynamic pads</title>
<para>
Some elements might not have all of their pads when the element is
pipelines later on in this manual.
</para>
</sect2>
- <sect2 id="sec-pads-request">
+ <sect2 id="section-pads-request">
<title>Request pads</title>
<para>
An element can also have request pads. These pads are not created
</sect1>
- <sect1 id="sec-caps">
+ <sect1 id="section-caps">
<title>Capabilities of a pad</title>
<para>
Since the pads play a very important role in how the element is viewed by the
Plugin Writer's Guide.
</para>
- <sect2 id="sec-pads-caps">
+ <sect2 id="section-pads-caps">
<title>Capabilities</title>
<para>
Capabilities are attached to a pad in order to describe
rate: Integer range: 11025 - 48000
</programlisting>
</sect2>
- <sect2 id="sec-pads-props">
+ <sect2 id="section-pads-props">
<title>What are properties ?</title>
<para>
Properties are used to describe extra information for
</itemizedlist>
</sect2>
- <sect2 id="sec-pads-caps-use">
+ <sect2 id="section-pads-caps-use">
<title>What capabilities are used for</title>
<para>
Capabilities describe in great detail the type of media that is handled by the pads.
-<chapter id="cha-plugins-api">
+<chapter id="chapter-plugins-api">
<title>Plugins</title>
<!-- FIXME: introduce type definitions before this chapter -->
<para>
-<chapter id="cha-plugins">
+<chapter id="chapter-plugins">
<title>Plugins</title>
<!-- FIXME: introduce type definitions before this chapter -->
<para>
-<chapter id="cha-programs">
+<chapter id="chapter-programs">
<title>Programs</title>
<para>
</para>
- <sect1>
+ <sect1 id="section-programs-gst-register">
<title><command>gst-register</command></title>
<para>
<command>gst-register</command> is used to rebuild the database of plugins.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-programs-gst-launch">
<title><command>gst-launch</command></title>
<para>
This is a tool that will construct pipelines based on a command-line
</sect2>
</sect1>
- <sect1>
+ <sect1 id="section-programs-gst-inspect">
<title><command>gst-inspect</command></title>
<para>
This is a tool to query a plugin or an element about its properties.
-<chapter id="cha-queues">
+<chapter id="chapter-queues">
<title>Queues</title>
<para>
A queue is a filter element.
Below is a figure of a two-threaded decoder. We have one thread (the main execution
thread) reading the data from a file, and another thread decoding the data.
</para>
- <figure float="1" id="sec-queues-img">
+ <figure float="1" id="section-queues-img">
<title>a two-threaded decoder with a queue</title>
<mediaobject>
<imageobject>
-<chapter id="cha-quotes">
+<chapter id="chapter-quotes">
<title>Quotes from the Developers</title>
<para>
As well as being a cool piece of software,
-<chapter id="cha-scheduler">
+<chapter id="chapter-scheduler">
<title>Understanding schedulers</title>
<para>
The scheduler is responsible for managing the plugins at runtime. Its
-<chapter id="cha-states-api">
+<chapter id="chapter-states-api">
<title>Element states</title>
- <sect1 id="sec-states-api">
+ <sect1 id="section-states-api">
<title>Changing element state</title>
<para>
The state of an element can be changed with the following code:
-<chapter id="cha-states">
+<chapter id="chapter-states">
<title>Element states</title>
<para>
Once you have created a pipeline packed with elements, nothing will happen
right away. This is where the different states come into play.
</para>
- <sect1 id="sec-states">
+ <sect1 id="section-states">
<title>The different element states</title>
<para>
An element can be in one of the following four states:
</sect1>
- <sect1 id="sec-states-null">
+ <sect1 id="section-states-null">
<title>The NULL state</title>
<para>
When you created the pipeline all of the elements will be in the NULL state. There is
</note>
</sect1>
- <sect1 id="sec-states-ready">
+ <sect1 id="section-states-ready">
<title>The READY state</title>
<para>
You will start the pipeline by first setting it to the READY state. This will allow the
</note>
</sect1>
- <sect1 id="sec-states-paused">
+ <sect1 id="section-states-paused">
<title>The PAUSED state</title>
<para>
A pipeline that is playing can be set to the PAUSED state. This will temporarily stop all
</note>
<para>
The pipeline has to be in the PAUSED or NULL state if you want to insert or modify an element
- in the pipeline. We will cover dynamic pipeline behaviour in <xref linkend="cha-dynamic"/>.
+ in the pipeline. We will cover dynamic pipeline behaviour in <xref linkend="chapter-dynamic"/>.
</para>
</sect1>
- <sect1 id="sec-states-playing">
+ <sect1 id="section-states-playing">
<title>The PLAYING state</title>
<para>
A Pipeline that is in the READY state can be started by setting it to the PLAYING state. At
-<chapter id="cha-threads">
+<chapter id="chapter-threads">
<title>Threads</title>
<para>
GStreamer has support for multithreading through the use of
itself. You never need to explicitly iterate a thread.
</para>
- <sect1>
+ <sect1 id="section-threads-constraints">
<title>Constraints placed on the pipeline by the GstThread</title>
<para>
Within the pipeline, everything is the same as in any other bin. The
fundamentally buffer-oriented rather than byte-oriented, the natural
solution to this problem is an element that can "buffer" the buffers
between the threads, in a thread-safe fashion. This element is the
- queue, described more fully in <xref linkend="cha-queues"/>. It doesn't
+ queue, described more fully in <xref linkend="chapter-queues"/>. It doesn't
matter if the queue is placed in the containing bin or in the thread
itself, but it needs to be present on one side or the other to enable
inter-thread communication.
</para>
</sect1>
- <sect1>
+ <sect1 id="section-threads-when">
<title>When would you want to use a thread?</title>
<para>
If you are writing a GUI application, making the top-level bin a thread will make your GUI
an audio pipeline.
</para>
<para>
- <xref linkend="sec-threads-img"/> shows how a thread can be visualised.
+ <xref linkend="section-threads-img"/> shows how a thread can be visualised.
</para>
- <figure float="1" id="sec-threads-img">
+ <figure float="1" id="section-threads-img">
<title>A thread</title>
<mediaobject>
<imageobject>
-<chapter id="cha-typedetection">
+<chapter id="chapter-typedetection">
<title>Type Detection</title>
<para>
Sometimes the capabilities of a pad are not specificied. The filesrc
-<chapter id="cha-xml">
+<chapter id="chapter-xml">
<title>XML in <application>GStreamer</application></title>
<para>
<application>GStreamer</application> uses XML to store and load
XML file again for later use.
</para>
- <sect1 id="sec-xml-write">
+ <sect1 id="section-xml-write">
<title>Turning GstElements into XML</title>
<para>
</para>
</sect1>
- <sect1 id="sec-xml-load">
+ <sect1 id="section-xml-load">
<title>Loading a GstElement from an XML file</title>
<para>
Before an XML file can be loaded, you must create a GstXML object.
success or failure of the requested action.
</para>
</sect1>
- <sect1 id="sec-xml-custom">
+ <sect1 id="section-xml-custom">
<title>Adding custom XML tags into the core XML data</title>
<para>
projects / platform / upstream / gstreamer.git / commitdiff