Commit 1a6f61a1 authored by Tim-Philipp Müller's avatar Tim-Philipp Müller

docs: mention that it's necessary to set the state of elements added to an already-running pipeline

https://bugzilla.gnome.org/show_bug.cgi?id=641631
parent 654a9484
......@@ -135,6 +135,10 @@ main (int argc,
[..]
}
</programlisting>
<para>
(This is a silly example of course, there already exists a much more
powerful and versatile custom bin like this: the playbin2 element.)
</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 <ulink
......@@ -143,10 +147,31 @@ main (int argc,
Writers Guide</ulink>.
</para>
<para>
Examples of such custom bins are the playbin and decodebin elements from<ulink
Examples of such custom bins are the playbin2 and uridecodebin elements from<ulink
type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html">
gst-plugins-base</ulink>.
</para>
</sect1>
<sect1 id="section-bin-state-change-handling">
<title>Bins manage states of their children</title>
<para>
Bins manage the state of all elements contained in them. If you set
a bin (or a pipeline, which is a special top-level type of bin) to
a certain target state using <function>gst_element_set_state ()</function>,
it will make sure all elements contained within it will also be set
to this state. This means it's usually only necessary to set the state
of the top-level pipeline to start up the pipeline or shut it down.
</para>
<para>
Note, however, that if elements are added to a bin or pipeline that's
already running, , e.g. from within a "pad-added" or "new-decoded-pad"
signal callback, its state will not automatically be brought in line with
the current state or target state of the bin or pipeline it was added to.
Instead, you have to need to set it to the desired target state yourself
using <function>gst_element_set_state ()</function> or
<function>gst_element_sync_state_with_parent ()</function> when adding
elements to an already-running pipeline.
</para>
</sect1>
</chapter>
......@@ -554,5 +554,16 @@ main (int argc,
url="&URLAPI;GstBus.html"><classname>GstBus</classname></ulink>. See
<xref linkend="chapter-bus"/> for details.
</para>
<para>
When you set a bin or pipeline to a certain target state, it will usually
propagate the state change to all elements within the bin or pipeline
automatically, so it's usually only necessary to set the state of the
top-level pipeline to start up the pipeline or shut it down. However,
when adding elements dynamically to an already-running pipeline, e.g.
from within a "pad-added" or "new-decoded-pad" signal callback, you
need to set it to the desired target state yourself using
<function>gst_element_set_state ()</function> or
<function>gst_element_sync_state_with_parent ()</function>.
</para>
</sect1>
</chapter>
......@@ -118,6 +118,14 @@ main (int argc,
<!-- example-begin pad.c d -->
}
<!-- example-end pad.c d --></programlisting>
<para>
It is not uncommon to add elements to the pipeline only from within
the "pad-added" or "new-decoded-pad" callback. If you do this, don't
forget to set the state of the newly-added elements to the target
state of the pipeline using
<function>gst_element_set_state ()</function> or
<function>gst_element_sync_state_with_parent ()</function>.
</para>
</sect2>
<sect2 id="section-pads-request">
......
......@@ -1194,6 +1194,14 @@ had_parent:
* If the element's pads are linked to other pads, the pads will be unlinked
* before the element is added to the bin.
*
* <note>
* When you add an element to an already-running pipeline, you will have to
* take care to set the state of the newly-added element to the desired
* state (usually PLAYING or PAUSED, same you set the pipeline to originally)
* with gst_element_set_state(), or use gst_element_sync_state_with_parent().
* The bin or pipeline will not take care of this for you.
* </note>
*
* MT safe.
*
* Returns: TRUE if the element could be added, FALSE if
......
......@@ -202,7 +202,11 @@ gst_element_class_init (GstElementClass * klass)
* @gstelement: the object which received the signal
* @new_pad: the pad that has been added
*
* a new #GstPad has been added to the element.
* a new #GstPad has been added to the element. Note that this signal will
* usually be emitted from the context of the streaming thread. Also keep in
* mind that if you add new elements to the pipeline in the signal handler
* you will need to set them to the desired target state with
* gst_element_set() or gst_element_sync_state_with_parent().
*/
gst_element_signals[PAD_ADDED] =
g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
......@@ -224,6 +228,8 @@ gst_element_class_init (GstElementClass * klass)
* @gstelement: the object which received the signal
*
* This signals that the element will not generate more dynamic pads.
* Note that this signal will usually be emitted from the context of
* the streaming thread.
*/
gst_element_signals[NO_MORE_PADS] =
g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment