mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-15 22:01:27 +00:00
22c66f1afb
Original commit message from CVS: + updating docs to reflect the connect->link api change, closes bug#103843
247 lines
9.2 KiB
XML
247 lines
9.2 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>
|
|
<classname>GstElement</classname> is the basic building block for the
|
|
media pipeline. All the different 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", or link 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 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.&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 source pad. A source
|
|
pad can only generate data.
|
|
</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 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.&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 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.&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 (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 terminal 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.
|
|
</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>
|
|
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 (&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 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>.
|
|
</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>
|