gstreamer/docs/manual/elements.xml
Andy Wingo b214d35eed commit to make gstreamer follow the gtk function/macro naming conventions:
Original commit message from CVS:
commit to make gstreamer follow the gtk function/macro naming conventions:

GstPadTemplate <-> gst_pad_template <-> GST_PAD_TEMPLATE

and the same for *factory and typefind.
2002-04-11 20:35:18 +00:00

154 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> 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.
</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>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.
</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.
</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 (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;" />
</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.
</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.
</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
'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:
</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.
</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.
</para>
<programlisting>
GstElement *element;
element = gst_element_factory_make ("mad", "decoder");
</programlisting>
<para>
An element can be destroyed with: FIXME talk about refcounting
</para>
<programlisting>
GstElement *element;
...
gst_element_destroy (element);
</programlisting>
</sect1>
</chapter>