gstreamer/docs/manual/elements-api.xml
Thomas Vander Stichele bba6ac4b74 docs/: restructure so that common stuff is shown first
Original commit message from CVS:
* docs/Makefile.am:
* docs/manual/elements-api.xml:
restructure so that common stuff is shown first
* docs/manual/init-api.xml:
convert to examples
* docs/manual/manual.xml:
* docs/manuals.mak:
* docs/url.entities:
link to API on the website, possibly override later in build
* examples/manual/.cvsignore:
ignore more
* examples/manual/Makefile.am:
add more examples
* examples/manual/extract.pl:
error out on failure
2004-09-08 23:18:55 +00:00

202 lines
6.7 KiB
XML

<chapter id="chapter-elements-api">
<title>Elements</title>
<sect1 id="section-elements-create">
<title>Creating a GstElement</title>
<para>
The simplest way to create an element is to use
<ulink type="http"
url="&URLAPI;GstElementFactory.html#gst-element-factory-make">
<function>gst_element_factory_make</function>
</ulink>.
This function takes a factory name and an element name for the newly created
element.
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>
When you don't need the element anymore, you need to unref it using
<ulink type="http"
url="&URLAPI;GstObject.html#gst-object-unref">
<function>gst_object_unref</function></ulink>.
This decreases the reference count for the element by 1. An element has a
refcount of 1 when it gets created. An element gets destroyed completely
when the refcount is decreased to 0.
</para>
<para>
The following example &EXAFOOT; shows how to create an element named
<emphasis>source</emphasis> from the element factory named
<emphasis>fakesrc</emphasis>. It checks if the creation succeeded.
After checking, it unrefs the element.
</para>
<programlisting>
<![CDATA[
/* example-begin elementmake.c */
#include <gst/gst.h>
int
main (int argc, char *argv[])
{
GstElement *element;
gst_init (&argc, &argv);
element = gst_element_factory_make ("fakesrc", "source");
if (!element) {
g_error ("Could not create an element from 'fakesrc' factory.\n");
}
gst_object_unref (GST_OBJECT (element));
return 0;
}
/* example-end elementmake.c */
]]>
</programlisting>
<para>
<function>gst_element_factory_make</function> is actually a shorthand
for a combination of two functions.
A
<ulink type="http"
url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
object is created from a factory.
To create the element, you have to get access to a
<ulink type="http" url="&URLAPI;GstElementFactory.html">
<classname>GstElementFactory</classname></ulink>
object using a unique factory name.
This is done with
<ulink type="http"
url="&URLAPI;GstElementFactory.html#gst-element-factory-find">
<function>gst_element_factory_find</function></ulink>.
</para>
<para>
The following code fragment is used to get a factory that can be used
to create the <emphasis>fakesrc</emphasis> element, a fake data source.
</para>
<programlisting>
GstElementFactory *factory;
factory = gst_element_factory_find ("fakesrc");
</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, "source");
</programlisting>
<para>
<ulink type="http"
url="&URLAPI;GstElementFactory.html#gst-element-factory-create">
<function>gst_element_factory_create</function></ulink>
will use the element factory to create an element with the given name.
</para>
</sect1>
<sect1 id="section-elements-properties">
<title>GstElement properties</title>
<para>
A <ulink type="http" url="&URLAPI;GstElement.html">
<classname>GstElement</classname></ulink> 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 <ulink type="http" url="&URLAPI;GstElementFactory.html">
<classname>GstElement</classname></ulink> 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>
<![CDATA[
/* example-begin elementget.c */
#include <gst/gst.h>
int
main (int argc, char *argv[])
{
GstElement *element;
GValue value = { 0, }; /* initialize the GValue for g_object_get() */
gst_init (&argc, &argv);
element = gst_element_factory_make ("fakesrc", "source");
g_object_set (G_OBJECT (element), "name", "mysource", NULL);
g_value_init (&value, G_TYPE_STRING);
g_object_get_property (G_OBJECT (element), "name", &value);
g_print ("The name of the source is '%s'.\n", g_value_get_string (&value));
return 0;
}
/* example-end elementget.c */
]]>
</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> and an introduction to <ulink
url="http://le-hacker.org/papers/gobject/index.html" type="http">
The Glib Object system</ulink>.
</para>
</sect1>
<sect1 id="section-elements-signals">
<title>GstElement signals</title>
<para>
A <ulink type="http" url="&URLAPI;gstreamer/html/GstElementFactory.html">
<classname>GstElement</classname></ulink> also provides various
<classname>GObject</classname> signals that can be used as a flexible
callback mechanism.
</para>
</sect1>
<sect1 id="section-elements-factories">
<title>More about GstElementFactory</title>
<para>
We talk some more about the GstElementFactory object.
</para>
<sect2 id="section-elements-factories-details">
<title>Getting information about an element using the factory details</title>
<para>
</para>
</sect2>
<sect2 id="section-elements-factories-padtemplates">
<title>Finding out what pads an element can contain</title>
<para>
</para>
</sect2>
<sect2 id="section-elements-factories-query">
<title>Different ways of querying the factories</title>
<para>
</para>
</sect2>
</sect1>
</chapter>