mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-04 13:45:52 +00:00
228 lines
8.4 KiB
XML
228 lines
8.4 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>
|
|
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 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.
|
|
</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.
|
|
</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 (&value, G_TYPE_STRING);
|
|
g_object_get_property (G_OBJECT (element), "name", &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 perticular 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.
|
|
</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
|
|
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>
|