gstreamer/docs/manual/elements.xml
Thomas Vander Stichele 3b7659725f typos and style fixes
Original commit message from CVS:
typos and style fixes
2003-10-09 12:42:49 +00:00

256 lines
9.6 KiB
XML

<chapter id="cha-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">
<title>What is an element ?</title>
<para>
An element is the basic building block for the media pipeline.
All the different high-level 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" (see <xref linkend="cha-pads"/>), or link points. This terminology arises from soldering;
pads are where wires can be attached.
</para>
</sect1>
<sect1 id="sec-elements-types">
<title>Types of elements</title>
<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.
</para>
<para>
<xref linkend="sec-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">
<title>Visualisation of a source element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/src-element.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
<para>
Source elements do not accept data, they only generate data. You can
see this in the figure because it only has a source pad. A source
pad can only generate data.
</para>
</sect2>
<sect2 id="sec-elements-filter">
<title>Filters and codecs</title>
<para>
Filter elements have both input and output pads. They operate on
data they receive in their sink pads and produce data on their source
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 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>
<imageobject>
<imagedata fileref="images/filter-element.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
<para>
<xref linkend="sec-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">
<title>Visualisation of a filter element with
more than one output pad</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/filter-element-multi.&image;"
format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
<para>
<xref linkend="sec-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
send out a signal when a new pad is created so that the application
programmer can link an arbitrary element to the newly created pad.
</para>
</sect2>
<sect2 id="sec-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.
</para>
<figure float="1" id="sec-element-sinkimg">
<title>Visualisation of a sink element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/sink-element.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
</sect2>
</sect1>
<sect1 id="sec-elements-create">
<title>Creating a GstElement</title>
<para>
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.
</para>
<programlisting>
GstElementFactory *factory;
factory = gst_element_factory_find ("mad");
</programlisting>
<para>
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>
<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 element
factory named "mad". This convenience function is most widely used to
create an element.
</para>
<programlisting>
GstElement *element;
element = gst_element_factory_make ("mad", "decoder");
</programlisting>
<para>
When you don't need the element anymore, you need to unref it, as shown in the following
example.
</para>
<programlisting>
GstElement *element;
...
gst_element_unref (element);
</programlisting>
</sect1>
<sect1 id="sec-elements-properties">
<title>GstElement properties</title>
<para>
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 <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;
GValue value = { 0, }; /* initialize the GValue for g_object_get() */
element = gst_element_factory_make ("mad", "decoder");
g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
...
g_value_init (&amp;value, G_TYPE_STRING);
g_object_get_property (G_OBJECT (element), "name", &amp;value);
...
</programlisting>
<para>
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 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 <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> and an introduction to <ulink
url="http://le-hacker.org/papers/gobject/index.html" type="http">
The Glib Object system</ulink>.
</para>
</sect1>
<sect1 id="sec-elements-signals">
<title>GstElement signals</title>
<para>
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-factories">
<title>More about GstElementFactory</title>
<para>
We talk some more about the GstElementFactory object.
</para>
<sect2 id="sec-elements-factories-details">
<title>Getting information about an element using the factory details</title>
<para>
</para>
</sect2>
<sect2 id="sec-elements-factories-padtemplates">
<title>Finding out what pads an element can contain</title>
<para>
</para>
</sect2>
<sect2 id="sec-elements-factories-query">
<title>Different ways of querying the factories</title>
<para>
</para>
</sect2>
</sect1>
</chapter>