scrubbed and applied cameron's patch

Original commit message from CVS:
scrubbed and applied cameron's patch
This commit is contained in:
Thomas Vander Stichele 2002-09-06 15:53:06 +00:00
parent 6fc49a76a1
commit 08ff42a0c3
4 changed files with 174 additions and 122 deletions

View file

@ -8,20 +8,23 @@
<sect1 id="sec-elements-design">
<title>What is a GstElement</title>
<para>
The GstElement is the basic building block for the media pipeline. All the
different components you are going to use are derived from this GstElement.
This means that a lot of functions you are going to use operate on this object.
<classname>GstElement</classname> is the basic building block for the
media pipeline. All the different components you are going to use are
derived from <classname>GstElement</classname>. This means that a
lot of functions you are going to use operate on objects of this class.
</para>
<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", or connection points. This
terminology arises from soldering; pads are where wires can be attached.
<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", or connection points. This terminology arises from soldering;
pads are where wires can be attached.
</para>
<sect2 id="sec-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.
Source elements generate data for use by a pipeline, for example
reading from disk or from a sound card.
</para>
<para>
Below you see how we will visualize the element.
@ -38,21 +41,22 @@
<para>
Source elements do not accept data, they only generate data. You can see
this in the figure because it only has a src pad. A src pad can only
generate buffers.
generate data.
</para>
</sect2>
<sect2 id="sec-elements-filter">
<title>Filters and codecs</title>
<para>
Filter elements both have input and output pads. They operate on data they receive in their
sink pads and produce data on their src pads. For example, MPEG decoders and volume filters
would fall into this category.
Filter elements both have input and output pads. They operate on
data they receive in their sink pads and produce data on their src
pads. For example, MPEG decoders and volume filters would fall into
this category.
</para>
<para>
Elements are not constrained as to the number of pads they migh have; for example, a video
mixer might have two input pads (the images of the two different video streams) and one
output pad.
Elements are not constrained as to the number of pads they might have;
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">
<title>Visualisation of a filter element</title>
@ -63,34 +67,36 @@
</mediaobject>
</figure>
<para>
The above figure shows the visualisation of a filter element. This element has
one sink (input) pad and one src (output) pad. Sink pads are drawn on the left
of the element.
The above figure shows the visualisation of a filter element.
This element has one sink (input) pad and one src (output) pad.
Sink pads are drawn on the left of the element.
</para>
<figure float="1" id="sec-element-multifilterimg">
<title>Visualisation of a filter element with
more than one output pad</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/filter-element-multi.&magic;" format="&magic;" />
<imagedata fileref="images/filter-element-multi.&magic;"
format="&magic;" />
</imageobject>
</mediaobject>
</figure>
<para>
The above figure shows the visualisation of a filter element with more than one output pad.
An example of such a filter is the AVI splitter (demuxer). This element will parse the input
data and extracts the audio and video data. Most of these filters dynamically send out a
signal when a new pad is created so that the application programmer can connect an arbitrary
element to the newly created pad.
The above figure shows the visualisation of a filter element with
more than one output pad. An example of such a filter is the AVI
splitter (demultiplexer). This element will parse the input data and
extract the audio and video data. Most of these filters dynamically
send out a signal when a new pad is created so that the application
programmer can connect an arbitrary element to the newly created pad.
</para>
</sect2>
<sect2 id="sec-elements-sink">
<title>Sink elements</title>
<para>
Sink elements are terminal points in a media pipeline. They accept data but do not produce
anything. Disk writing, soundcard playback, and video output woul all be implemented by sink
elements.
Sink elements are terminal 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.
</para>
<figure float="1" id="sec-element-sinkimg">
<title>Visualisation of a sink element</title>
@ -105,12 +111,14 @@
<sect1 id="sec-elements-create">
<title>Creating a GstElement</title>
<para>
GstElements are created from factories. To create an element, one has to get
access the a <classname>GstElementFactory</classname> using a unique factoryname.
A <classname>GstElement</classname> object is created from
a factory. To create an element, you have to get access to a
<classname>GstElementFactory</classname> object using a unique
factory name.
</para>
<para>
The following code example is used to get a factory that can be used to create the
'mad' element, an mp3 decoder.
The following code example is used to get a factory that can be used
to create the 'mad' element, an mp3 decoder.
</para>
<programlisting>
GstElementFactory *factory;
@ -118,8 +126,8 @@
factory = gst_element_factory_find ("mad");
</programlisting>
<para>
Once you have the handle to the elementfactory, you can create a real element with
the following code fragment:
Once you have the handle to the element factory, you can create a
real element with the following code fragment:
</para>
<programlisting>
GstElement *element;
@ -127,14 +135,17 @@
element = gst_element_factory_create (factory, "decoder");
</programlisting>
<para>
gst_element_factory_create () will use the elementfactory to create an element with the given
name. The name of the element is something you can use later on to lookup the element in a
bin, for example. You can pass NULL as the name argument to get a unique, default name.
<function>gst_element_factory_create</function> will use the element
factory to create an element with the given name. The name of the
element is something you can use later on to look up the element in
a bin, for example. You can pass <symbol>NULL</symbol> as the name
argument to get a unique, default name.
</para>
<para>
A simple shortcut exists for creating an element from a factory. The following example creates
an element, named "decoder" from the elementfactory named "mad". This convenient function is
most widely used to create an element.
A simple shortcut exists for creating an element from a factory. The
following example creates an element named "decoder" from the element
factory named "mad". This convenience function is most widely used to
create an element.
</para>
<programlisting>
GstElement *element;
@ -155,16 +166,22 @@
<sect1 id="sec-elements-properties">
<title>GstElement properties</title>
<para>
A GstElement can have several properties which are implemented using standard
GObject properties. The usual GObject methods to query, set and get property values
and GParamSpecs are therefore supported.
A <classname>GstElement</classname> can have several properties
which are implemented using standard <classname>GObject</classname>
properties. The usual <classname>GObject</classname> methods to query,
set and get property values and <classname>GParamSpecs</classname>
are therefore supported.
</para>
<para>
Every GstElement inherits at least one property of its parent GstObject, the "name"
property. This is the name you provide to gst_element_factory_make() or
gst_element_factory_create(). You can get and set this property using the
gst_object_set_name() and gst_object_get_name() or use the GObject property
mechanism as shown below.
Every <classname>GstElement</classname> inherits at least
one property of its parent <classname>GstObject</classname>:
the "name" property. This is the name you provide to the
functions <function>gst_element_factory_make</function> or
<function>gst_element_factory_create</function>. You can get and set
this property using the functions
<function>gst_object_set_name</function>
and <function>gst_object_get_name</function> or use the
<classname>GObject</classname> property mechanism as shown below.
</para>
<programlisting>
GstElement *element;
@ -182,20 +199,23 @@
Most plugins provide additional properties to provide more information
about their configuration or to configure the element.
<command>gst-inspect</command> is a useful tool to query the properties
of a perticular element, it will also use property introspection to give
of a particular element, it will also use property introspection to give
a short explanation about the function of the property and about the
parameter types and ranges it supports.
</para>
<para>
For more information about GObject properties we recommend to read the GObject
manual.
For more information about <classname>GObject</classname>
properties we recommend you read the <ulink
url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
type="http">GObject manual</ulink>.
</para>
</sect1>
<sect1 id="sec-elements-signals">
<title>GstElement signals</title>
<para>
A GstElement also provides various GObject signals that can be used as a flexible
A <classname>GstElement</classname> also provides various
<classname>GObject</classname> signals that can be used as a flexible
callback mechanism.
</para>
</sect1>

