From a56bdf2768a740b17484f356503030a931e11477 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 10 Nov 2005 11:17:26 +0000 Subject: [PATCH] Fix docs, move some STATE macros to private. Original commit message from CVS: * docs/gst/gstreamer-sections.txt: * gst/gstelement.c: * gst/gstelement.h: Fix docs, move some STATE macros to private. --- ChangeLog | 7 ++ docs/gst/gstreamer-sections.txt | 27 +++--- gst/gstelement.c | 49 ++++++---- gst/gstelement.h | 158 ++++++++++++++++++++++---------- 4 files changed, 160 insertions(+), 81 deletions(-) diff --git a/ChangeLog b/ChangeLog index dea19bc91a..4b2eca8fec 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2005-11-10 Wim Taymans + + * docs/gst/gstreamer-sections.txt: + * gst/gstelement.c: + * gst/gstelement.h: + Fix docs, move some STATE macros to private. + 2005-11-10 Wim Taymans * check/gst/gstghostpad.c: (GST_START_TEST), (gst_ghost_pad_suite): diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index d6149e6657..efded6768e 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -422,30 +422,24 @@ GST_PADDING_INIT gstelement GstElement GstElement +GstElementClass GstElementFlags GstState GstStateChange GstStateChangeReturn GST_STATE -GST_STATE_BROADCAST -GST_STATE_GET_COND -GST_STATE_GET_LOCK GST_STATE_GET_NEXT -GST_STATE_LOCK -GST_STATE_LOCK_FULL GST_STATE_NEXT GST_STATE_PENDING GST_STATE_RETURN -GST_STATE_SIGNAL -GST_STATE_TIMED_WAIT GST_STATE_TRANSITION GST_STATE_TRANSITION_CURRENT GST_STATE_TRANSITION_NEXT -GST_STATE_TRYLOCK -GST_STATE_UNLOCK -GST_STATE_UNLOCK_FULL -GST_STATE_WAIT + +GST_STATE_GET_LOCK +GST_STATE_GET_COND + GST_ELEMENT_NAME GST_ELEMENT_PARENT GST_ELEMENT_BUS @@ -522,7 +516,6 @@ gst_element_unlink gst_element_unlink_many gst_element_unlink_pads -GstElementClass GST_ELEMENT GST_IS_ELEMENT GST_ELEMENT_CLASS @@ -535,6 +528,16 @@ GST_TYPE_STATE GST_TYPE_STATE_CHANGE GST_TYPE_STATE_CHANGE_RETURN +GST_STATE_LOCK +GST_STATE_TRYLOCK +GST_STATE_UNLOCK +GST_STATE_UNLOCK_FULL +GST_STATE_LOCK_FULL +GST_STATE_WAIT +GST_STATE_TIMED_WAIT +GST_STATE_SIGNAL +GST_STATE_BROADCAST + gst_element_get_type gst_element_flags_get_type gst_state_get_type diff --git a/gst/gstelement.c b/gst/gstelement.c index 85d7bd769d..daee12d4fb 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -29,14 +29,14 @@ * used in a GStreamer pipeline. As such, it is not a functional entity, and * cannot do anything when placed in a pipeline. * - * The name of a GstElement can be get with gst_element_get_name() and set with + * The name of a #GstElement can be get with gst_element_get_name() and set with * gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the * core when using the appropriate locking. Do not use this in plug-ins or * applications in order to retain ABI compatibility. * * All elements have pads (of the type #GstPad). These pads link to pads on - * other elements. Buffers flow between these linked pads. - * A GstElement has a GList of #GstPad structures for all their input (or sink) + * other elements. #GstBuffer flow between these linked pads. + * A #GstElement has a #GList of #GstPad structures for all their input (or sink) * and output (or source) pads. * Core and plug-in writers can add and remove pads with gst_element_add_pad() * and gst_element_remove_pad(). @@ -332,7 +332,8 @@ gst_element_requires_clock (GstElement * element) * gst_element_provides_clock: * @element: a #GstElement to query * - * Query if the element provides a clock. + * Query if the element provides a clock. A #GstClock provided by an + * element can be used as the global #GstClock for the pipeline. * * Returns: TRUE if the element provides a clock * @@ -506,7 +507,7 @@ gst_element_is_indexable (GstElement * element) * @element: a #GstElement. * @index: a #GstIndex. * - * Set the specified GstIndex on the element. The refcount of the index + * Set @index on the element. The refcount of the index * will be increased, any previously set index is unreffed. * * MT safe. @@ -567,7 +568,8 @@ gst_element_get_index (GstElement * element) * The pad and the element should be unlocked when calling this function. * * Returns: TRUE if the pad could be added. This function can fail when - * passing bad arguments or when a pad with the same name already existed. + * a pad with the same name already existed or the pad already had another + * parent. * * MT safe. */ @@ -660,8 +662,7 @@ no_direction: * referenced elsewhere. * * Returns: TRUE if the pad could be removed. Can return FALSE if the - * pad is not belonging to the provided element or when wrong parameters - * are passed to this function. + * pad is not belonging to the provided element. * * MT safe. */ @@ -740,7 +741,7 @@ not_our_pad: * * Use this function to signal that the element does not expect any more pads * to show up in the current pipeline. This function should be called whenever - * pads have been added by the element itself. Elements with GST_PAD_SOMETIMES + * pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES * pad templates use this in combination with autopluggers to figure out that * the element is done initializing its pads. * @@ -1166,7 +1167,7 @@ wrong_direction: * Sends an event to an element. If the element doesn't * implement an event handler, the event will be forwarded * to a random sink pad. This function takes owership of the - * provided event so you should _ref it if you want to reuse + * provided event so you should gst_event_ref() it if you want to reuse * the event after this call. * * Returns: TRUE if the event was handled. @@ -1287,7 +1288,7 @@ gst_element_get_query_types (GstElement * element) * @query: the #GstQuery. * * Performs a query on the given element. If the format is set - * to GST_FORMAT_DEFAULT and this function returns TRUE, the + * to #GST_FORMAT_DEFAULT and this function returns TRUE, the * format pointer will hold the default format. * For element that don't implement a query handler, this function * forwards the query to a random usable sinkpad of this element. @@ -1729,15 +1730,24 @@ interrupted: * specified timeout value for the state change to complete. * If the element completes the state change or goes into * an error, this function returns immediatly with a return value of - * GST_STATE_CHANGE_SUCCESS or GST_STATE_CHANGE_FAILURE respectively. + * #GST_STATE_CHANGE_SUCCESS or #GST_STATE_CHANGE_FAILURE respectively. * - * For elements that did not return ASYNC, this function returns the - * current and pending state immediatly. + * For elements that did not return #GST_STATE_CHANGE_ASYNC, this function + * returns the current and pending state immediatly. * - * Returns: GST_STATE_CHANGE_SUCCESS if the element has no more pending state and - * the last state change succeeded, GST_STATE_CHANGE_ASYNC + * 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 #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 element to playing, the preroll + * will complete and playback will start. + * + * Returns: #GST_STATE_CHANGE_SUCCESS if the element has no more pending state and + * the last state change succeeded, #GST_STATE_CHANGE_ASYNC * if the element is still performing a state change or - * GST_STATE_CHANGE_FAILURE if the last state change failed. + * #GST_STATE_CHANGE_FAILURE if the last state change failed. * * MT safe. */ @@ -1994,8 +2004,9 @@ nothing_lost: * requested state by going through all the intermediary states and calling * the class's state change function for each. * - * This function can return GST_STATE_CHANGE_ASYNC, in which case the - * element will perform the remainder of the state change asynchronously. + * This function can return #GST_STATE_CHANGE_ASYNC, in which case the + * element will perform the remainder of the state change asynchronously in + * another thread. * An application can use gst_element_get_state() to wait for the completion * of the state change or it can wait for a state change message on the bus. * diff --git a/gst/gstelement.h b/gst/gstelement.h index c5a7633696..43af955bab 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -40,8 +40,7 @@ typedef struct _GstElementClass GstElementClass; * The posible states an element can be in. */ typedef enum { - GST_STATE_VOID_PENDING = 0, /* used for GstElement->pending_state when - there is no pending state */ + GST_STATE_VOID_PENDING = 0, GST_STATE_NULL = 1, GST_STATE_READY = 2, GST_STATE_PAUSED = 3, @@ -95,44 +94,44 @@ typedef enum { /** * GST_STATE: - * @obj: Element to return state for. + * @elem: a #GstElement to return state for. * - * This macro returns the current state of the element. + * This macro returns the current #GstState of the element. */ -#define GST_STATE(obj) (GST_ELEMENT_CAST(obj)->current_state) +#define GST_STATE(elem) (GST_ELEMENT_CAST(elem)->current_state) /** * GST_STATE_NEXT: - * @obj: Element to return the next state for. + * @elem: a #GstElement to return the next state for. * - * This macro returns the next state of the element. + * This macro returns the next #GstState of the element. */ -#define GST_STATE_NEXT(obj) (GST_ELEMENT_CAST(obj)->next_state) +#define GST_STATE_NEXT(elem) (GST_ELEMENT_CAST(elem)->next_state) /** * GST_STATE_PENDING: - * @obj: Element to return the pending state for. + * @elem: a #GstElement to return the pending state for. * - * This macro returns the currently pending state of the element. + * This macro returns the currently pending #GstState of the element. */ -#define GST_STATE_PENDING(obj) (GST_ELEMENT_CAST(obj)->pending_state) +#define GST_STATE_PENDING(elem) (GST_ELEMENT_CAST(elem)->pending_state) /** * GST_STATE_RETURN: - * @obj: Element to return the last state result for. + * @elem: a #GstElement to return the last state result for. * - * This macro returns the last state change return value. + * This macro returns the last #GstStateChangeReturn value. */ -#define GST_STATE_RETURN(obj) (GST_ELEMENT_CAST(obj)->last_return) +#define GST_STATE_RETURN(elem) (GST_ELEMENT_CAST(elem)->last_return) #define __GST_SIGN(val) ((val) < 0 ? -1 : ((val) > 0 ? 1 : 0)) /** * GST_STATE_GET_NEXT: - * @cur: A starting state - * @pending: A target state + * @cur: A starting #GstState + * @pending: A target #GstState * - * Given a current state and a target state, calculate the next (intermediate) - * state. + * Given a current state @cur and a target state @pending, calculate the next (intermediate) + * #GstState. */ #define GST_STATE_GET_NEXT(cur,pending) ((cur) + __GST_SIGN ((gint)(pending) - (gint)(cur))) /** @@ -140,22 +139,22 @@ typedef enum { * @cur: A current state * @next: A next state * - * Given a current state and a next state, calculate the associated - * state transition. + * Given a current state @cur and a next state @next, calculate the associated + * #GstStateChange transition. */ #define GST_STATE_TRANSITION(cur,next) (((cur)<<3)|(next)) /** * GST_STATE_TRANSITION_CURRENT: - * @trans: A state transition + * @trans: A #GstStateChange * - * Given a state transition, extract the current state. + * Given a state transition @trans, extract the current #GstState. */ #define GST_STATE_TRANSITION_CURRENT(trans) ((trans)>>3) /** * GST_STATE_TRANSITION_NEXT: - * @trans: A state transition + * @trans: A #GstStateChange * - * Given a state transition, extract the next state. + * Given a state transition @trans, extract the next #GstState. */ #define GST_STATE_TRANSITION_NEXT(trans) ((trans)&0x7) @@ -202,59 +201,59 @@ typedef enum /** * GST_ELEMENT_IS_LOCKED_STATE: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Check if the element is in the locked state and therefore will ignore state * changes from its parent object. */ -#define GST_ELEMENT_IS_LOCKED_STATE(obj) (GST_OBJECT_FLAG_IS_SET(obj,GST_ELEMENT_LOCKED_STATE)) +#define GST_ELEMENT_IS_LOCKED_STATE(elem) (GST_OBJECT_FLAG_IS_SET(elem,GST_ELEMENT_LOCKED_STATE)) /** * GST_ELEMENT_NAME: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Gets the name of this element. Use only in core as this is not * ABI-compatible. Others use gst_element_get_name() */ -#define GST_ELEMENT_NAME(obj) (GST_OBJECT_NAME(obj)) +#define GST_ELEMENT_NAME(elem) (GST_OBJECT_NAME(elem)) /** * GST_ELEMENT_PARENT: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Get the parent object of this element. */ -#define GST_ELEMENT_PARENT(obj) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj))) +#define GST_ELEMENT_PARENT(elem) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(elem))) /** * GST_ELEMENT_BUS: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Get the message bus of this element. */ -#define GST_ELEMENT_BUS(obj) (GST_ELEMENT_CAST(obj)->bus) +#define GST_ELEMENT_BUS(elem) (GST_ELEMENT_CAST(elem)->bus) /** * GST_ELEMENT_CLOCK: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Get the clock of this element */ -#define GST_ELEMENT_CLOCK(obj) (GST_ELEMENT_CAST(obj)->clock) +#define GST_ELEMENT_CLOCK(elem) (GST_ELEMENT_CAST(elem)->clock) /** * GST_ELEMENT_PADS: - * @obj: A #GstElement to query + * @elem: A #GstElement to query * * Get the pads of this elements. */ -#define GST_ELEMENT_PADS(obj) (GST_ELEMENT_CAST(obj)->pads) +#define GST_ELEMENT_PADS(elem) (GST_ELEMENT_CAST(elem)->pads) /** * GST_ELEMENT_ERROR: * @el: the element that throws the error - * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError) - * @code: error code defined for that domain (see #GstError) + * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstGError) + * @code: error code defined for that domain (see #GstGError) * @text: the message to display (format string and args enclosed in parentheses) * @debug: debugging information for the message (format string and args @@ -280,8 +279,8 @@ G_STMT_START { \ /** * GST_ELEMENT_WARNING: * @el: the element that throws the error - * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError) - * @code: error code defined for that domain (see #GstError) + * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstGError) + * @code: error code defined for that domain (see #GstGError) * @text: the message to display (format string and args enclosed in parentheses) * @debug: debugging information for the message (format string and args @@ -305,22 +304,28 @@ G_STMT_START { \ } G_STMT_END /* the state change mutexes and conds */ -#define GST_STATE_GET_LOCK(elem) (GST_ELEMENT_CAST(elem)->state_lock) - /** - * GST_STATE_LOCK: - * @elem: the #GstElement to take the state lock on + * GST_STATE_GET_LOCK: + * @elem: a #GstElement * - * Takes the state lock on the element. - * This function is used by the core. It is taken while getting or setting + * Get a reference to the state lock of @elem. + * This lock is used by the core. It is taken while getting or setting * the state, during state changes, and while finalizing. */ +#define GST_STATE_GET_LOCK(elem) (GST_ELEMENT_CAST(elem)->state_lock) +/** + * GST_STATE_GET_COND: + * @elem: a #GstElement + * + * Get the conditional used to signal the completion of a state change. + */ +#define GST_STATE_GET_COND(elem) (GST_ELEMENT_CAST(elem)->state_cond) + #define GST_STATE_LOCK(elem) g_static_rec_mutex_lock(GST_STATE_GET_LOCK(elem)) #define GST_STATE_TRYLOCK(elem) g_static_rec_mutex_trylock(GST_STATE_GET_LOCK(elem)) #define GST_STATE_UNLOCK(elem) g_static_rec_mutex_unlock(GST_STATE_GET_LOCK(elem)) #define GST_STATE_UNLOCK_FULL(elem) g_static_rec_mutex_unlock_full(GST_STATE_GET_LOCK(elem)) #define GST_STATE_LOCK_FULL(elem,t) g_static_rec_mutex_lock_full(GST_STATE_GET_LOCK(elem), t) -#define GST_STATE_GET_COND(elem) (GST_ELEMENT_CAST(elem)->state_cond) #define GST_STATE_WAIT(elem) g_cond_wait (GST_STATE_GET_COND (elem), \ GST_GET_LOCK (elem)) #define GST_STATE_TIMED_WAIT(elem, timeval) g_cond_timed_wait (GST_STATE_GET_COND (elem), \ @@ -328,13 +333,42 @@ G_STMT_START { \ #define GST_STATE_SIGNAL(elem) g_cond_signal (GST_STATE_GET_COND (elem)); #define GST_STATE_BROADCAST(elem) g_cond_broadcast (GST_STATE_GET_COND (elem)); +/** + * GstElement: + * @state_lock: Used to serialize execution of gst_element_set_state() + * @state_cond: Used to signal completion of a state change + * @state_cookie: Used to detect concurrent execution of gst_element_set_state() and + * gst_element_get_state() + * @current_state: the current state of an element + * @next_state: the next state of an element, can be #GST_STATE_VOID_PENDING if the + * element is in the correct state. + * @pending_state: the final state the element should go to, can be #GST_STATE_VOID_PENDING + * if the element is in the correct state + * @last_return: the last return value of an element state change + * @bus: the bus of the element. This bus is provided to the element by the parent element + * or the application. A #GstPipeline has a bus of its own. + * @clock: the clock of the element. This clock is usually provided by to the element by + * the toplevel #GstPipeline. + * @base_time: the time of the clock right before the element is set to PLAYING. Subtracting + * @base_time from the current clock time in the PLAYING state will yield the stream time. + * @numpads: number of pads of the element, includes both source and sink pads. + * @pads: list of pads + * @numsrcpads: number of source pads of the element. + * @srcpads: list of source pads + * @numsinkpads: number of sink pads of the element. + * @sinkpads: list of sink pads + * @pads_cookie: updated whenever the a pad is added or removed + * + * GStreamer element abstract base class. + */ struct _GstElement { GstObject object; /*< public >*/ /* with LOCK */ - /* element state */ GStaticRecMutex *state_lock; + + /* element state */ GCond *state_cond; guint32 state_cookie; GstState current_state; @@ -342,7 +376,6 @@ struct _GstElement GstState pending_state; GstStateChangeReturn last_return; - /*< public >*/ /* with LOCK */ GstBus *bus; /* allocated clock */ @@ -363,6 +396,31 @@ struct _GstElement gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstElementClass: + * @parent_class: the parent class structure + * @details: #GstElementDetails for elements of this class + * @elementfactory: the #GstElementFactory that creates these elements + * @padtemplates: a #GList of #GstPadTemplate + * @numpadtemplates: the number of padtemplates + * @pad_templ_cookie: changed whenever the padtemplates change + * @request_new_pad: called when a new pad is requested + * @release_pad: called when a request pad is to be released + * @get_state: get the state of the element + * @set_state: set a new state on the element + * @change_state: called by @set_state to perform an incremental state change + * @set_bus: set a #GstBus on the element + * @provide_clock: gets the #GstClock provided by the element + * @set_clock: set the #GstClock on the element + * @get_index: set a #GstIndex on the element + * @set_index: get the #GstIndex of an element + * @send_event: send a #GstEvent to the element + * @get_query_types: get the supported #GstQueryType of this element + * @query: perform a #GstQuery on the element + * + * GStreamer element class. Override the vmethods to implement the element + * functionality. + */ struct _GstElementClass { GstObjectClass parent_class; @@ -381,7 +439,7 @@ struct _GstElementClass /*< private >*/ /* signal callbacks */ - void (*state_changed) (GstElement *element, GstState old, GstState state); + void (*state_changed) (GstElement *element, GstState old, GstState state); /* FIXME, ABI unused */ void (*pad_added) (GstElement *element, GstPad *pad); void (*pad_removed) (GstElement *element, GstPad *pad); void (*no_more_pads) (GstElement *element);