gstreamer/docs/manual/bins-api.xml
Stefan Kost 626cbdc8b2 cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to R...
Original commit message from CVS:
cleanup of unused and forgoten sections
fixed links from the manual and the pwg to the API docs
added more notes to README
2004-07-27 15:01:10 +00:00

205 lines
7 KiB
XML

<chapter id="chapter-bins-api">
<title>Bins</title>
<sect1 id="section-bin-create">
<title>Creating a bin</title>
<para>
Bins are created in the same way that other elements are created. ie.
using an element factory, or any of the associated convenience functions:
</para>
<programlisting>
GstElement *bin, *thread, *pipeline;
/* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal
GstBin doesn't affect plan generation */
bin = gst_element_factory_make ("bin", "mybin");
/* create a new thread, and give it a unique name */
thread = gst_element_factory_make ("thread", NULL);
/* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs,
gst_&lt;bintype&gt;_new (). these are equivalent to the gst_element_factory_make () syntax. */
pipeline = gst_pipeline_new ("pipeline_name");
</programlisting>
</sect1>
<sect1 id="section-bin-adding">
<title>Adding elements to a bin</title>
<para>
Elements are added to a bin with the following code sample:
</para>
<programlisting>
GstElement *element;
GstElement *bin;
bin = gst_bin_new ("mybin");
element = gst_element_factory_make ("mad", "decoder");
gst_bin_add (GST_BIN (bin), element);
...
</programlisting>
<para>
Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though.
They are toplevel bins and they are directly linked to the scheduler.
</para>
<para>
To get an element from the bin you can use:
</para>
<programlisting>
GstElement *element;
element = gst_bin_get_by_name (GST_BIN (bin), "decoder");
...
</programlisting>
<para>
You can see that the name of the element becomes very handy
for retrieving the element from a bin by using the element's
name. gst_bin_get_by_name () will recursively search nested bins.
</para>
<para>
To get a list of elements in a bin, use:
</para>
<programlisting>
GList *elements;
elements = gst_bin_get_list (GST_BIN (bin));
while (elements) {
GstElement *element = GST_ELEMENT (elements-&gt;data);
g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element)));
elements = g_list_next (elements);
}
...
</programlisting>
<para>
To remove an element from a bin, use:
</para>
<programlisting>
GstElement *element;
gst_bin_remove (GST_BIN (bin), element);
...
</programlisting>
<para>
To add many elements to a bin at the same time, use the gst_bin_add_many
() function. Remember to pass NULL as the last argument.
</para>
<programlisting>
GstElement *filesrc, *decoder, *audiosink;
GstBin *bin;
/* instantiate the elements and the bins... */
gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL);
</programlisting>
</sect1>
<sect1 id="section-bin-custom">
<title>Custom bins</title>
<para>
The application programmer can create custom bins packed with elements
to perform a specific task. This allows you to write an MPEG audio
decoder with just the following lines of code:
</para>
<programlisting>
/* create the mp3player element */
GstElement *mp3player = gst_element_factory_make ("mp3player", "mp3player");
/* set the source mp3 audio file */
g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL);
/* start playback */
gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING);
...
/* pause playback */
gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED);
...
/* stop */
gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL);
</programlisting>
<para>
Note that the above code assumes that the mp3player bin derives itself
from a <ulink type="http"
url="../../gstreamer/html/GstThread.html"><classname>GstThread</classname></ulink>, which begins to play as soon
as its state is set to PLAYING. Other bin types may need explicit
iteration. For more information, see <xref linkend="chapter-threads"/>.
</para>
<para>
Custom bins can be created with a plugin or an XML description. You
will find more information about creating custom bin in the Plugin
Writers Guide (FIXME ref).
</para>
</sect1>
<sect1 id="section-bin-ghostpads">
<title>Ghost pads</title>
<para>
You can see from <xref linkend="section-bin-noghost-img"/> how a bin has no pads of its own.
This is where "ghost pads" come into play.
</para>
<figure float="1" id="section-bin-noghost-img">
<title>Visualisation of a <ulink type="http"
url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink> element without ghost pads</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/bin-element-noghost.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
<para>
A ghost pad is a pad from some element in the bin that has been promoted to the bin.
This way, the bin also has a pad. The bin becomes just another element with a pad and
you can then use the bin just like any other element. This is a very important feature
for creating custom bins.
</para>
<figure float="1" id="section-bin-ghost-img">
<title>Visualisation of a <ulink type="http"
url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink> element with a ghost pad</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/bin-element-ghost.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
<para>
<xref linkend="section-bin-ghost-img"/>
is a representation of a ghost pad. The sink pad of element one is now also a pad
of the bin.
</para>
<para>
Ghost pads can actually be added to all <ulink type="http"
url="../../gstreamer/html/GstElement.html"><classname>GstElement</classname></ulink>s and not just
<ulink type="http" url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>s. Use the following code example to add a ghost pad to a bin:
</para>
<programlisting>
GstElement *bin;
GstElement *element;
element = gst_element_factory_create ("mad", "decoder");
bin = gst_bin_new ("mybin");
gst_bin_add (GST_BIN (bin), element);
gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink");
</programlisting>
<para>
In the above example, the bin now also has a pad: the pad called 'sink'
of the given element.
</para>
<para>
We can now, for example, link the source pad of a filesrc element
to the bin with:
</para>
<programlisting>
GstElement *filesrc;
filesrc = gst_element_factory_create ("filesrc", "disk_reader");
gst_element_link_pads (filesrc, "src", bin, "sink");
...
</programlisting>
</sect1>
</chapter>