mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-27 18:50:48 +00:00
Code Issues 1 Projects Releases Wiki Activity

Fix docs, move some STATE macros to private.

Browse source 
Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstelement.c:
* gst/gstelement.h:
Fix docs, move some STATE macros to private.
This commit is contained in:
Wim Taymans 2005-11-10 11:17:26 +00:00
parent 96936912f3
commit a56bdf2768
4 changed files with 160 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
ChangeLog
View file

@ -1,3 +1,10 @@
2005-11-10 Wim Taymans <wim@fluendo.com>
* docs/gst/gstreamer-sections.txt:
* gst/gstelement.c:
* gst/gstelement.h:
Fix docs, move some STATE macros to private.
2005-11-10 Wim Taymans <wim@fluendo.com>
* check/gst/gstghostpad.c: (GST_START_TEST), (gst_ghost_pad_suite):

27
docs/gst/gstreamer-sections.txt
View file

@ -422,30 +422,24 @@ GST_PADDING_INIT
<FILE>gstelement</FILE>
<TITLE>GstElement</TITLE>
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
<SUBSECTION Standard>
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
<SUBSECTION Private>
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

49
gst/gstelement.c
View file

@ -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.
*

158
gst/gstelement.h
View file

@ -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);