[gst-devel] [PATCH] documentation patch (2nd try)
Cameron Hutchison
camh+gst at xdna.net
Fri Aug 30 07:22:05 CEST 2002
I forget to add attachments more often than not... sigh...
-------------- next part --------------
Index: gstreamer/docs/manual/elements.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/elements.xml,v
retrieving revision 1.4
diff -u -u -r1.4 elements.xml
--- gstreamer/docs/manual/elements.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/elements.xml 30 Aug 2002 14:09:53 -0000
@@ -8,9 +8,10 @@
<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
@@ -38,19 +39,20 @@
<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
+ 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>
@@ -77,20 +79,21 @@
</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,8 +108,10 @@
<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 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
@@ -118,8 +123,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 +132,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 lookup 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 convenient function is most widely used to
+ create an element.
</para>
<programlisting>
GstElement *element;
@@ -155,16 +163,21 @@
<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 +195,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>
Index: gstreamer/docs/manual/goals.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/goals.xml,v
retrieving revision 1.3
diff -u -u -r1.3 goals.xml
--- gstreamer/docs/manual/goals.xml 24 Jul 2002 19:46:42 -0000 1.3
+++ gstreamer/docs/manual/goals.xml 30 Aug 2002 14:09:53 -0000
@@ -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>
Index: gstreamer/docs/manual/gstreamer-manual.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/gstreamer-manual.xml,v
retrieving revision 1.4
diff -u -u -r1.4 gstreamer-manual.xml
--- gstreamer/docs/manual/gstreamer-manual.xml 7 Apr 2002 23:32:11 -0000 1.4
+++ gstreamer/docs/manual/gstreamer-manual.xml 30 Aug 2002 14:09:53 -0000
@@ -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
Index: gstreamer/docs/manual/init.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/init.xml,v
retrieving revision 1.3
diff -u -u -r1.3 init.xml
--- gstreamer/docs/manual/init.xml 24 Jul 2002 19:46:42 -0000 1.3
+++ gstreamer/docs/manual/init.xml 30 Aug 2002 14:09:53 -0000
@@ -2,13 +2,14 @@
<title>Initializing <application>GStreamer</application></title>
<para>
When writing a <application>GStreamer</application> application, you can
- simply include gst/gst.h to get access to the library functions.
+ simply include <filename class='headerfile'>gst/gst.h</filename> to get
+ access to the library functions.
</para>
<para>
Before the <application>GStreamer</application> libraries can be used
- gst_init () has to be performed from the main app. this call will perform
- first initialisation and will parse the GStreamer specific command line
- options.
+ <function>gst_init</function> has to be called from the main app. This
+ call will perform first initialization and will parse the GStreamer
+ specific command line options.
</para>
<para>
A typical program would start like this:
@@ -28,17 +29,30 @@
}
</programlisting>
<para>
- It is also possible to call the gst_init method with two NULL arguments.
+ FIXME: What options does gst_init look for and what do they do???
+ </para>
+ <para>
+ It is also possible to call the <function>gst_init</function> function
+ with two <symbol>NULL</symbol> arguments, in which case no command line
+ options will parsed by <application>GStreamer</application>.
</para>
<para>
- Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to
- get the <application>GStreamer</application> version you are building against or
- use gst_version() to get the version you are linked against.
+ Use the <symbol>GST_VERSION_MAJOR</symbol>,
+ <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
+ macros to get the <application>GStreamer</application> version you are
+ building against or use the function <function>gst_version</function>
+ to get the version your application is linked against.
</para>
<sect1>
<title>The popt interface</title>
<para>
- You can also use a popt table to initialize your own parameters as shown in the next code fragment:
+ You can also use a <ulink
+ url="http://developer.gnome.org/doc/guides/popt/"
+ type="http">popt</ulink> table to define your application
+ specific command line options, and pass this table to the
+ function <function>gst_init_with_popt_table</function>. Your
+ application options will be parsed in addition to the standard
+ <application>GStreamer</application> options.
</para>
<programlisting>
int
Index: gstreamer/docs/manual/intro.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/intro.xml,v
retrieving revision 1.4
diff -u -u -r1.4 intro.xml
--- gstreamer/docs/manual/intro.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/intro.xml 30 Aug 2002 14:09:53 -0000
@@ -22,14 +22,14 @@
</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 so on.
- GStreamer, however, is much more than just another media player. Its
- main advantages are that the pluggable components can be mixed and matched into
- abitrary pipelines so that it's possible
- to write a full fledged video or audio editing application.
+ 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 so on. GStreamer,
+ however, is much more than just another media player. Its main advantages
+ are that the pluggable components can be mixed and matched into abitrary
+ pipelines so that it's possible to write a full fledged video or audio
+ editing application.
</para>
<para>
Index: gstreamer/docs/manual/motivation.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/motivation.xml,v
retrieving revision 1.4
diff -u -u -r1.4 motivation.xml
--- gstreamer/docs/manual/motivation.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/motivation.xml 30 Aug 2002 14:09:53 -0000
@@ -83,7 +83,8 @@
</para>
<para>
No provisions have been made for emerging technologies such as
- the GNOME object embedding using Bonobo.
+ the <ulink url="http://developer.gnome.org/arch/component/bonobo.html"
+ type="http">GNOME object embedding using Bonobo</ulink>.
</para>
<para>
The GStreamer cores does not use network transparent technologies at the
Index: gstreamer/docs/manual/plugins.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/plugins.xml,v
retrieving revision 1.3
diff -u -u -r1.3 plugins.xml
--- gstreamer/docs/manual/plugins.xml 9 Jul 2002 18:43:13 -0000 1.3
+++ gstreamer/docs/manual/plugins.xml 30 Aug 2002 14:09:53 -0000
@@ -1,5 +1,8 @@
<chapter id="cha-plugins">
- <title>What are Plugins</title>
+ <title>Plugins</title>
+ <para>
+ FIXME: Type definitions should be introduced before this chapter
+ </para>
<para>
A plugin is a shared library that contains at least one of the following items:
</para>
@@ -7,17 +10,17 @@
<itemizedlist>
<listitem>
<para>
- one or more elementfactories
+ one or more element factories
</para>
</listitem>
<listitem>
<para>
- one or more typedefinitions
+ one or more type definitions
</para>
</listitem>
<listitem>
<para>
- one or more autopluggers
+ one or more auto-pluggers
</para>
</listitem>
<listitem>
@@ -27,19 +30,23 @@
</listitem>
</itemizedlist>
<para>
- The plugins have one simple method: plugin_init () where all the elementfactories are
- created and the typedefinitions are registered.
+ All plugins have one main function, <function>plugin_init</function>,
+ that creates all the element factories and registers all the type
+ definitions contained in the plugin.
</para>
<para>
- the plugins are maintained in the plugin system. Optionally, the typedefinitions and
- the elementfactories can be saved into an XML representation so that the plugin system
- does not have to load all available plugins in order to know their definition.
+ The plugins are maintained in the plugin system. Optionally, the
+ type definitions and the element factories can be saved into an XML
+ representation so that the plugin system does not have to load all
+ available plugins in order to know their definition.
</para>
<para>
The basic plugin structure has the following fields:
</para>
<programlisting>
+typedef struct _GstPlugin GstPlugin;
+
struct _GstPlugin {
gchar *name; /* name of the plugin */
gchar *longname; /* long name of plugin */
@@ -57,7 +64,8 @@
</programlisting>
<para>
- You can query a GList of available plugins with:
+ You can query a <classname>GList</classname> of available plugins with the
+ function <function>gst_plugin_get_list</function> as this example shows:
</para>
<programlisting>
GList *plugins;
Index: gstreamer/docs/manual/threads.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/threads.xml,v
retrieving revision 1.5
diff -u -u -r1.5 threads.xml
--- gstreamer/docs/manual/threads.xml 9 Jul 2002 18:43:13 -0000 1.5
+++ gstreamer/docs/manual/threads.xml 30 Aug 2002 14:09:53 -0000
@@ -81,7 +81,7 @@
/* eos will be called when the src element has an end of stream */
void
-eos (GstSrc *src, gpointer data)
+eos (GstElement *src, gpointer data)
{
GstThread *thread = GST_THREAD (data);
g_print ("have eos, quitting\n");
More information about the gstreamer-devel
mailing list