View file

@ -8,20 +8,23 @@
<sect1 id="sec-elements-design">
<title>What is a GstElement</title>
<para>
The GstElement is the basic building block for the media pipeline. All the
different components you are going to use are derived from this GstElement.
This means that a lot of functions you are going to use operate on this object.
<classname>GstElement</classname> is the basic building block for the
media pipeline. All the different components you are going to use are
derived from <classname>GstElement</classname>. This means that a
lot of functions you are going to use operate on objects of this class.
</para>
<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", or connection points. This
terminology arises from soldering; pads are where wires can be attached.
<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", or connection points. This terminology arises from soldering;
pads are where wires can be attached.
</para>
<sect2 id="sec-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.
Source elements generate data for use by a pipeline, for example
reading from disk or from a sound card.
</para>
<para>
Below you see how we will visualize the element.
@ -38,21 +41,22 @@
<para>
Source elements do not accept data, they only generate data. You can see
this in the figure because it only has a src pad. A src pad can only
generate buffers.
generate data.
</para>
</sect2>
<sect2 id="sec-elements-filter">
<title>Filters and codecs</title>
<para>
Filter elements both have input and output pads. They operate on data they receive in their
sink pads and produce data on their src pads. For example, MPEG decoders and volume filters
would fall into this category.
Filter elements both have input and output pads. They operate on
data they receive in their sink pads and produce data on their src
pads. For example, MPEG decoders and volume filters would fall into
this category.
</para>
<para>
Elements are not constrained as to the number of pads they migh have; for example, a video
mixer might have two input pads (the images of the two different video streams) and one
output pad.
Elements are not constrained as to the number of pads they might have;
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">
<title>Visualisation of a filter element</title>
@ -63,34 +67,36 @@
</mediaobject>
</figure>
<para>
The above figure shows the visualisation of a filter element. This element has
one sink (input) pad and one src (output) pad. Sink pads are drawn on the left
of the element.
The above figure shows the visualisation of a filter element.
This element has one sink (input) pad and one src (output) pad.
Sink pads are drawn on the left of the element.
</para>
<figure float="1" id="sec-element-multifilterimg">
<title>Visualisation of a filter element with
more than one output pad</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/filter-element-multi.&magic;" format="&magic;" />
<imagedata fileref="images/filter-element-multi.&magic;"
format="&magic;" />
</imageobject>
</mediaobject>
</figure>
<para>
The above figure shows the visualisation of a filter element with more than one output pad.
An example of such a filter is the AVI splitter (demuxer). This element will parse the input
data and extracts the audio and video data. Most of these filters dynamically send out a
signal when a new pad is created so that the application programmer can connect an arbitrary
element to the newly created pad.
The above figure shows the visualisation of a filter element with
more than one output pad. An example of such a filter is the AVI
splitter (demultiplexer). This element will parse the input data and
extract the audio and video data. Most of these filters dynamically
send out a signal when a new pad is created so that the application
programmer can connect an arbitrary element to the newly created pad.
</para>
</sect2>
<sect2 id="sec-elements-sink">
<title>Sink elements</title>
<para>
Sink elements are terminal points in a media pipeline. They accept data but do not produce
anything. Disk writing, soundcard playback, and video output woul all be implemented by sink
elements.
Sink elements are terminal 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.
</para>
<figure float="1" id="sec-element-sinkimg">
<title>Visualisation of a sink element</title>
@ -105,12 +111,14 @@
<sect1 id="sec-elements-create">
<title>Creating a GstElement</title>
<para>
GstElements are created from factories. To create an element, one has to get
access the a <classname>GstElementFactory</classname> using a unique factoryname.
A <classname>GstElement</classname> object is created from
a factory. To create an element, you have to get access to a
<classname>GstElementFactory</classname> object using a unique
factory name.
</para>
<para>
The following code example is used to get a factory that can be used to create the
'mad' element, an mp3 decoder.
The following code example is used to get a factory that can be used
to create the 'mad' element, an mp3 decoder.
</para>
<programlisting>
GstElementFactory *factory;
@ -118,8 +126,8 @@
factory = gst_element_factory_find ("mad");
</programlisting>
<para>
Once you have the handle to the elementfactory, you can create a real element with
the following code fragment:
Once you have the handle to the element factory, you can create a
real element with the following code fragment:
</para>
<programlisting>
GstElement *element;
@ -127,14 +135,17 @@
element = gst_element_factory_create (factory, "decoder");
</programlisting>
<para>
gst_element_factory_create () will use the elementfactory to create an element with the given
name. The name of the element is something you can use later on to lookup the element in a
bin, for example. You can pass NULL as the name argument to get a unique, default name.
<function>gst_element_factory_create</function> will use the element
factory to create an element with the given name. The name of the
element is something you can use later on to look up the element in
a bin, for example. You can pass <symbol>NULL</symbol> as the name
argument to get a unique, default name.
</para>
<para>
A simple shortcut exists for creating an element from a factory. The following example creates
an element, named "decoder" from the elementfactory named "mad". This convenient function is
most widely used to create an element.
A simple shortcut exists for creating an element from a factory. The
following example creates an element named "decoder" from the element
factory named "mad". This convenience function is most widely used to
create an element.
</para>
<programlisting>
GstElement *element;
@ -155,16 +166,22 @@
<sect1 id="sec-elements-properties">
<title>GstElement properties</title>
<para>
A GstElement can have several properties which are implemented using standard
GObject properties. The usual GObject methods to query, set and get property values
and GParamSpecs are therefore supported.
A <classname>GstElement</classname> can have several properties
which are implemented using standard <classname>GObject</classname>
properties. The usual <classname>GObject</classname> methods to query,
set and get property values and <classname>GParamSpecs</classname>
are therefore supported.
</para>
<para>
Every GstElement inherits at least one property of its parent GstObject, the "name"
property. This is the name you provide to gst_element_factory_make() or
gst_element_factory_create(). You can get and set this property using the
gst_object_set_name() and gst_object_get_name() or use the GObject property
mechanism as shown below.
Every <classname>GstElement</classname> inherits at least
one property of its parent <classname>GstObject</classname>:
the "name" property. This is the name you provide to the
functions <function>gst_element_factory_make</function> or
<function>gst_element_factory_create</function>. You can get and set
this property using the functions
<function>gst_object_set_name</function>
and <function>gst_object_get_name</function> or use the
<classname>GObject</classname> property mechanism as shown below.
</para>
<programlisting>
GstElement *element;
@ -182,20 +199,23 @@
Most plugins provide additional properties to provide more information
about their configuration or to configure the element.
<command>gst-inspect</command> is a useful tool to query the properties
of a perticular element, it will also use property introspection to give
of a particular element, it will also use property introspection to give
a short explanation about the function of the property and about the
parameter types and ranges it supports.
</para>
<para>
For more information about GObject properties we recommend to read the GObject
manual.
For more information about <classname>GObject</classname>
properties we recommend you read the <ulink
url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
type="http">GObject manual</ulink>.
</para>
</sect1>
<sect1 id="sec-elements-signals">
<title>GstElement signals</title>
<para>
A GstElement also provides various GObject signals that can be used as a flexible
A <classname>GstElement</classname> also provides various
<classname>GObject</classname> signals that can be used as a flexible
callback mechanism.
</para>
</sect1>

