}
</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
type="http"
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>
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>
<!-- 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">
* 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
* @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,
* @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),