gstreamer/docs/manual/basics-elements.xml
Andy Wingo d2c3b2087d conversion to docbook-xml. i don't have to ask that this be testing, because not ionly is it perfect, but i'm sure yo...
Original commit message from CVS:
conversion to docbook-xml. i don't have to ask that this be testing, because
not ionly is it perfect, but i'm sure you folks will learn that on your own :-)
2001-12-15 23:13:04 +00:00

161 lines
5.9 KiB
XML

<chapter id="cha-elements">
<title>GstElement</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 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.
</para>
<para>
You will see that those elements have pads. These are the elements
connections with the 'outside' world. Depending on the number and direction of
the pads, we can see three types of elements: source, filter and sink element.
</para>
<para>
These three types are all the same GstElement object, they just differ in how
the pads are.
</para>
<sect2 id="sec-elements-src">
<title>GStreamer source elements</title>
<para>
This element will generate data that will be used by the pipeline. It is
typically a file or an audio source.
</para>
<para>
Below you see how we will visualize the element.
We always draw a src 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.&magic;" format="&magic;" />
</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 src pad. A src pad can only
generate buffers.
</para>
</sect2>
<sect2 id="sec-elements-filter">
<title>GStreamer filter elements</title>
<para>
Filter elements both have an input and an output pad. They operate on data
they receive in the sink pad and send the result to the src pad.
</para>
<para>
Examples of a filter element might include: an MPEG decoder, volume filter,...
</para>
<para>
Filters may also contain any number of input pads and output pads. For example,
a video mixer might have to 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.&magic;" format="&magic;" />
</imageobject>
</mediaobject>
</figure>
<para>
The above figure shows the visualisation of a filter element. This element has
one sink pad (input) 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;" />
</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. 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.
</para>
</sect2>
<sect2 id="sec-elements-sink">
<title>GStreamer sink elements</title>
<para>
This element accepts data but will not generate any new data. A sink element
is typically a file on disk, a soundcard, a display,... It is presented as
below:
</para>
<figure float="1" id="sec-element-sinkimg">
<title>Visualisation of a sink element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/sink-element.&magic;" format="&magic;" />
</imageobject>
</mediaobject>
</figure>
</sect2>
</sect1>
<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.
</para>
<para>
The following code example is used to get a factory that can be used to create the
mpg123 element, an mp3 decoder.
</para>
<programlisting>
GstElementFactory *factory;
factory = gst_elementfactory_find ("mpg123");
</programlisting>
<para>
Once you have the handle to the elementfactory, you can create a real element with
the following code fragment:
</para>
<programlisting>
GstElement *element;
element = gst_elementfactory_create (factory, "decoder");
</programlisting>
<para>
gst_elementfactory_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.
</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 "mpg123". This
convenient function is most widly used to create an element.
</para>
<programlisting>
GstElement *element;
element = gst_elementfactory_make ("mpg123", "decoder");
</programlisting>
<para>
An element can be destroyed with:
</para>
<programlisting>
GstElement *element;
...
gst_element_destroy (element);
</programlisting>
</sect1>
</chapter>