Menu
▾
▴
[gst-cvs] gstreamer: docs: add more docs around GstState and GstStateChange
|
From: <en...@ke...> - 2009-12-14 13:15:09
|
Module: gstreamer Branch: master Commit: 790e5d10c875452dab85638aabd1a8cd64932137 URL: http://cgit.freedesktop.org/gstreamer/gstreamer/commit/?id=790e5d10c875452dab85638aabd1a8cd64932137 Author: Stefan Kost <en...@us...> Date: Mon Dec 14 15:11:42 2009 +0200 docs: add more docs around GstState and GstStateChange Take reviewed docs from docs/design/part-state to have that more prominent inside the api docs. Add a few sentences to link things better together. --- gst/gstelement.c | 8 ++-- gst/gstelement.h | 154 +++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 140 insertions(+), 22 deletions(-) diff --git a/gst/gstelement.c b/gst/gstelement.c index 80baa04..7dd6afe 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -56,8 +56,8 @@ * * Each element has a state (see #GstState). You can get and set the state * of an element with gst_element_get_state() and gst_element_set_state(). - * To get a string representation of a #GstState, use - * gst_element_state_get_name(). + * Setting a state triggers a #GstStateChange. To get a string representation + * of a #GstState, use gst_element_state_get_name(). * * You can get and set a #GstClock on an element using gst_element_get_clock() * and gst_element_set_clock(). @@ -2063,8 +2063,8 @@ interrupted: * * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element * successfully changed its state but is not able to provide data yet. - * This mostly happens for live sources that only produce data in the PLAYING - * state. While the state change return is equivalent to + * This mostly happens for live sources that only produce data in + * %GST_STATE_PLAYING. While the state change return is equivalent to * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that * some sink elements might not be able to complete their state change because * an element is not producing data to complete the preroll. When setting the diff --git a/gst/gstelement.h b/gst/gstelement.h index d842edd..c60ae8d 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -31,13 +31,17 @@ typedef struct _GstElementClass GstElementClass; /* gstmessage.h needs State */ /** * GstState: - * @GST_STATE_VOID_PENDING : no pending state. - * @GST_STATE_NULL : the NULL state or initial state of an element - * @GST_STATE_READY : the element is ready to go to PAUSED - * @GST_STATE_PAUSED : the element is PAUSED - * @GST_STATE_PLAYING : the element is PLAYING - * - * The posible states an element can be in. + * @GST_STATE_VOID_PENDING: no pending state. + * @GST_STATE_NULL : the NULL state or initial state of an element. + * @GST_STATE_READY : the element is ready to go to PAUSED. + * @GST_STATE_PAUSED : the element is PAUSED, it is ready to accept and + * process data. Sink elements however only accept one + * buffer and then block. + * @GST_STATE_PLAYING : the element is PLAYING, the #GstClock is running and + * the data is flowing. + * + * The posible states an element can be in. States can be chaged using + * gst_element_set_state() and checked using gst_element_get_state(). */ typedef enum { GST_STATE_VOID_PENDING = 0, @@ -78,8 +82,8 @@ G_BEGIN_DECLS * @GST_STATE_CHANGE_SUCCESS : the state change succeeded * @GST_STATE_CHANGE_ASYNC : the state change will happen asynchronously * @GST_STATE_CHANGE_NO_PREROLL: the state change succeeded but the element - * cannot produce data in PAUSED. This typically - * happens with live sources. + * cannot produce data in %GST_STATE_PAUSED. + * This typically happens with live sources. * * The possible return values from a state change function. Only * @GST_STATE_CHANGE_FAILURE is a real failure. @@ -173,15 +177,129 @@ typedef enum { /** * GstStateChange: - * @GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY - * @GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED - * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING - * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED - * @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY - * @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL - * - * The different (interesting) state changes that are passed to the - * state change functions of elements. + * @GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY. + * <itemizedlist> + * <listitem><para> + * The element must check if the resources it needs are available. Device + * sinks and -sources typically try to probe the device to constrain their + * caps. + * </para></listitem> + * <listitem><para> + * The element opens the device (in case feature need to be probed). + * </para></listitem> + * </itemizedlist> + * @GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED. + * <itemizedlist> + * <listitem><para> + * The element pads are activated in order to receive data in PAUSED. + * Streaming threads are started. + * </para></listitem> + * <listitem><para> + * Some elements might need to return ASYNC and complete the state change + * when they have enough information. It is a requirement for sinks to + * return ASYNC and complete the state change when they receive the first + * buffer or EOS event (preroll). Sinks also block the dataflow when in + * PAUSED. + * </para></listitem> + * <listitem><para> + * A pipeline resets the running_time to 0. + * </para></listitem> + * <listitem><para> + * Live sources return NO_PREROLL and don't generate data. + * </para></listitem> + * </itemizedlist> + * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING. + * <itemizedlist> + * <listitem><para> + * Most elements ignore this state change. + * </para></listitem> + * <listitem><para> + * The pipeline selects a clock and distributes this to all the children + * before setting them to PLAYING. This means that it is only alowed to + * synchronize on the clock in the PLAYING state. + * </para></listitem> + * <listitem><para> + * The pipeline uses the clock and the running_time to calculate the + * base_time. The base_time is distributed to all children when performing + * the state change. + * </para></listitem> + * <listitem><para> + * Sink elements stop blocking on the preroll buffer or event and start + * rendering the data. + * </para></listitem> + * <listitem><para> + * Sinks can post the EOS message in the PLAYING state. It is not allowed to + * post EOS when not in the PLAYING state. + * </para></listitem> + * <listitem><para> + * While streaming in PAUSED or PLAYING elements can create and remove + * sometimes pads. + * </para></listitem> + * <listitem><para> + * Live sources start generating data and return SUCCESS. + * </para></listitem> + * </itemizedlist> + * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. + * <itemizedlist> + * <listitem><para> + * Most elements ignore this state change. + * </para></listitem> + * <listitem><para> + * The pipeline calculates the running_time based on the last selected clock + * and the base_time. It stores this information to continue playback when + * going back to the PLAYING state. + * </para></listitem> + * <listitem><para> + * Sinks unblock any clock wait calls. + * </para></listitem> + * <listitem><para> + * When a sink does not have a pending buffer to play, it returns ASYNC from + * this state change and completes the state change when it receives a new + * buffer or an EOS event. + * </para></listitem> + * <listitem><para> + * Any queued EOS messages are removed since they will be reposted when going + * back to the PLAYING state. The EOS messages are queued in GstBins. + * </para></listitem> + * <listitem><para> + * Live sources stop generating data and return NO_PREROLL. + * </para></listitem> + * </itemizedlist> + * @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. + * <itemizedlist> + * <listitem><para> + * Sinks unblock any waits in the preroll. + * </para></listitem> + * <listitem><para> + * Elements unblock any waits on devices + * </para></listitem> + * <listitem><para> + * Chain or get_range functions return WRONG_STATE. + * </para></listitem> + * <listitem><para> + * The element pads are deactivated so that streaming becomes impossible and + * all streaming threads are stopped. + * </para></listitem> + * <listitem><para> + * The sink forgets all negotiated formats + * </para></listitem> + * <listitem><para> + * Elements remove all sometimes pads + * </para></listitem> + * </itemizedlist> + * @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. + * <itemizedlist> + * <listitem><para> + * Elements close devices + * </para></listitem> + * <listitem><para> + * Elements reset any internal state. + * </para></listitem> + * </itemizedlist> + * + * These are the different state changes an element goes through. + * %GST_STATE_NULL ⇒ %GST_STATE_PLAYING is called an upwards state change + * and %GST_STATE_PLAYING ⇒ %GST_STATE_NULL a downwards state change. */ typedef enum /*< flags=0 >*/ { |