mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-04 23:46:43 +00:00
08bb61fd3c
Original commit message from CVS: Small manual changes. Added a section about autoplugging.
145 lines
5.5 KiB
Text
145 lines
5.5 KiB
Text
<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>
|
|
<graphic fileref="images/src-element" format="png"></graphic>
|
|
</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>
|
|
<graphic fileref="images/filter-element" format="png"></graphic>
|
|
</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>
|
|
<graphic fileref="images/filter-element-multi" format="png"></graphic>
|
|
</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>
|
|
<graphic fileref="images/sink-element" format="png"></graphic>
|
|
</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>
|