View file

@ -8,10 +8,10 @@
<sect1 id="sec-goals-design">
<title>The design goals</title>
<para>
We descibe what we try to achieve with GStreamer.
We describe what we try to achieve with GStreamer.
</para>
<sect2 id="sec-goals-clean">
<title>Clean and powerfull</title>
<title>Clean and powerful</title>
<para>
GStreamer wants to provide a clean interface to:
</para>
@ -19,7 +19,7 @@
<listitem>
<para>
The application programmer who wants to build a media pipeline.
The programmer can use an extensive set of powerfull tools to create
The programmer can use an extensive set of powerful tools to create
media pipelines without writing a single line of code. Performing
complex media manipulations becomes very easy.
</para>
@ -69,8 +69,8 @@
have any header files installed for the plugins.
</para>
<para>
Special care has been taking into making the plugin completely self
contained. All relevant aspects of plugins can be queried at run-time.
Special care has been taken to make plugins completely self contained.
All relevant aspects of plugins can be queried at run-time.
</para>
</sect2>
@ -115,7 +115,7 @@
</listitem>
<listitem>
<para>
Allowing HW acceleration by the use of specialized plugins.
Allowing hardware acceleration by the use of specialized plugins.
</para>
</listitem>
<listitem>
@ -136,12 +136,12 @@
<sect2 id="sec-goals-testbed">
<title>Provide a framework for codec experimentation</title>
<para>
GStreamer also wants to be an easy framework where codec developers
can experiment with different algorithms, speeding up the development
of open and free multimedia codecs like tarking and vorbis.
GStreamer also wants to be an easy framework where codec
developers can experiment with different algorithms, speeding up
the development of open and free multimedia codecs like <ulink
url="http://www.xiph.org/ogg/index.html" type="http">tarkin and
vorbis</ulink>.
</para>
<para>
</para>
</sect2>
</sect1>

