<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.
<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>
</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>
<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;
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;
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;
<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;
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>
<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.
<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>
</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>
<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;
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;
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;
<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;
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>
<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>
<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>
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>
</listitem>
<listitem>
<para>
- Allowing HW acceleration by the use of specialized plugins.
+ Allowing hardware acceleration by the use of specialized plugins.
</para>
</listitem>
<listitem>
<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>
<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>
<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
projects / platform / upstream / gstreamer.git / commitdiff