diff options
Diffstat (limited to 'gst/gstbin.c')
| -rw-r--r-- | gst/gstbin.c | 155 |
1 files changed, 61 insertions, 94 deletions
diff --git a/gst/gstbin.c b/gst/gstbin.c index 9e6708930..3c0b2da38 100644 --- a/gst/gstbin.c +++ b/gst/gstbin.c @@ -25,6 +25,7 @@ /** * SECTION:gstbin + * @title: GstBin * @short_description: Base class and element that can contain other elements * * #GstBin is an element that can contain other #GstElement, allowing them to be @@ -55,97 +56,67 @@ * the bin. Likewise the #GstBin::element-removed signal is fired whenever an * element is removed from the bin. * - * <refsect2><title>Notes</title> - * <para> + * ## Notes + * * A #GstBin internally intercepts every #GstMessage posted by its children and * implements the following default behaviour for each of them: - * <variablelist> - * <varlistentry> - * <term>GST_MESSAGE_EOS</term> - * <listitem><para>This message is only posted by sinks in the PLAYING - * state. If all sinks posted the EOS message, this bin will post and EOS - * message upwards.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_MESSAGE_SEGMENT_START</term> - * <listitem><para>just collected and never forwarded upwards. - * The messages are used to decide when all elements have completed playback - * of their segment.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_MESSAGE_SEGMENT_DONE</term> - * <listitem><para> Is posted by #GstBin when all elements that posted - * a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_MESSAGE_DURATION_CHANGED</term> - * <listitem><para> Is posted by an element that detected a change - * in the stream duration. The default bin behaviour is to clear any - * cached duration values so that the next duration query will perform - * a full duration recalculation. The duration change is posted to the - * application so that it can refetch the new duration with a duration - * query. Note that these messages can be posted before the bin is - * prerolled, in which case the duration query might fail. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_MESSAGE_CLOCK_LOST</term> - * <listitem><para> This message is posted by an element when it - * can no longer provide a clock. The default bin behaviour is to - * check if the lost clock was the one provided by the bin. If so and - * the bin is currently in the PLAYING state, the message is forwarded to - * the bin parent. - * This message is also generated when a clock provider is removed from - * the bin. If this message is received by the application, it should - * PAUSE the pipeline and set it back to PLAYING to force a new clock - * distribution. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_MESSAGE_CLOCK_PROVIDE</term> - * <listitem><para> This message is generated when an element - * can provide a clock. This mostly happens when a new clock - * provider is added to the bin. The default behaviour of the bin is to - * mark the currently selected clock as dirty, which will perform a clock - * recalculation the next time the bin is asked to provide a clock. - * This message is never sent tot the application but is forwarded to - * the parent of the bin. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>OTHERS</term> - * <listitem><para> posted upwards.</para></listitem> - * </varlistentry> - * </variablelist> * + * * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING + * state. If all sinks posted the EOS message, this bin will post and EOS + * message upwards. + * + * * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. + * The messages are used to decide when all elements have completed playback + * of their segment. + * + * * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted + * a SEGMENT_START have posted a SEGMENT_DONE. + * + * * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change + * in the stream duration. The default bin behaviour is to clear any + * cached duration values so that the next duration query will perform + * a full duration recalculation. The duration change is posted to the + * application so that it can refetch the new duration with a duration + * query. Note that these messages can be posted before the bin is + * prerolled, in which case the duration query might fail. + * + * * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it + * can no longer provide a clock. The default bin behaviour is to + * check if the lost clock was the one provided by the bin. If so and + * the bin is currently in the PLAYING state, the message is forwarded to + * the bin parent. + * This message is also generated when a clock provider is removed from + * the bin. If this message is received by the application, it should + * PAUSE the pipeline and set it back to PLAYING to force a new clock + * distribution. + * + * * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element + * can provide a clock. This mostly happens when a new clock + * provider is added to the bin. The default behaviour of the bin is to + * mark the currently selected clock as dirty, which will perform a clock + * recalculation the next time the bin is asked to provide a clock. + * This message is never sent tot the application but is forwarded to + * the parent of the bin. + * + * * OTHERS: posted upwards. * * A #GstBin implements the following default behaviour for answering to a * #GstQuery: - * <variablelist> - * <varlistentry> - * <term>GST_QUERY_DURATION</term> - * <listitem><para>If the query has been asked before with the same format - * and the bin is a toplevel bin (ie. has no parent), - * use the cached previous value. If no previous value was cached, the - * query is sent to all sink elements in the bin and the MAXIMUM of all - * values is returned. If the bin is a toplevel bin the value is cached. - * If no sinks are available in the bin, the query fails. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>GST_QUERY_POSITION</term> - * <listitem><para>The query is sent to all sink elements in the bin and the - * MAXIMUM of all values is returned. If no sinks are available in the bin, - * the query fails. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>OTHERS</term> - * <listitem><para>the query is forwarded to all sink elements, the result - * of the first sink that answers the query successfully is returned. If no - * sink is in the bin, the query fails.</para></listitem> - * </varlistentry> - * </variablelist> + * + * * GST_QUERY_DURATION:If the query has been asked before with the same format + * and the bin is a toplevel bin (ie. has no parent), + * use the cached previous value. If no previous value was cached, the + * query is sent to all sink elements in the bin and the MAXIMUM of all + * values is returned. If the bin is a toplevel bin the value is cached. + * If no sinks are available in the bin, the query fails. + * + * * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the + * MAXIMUM of all values is returned. If no sinks are available in the bin, + * the query fails. + * + * * OTHERS:the query is forwarded to all sink elements, the result + * of the first sink that answers the query successfully is returned. If no + * sink is in the bin, the query fails. * * A #GstBin will by default forward any event sent to it to all sink * (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements @@ -154,8 +125,6 @@ * is returned. If no elements of the required type are in the bin, the event * handler will return %TRUE. * - * </para> - * </refsect2> */ #include "gst_private.h" @@ -1527,13 +1496,11 @@ gst_bin_deep_element_removed_func (GstBin * bin, GstBin * sub_bin, * 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> + * > 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. * * MT safe. * |