View file

@ -91,13 +91,24 @@
<part id="overview"><title>Overview</title>
<partintro>
<para>
<xref linkend="overview"/> gives you an overview of <application>GStreamer</application>
design goals. <xref linkend="basic-concepts"/> rapidly covers the basics of
<application>GStreamer</application> programming. In <xref linkend="build-app"/> we will move
on to the examples. Since <application>GStreamer</application> uses GLib 2.0, the reader is
assumed to understand the basics of the GObject object model. For a gentle introduction to
this system, you may wish to read the <emphasis>GTK+ Tutorial</emphasis> or Eric Harlow's
book <emphasis>Developing Linux Applications with GTK+ and GDK</emphasis>.
<xref linkend="overview"/> gives you an overview of
<application>GStreamer</application> design goals.
<xref linkend="basic-concepts"/> rapidly covers the basics of
<application>GStreamer</application> programming.
In <xref linkend="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
<ulink url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
type="http">GObject object model</ulink>.
For a gentle introduction to this system, you may wish to read the
<emphasis><ulink url="http://www.gtk.org/tutorial/" type="http">GTK+
Tutorial</ulink></emphasis> or Eric Harlow's book <emphasis>Developing
Linux Applications with GTK+ and GDK</emphasis>.
</para>
</partintro>
@ -114,8 +125,9 @@
<part id="basic-concepts"><title>Basic concepts</title>
<partintro>
<para>
We will first describe the basics of the <application>GStreamer</application> programming by
introducing the different objects needed to create a media pipeline.
We will first describe the basics of
<application>GStreamer</application> programming by introducing the
different objects needed to create a media pipeline.
</para>
<para>
We will use a visual representation of these objects so that we can