From: Wim Taymans Date: Fri, 21 Oct 2005 11:36:32 +0000 (+0000) Subject: And 2% more doc coverage. X-Git-Tag: RELEASE-0_9_4~8 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e1a166a58416880458aa44dc0c21dd6a5f90a76c;p=platform%2Fupstream%2Fgstreamer.git And 2% more doc coverage. Original commit message from CVS: * docs/gst/gstreamer-docs.sgml: * docs/gst/gstreamer-sections.txt: * gst/gstelement.h: * gst/gstevent.c: * gst/gstevent.h: * gst/gstmessage.h: * gst/gstpad.h: * gst/gstparse.h: * gst/gsttask.c: (gst_task_finalize), (gst_task_func): * gst/gsttask.h: * gst/gstutils.c: * gst/gstutils.h: And 2% more doc coverage. --- diff --git a/ChangeLog b/ChangeLog index 3428825..d516520 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +2005-10-21 Wim Taymans + + * docs/gst/gstreamer-docs.sgml: + * docs/gst/gstreamer-sections.txt: + * gst/gstelement.h: + * gst/gstevent.c: + * gst/gstevent.h: + * gst/gstmessage.h: + * gst/gstpad.h: + * gst/gstparse.h: + * gst/gsttask.c: (gst_task_finalize), (gst_task_func): + * gst/gsttask.h: + * gst/gstutils.c: + * gst/gstutils.h: + And 2% more doc coverage. + 2005-10-21 Andy Wingo * gst/base/gstbasesrc.c (gst_base_src_query): Clean up percent diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml index 818e6c4..4043b4c 100644 --- a/docs/gst/gstreamer-docs.sgml +++ b/docs/gst/gstreamer-docs.sgml @@ -43,6 +43,7 @@ + @@ -153,6 +154,7 @@ Windows. It is released under the GNU Library General Public License &GstSystemClock; &GstTagList; &GstTagSetter; + &GstTask; &GstTypeFind; &GstTypeFindFactory; &GstUriHandler; diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 41103a0..8ebf02a 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -498,6 +498,7 @@ gst_element_provides_clock gst_element_query gst_element_query_convert gst_element_query_position +gst_element_query_duration gst_element_release_request_pad gst_element_remove_pad gst_element_requires_clock @@ -983,6 +984,8 @@ gst_message_new_segment_start gst_message_new_state_changed gst_message_new_tag gst_message_new_warning +gst_message_new_duration +gst_message_new_state_dirty gst_message_parse_clock_lost gst_message_parse_clock_provide gst_message_parse_error @@ -992,6 +995,7 @@ gst_message_parse_segment_start gst_message_parse_state_changed gst_message_parse_tag gst_message_parse_warning +gst_message_parse_duration gst_message_ref gst_message_unref @@ -1230,6 +1234,7 @@ gst_pad_event_default gst_pad_query gst_pad_query_default gst_pad_query_position +gst_pad_query_duration gst_pad_query_convert gst_pad_set_query_function GstPadQueryFunction @@ -1527,12 +1532,15 @@ gst_query_make_writable gst_query_new_application gst_query_new_convert gst_query_new_position +gst_query_new_duration gst_query_parse_convert gst_query_parse_position +gst_query_parse_duration gst_query_ref gst_query_set_convert gst_query_set_formats gst_query_set_position +gst_query_set_duration gst_query_set_seeking gst_query_type_iterate_definitions gst_query_unref diff --git a/gst/gstelement.h b/gst/gstelement.h index c14cd9f..42a401d 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -29,6 +29,16 @@ typedef struct _GstElement GstElement; 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. + */ typedef enum { GST_STATE_VOID_PENDING = 0, /* used for GstElement->pending_state when there is no pending state */ @@ -116,9 +126,37 @@ typedef enum { #define GST_STATE_RETURN(obj) (GST_ELEMENT(obj)->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 + * + * Given a current state and a target state, calculate the next (intermediate) + * state. + */ #define GST_STATE_GET_NEXT(cur,pending) ((cur) + __GST_SIGN ((gint)(pending) - (gint)(cur))) +/** + * GST_STATE_TRANSITION: + * @cur: A current state + * @next: A next state + * + * Given a current state and a next state, calculate the associated + * state transition. + */ #define GST_STATE_TRANSITION(cur,next) (((cur)<<3)|(next)) +/** + * GST_STATE_TRANSITION_CURRENT: + * @trans: A state transition + * + * Given a state transition, extract the current state. + */ #define GST_STATE_TRANSITION_CURRENT(trans) ((trans)>>3) +/** + * GST_STATE_TRANSITION_NEXT: + * @trans: A state transition + * + * Given a state transition, extract the next state. + */ #define GST_STATE_TRANSITION_NEXT(trans) ((trans)&0x7) /** @@ -129,6 +167,9 @@ typedef enum { * @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. */ typedef enum /*< flags=0 >*/ { diff --git a/gst/gstevent.c b/gst/gstevent.c index 5395b81..cefad04 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -33,12 +33,41 @@ * Events can be parsed with their respective gst_event_parse_*() functions. * The event should be unreffed with gst_event_unref(). * + * Events are passed between elements in parallel to the data stream. Some events + * are serialized with buffers, others are not. Some events only travel downstream, + * others only upstream. Some events can travel both upstream and downstream. + * + * The events are used to signal special conditions in the datastream such as EOS + * or the start of a new segment. Events are also used to flush the pipeline of + * any pending data. + * + * Most of the event API is used inside plugins. The application usually only + * constructs and uses the seek event API when it wants to perform a seek in the + * pipeline. + * gst_event_new_seek() is usually used to create a seek event and it takes * the needed parameters for a seek event. - * - * gst_event_new_flush() creates a new flush event. + * + * performing a seek on a pipeline + * + * GstEvent *event; + * gboolean result; + * ... + * // construct a seek event to play the media from second 2 to 5, flush + * // the pipeline to decrease latency. + * event = gst_event_new_seek (1.0, + * GST_FORMAT_TIME, + * GST_SEEK_FLAG_FLUSH, + * GST_SEEK_TYPE_SET, 2 * GST_SECOND, + * GST_SEEK_TYPE_SET, 5 * GST_SECOND); + * ... + * result = gst_element_send_event (pipeline, event); + * if (!result) + * g_warning ("seek failed"); + * ... + * + * */ - #include /* memcpy */ #include "gst_private.h" @@ -373,7 +402,7 @@ gst_event_new_eos (void) * into the stream time again. * * The @start_value cannot be -1, the @stop_value can be -1. If there - * is a valid @stop_value given, it must be smaller than @start_value. + * is a valid @stop_value given, it must be greater or equal than @start_value. * * After a newsegment event, the buffer stream time is calculated with: * @@ -649,7 +678,7 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion, * Allocate a new seek event with the given parameters. * * The seek event configures playback of the pipeline from - * @cur to @stop at the speed given in @rate. + * @cur to @stop at the speed given in @rate, also called a segment. * The @cur and @stop values are expressed in format @format. * * A @rate of 1.0 means normal playback rate, 2.0 means double speed. @@ -657,8 +686,9 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion, * rate is not allowed. * * @cur_type and @stop_type specify how to adjust the current and stop - * time, relative or absolute. A type of #GST_EVENT_TYPE_NONE means that - * the position should not be updated. + * time, relative or absolute. A type of #GST_SEEK_TYPE_NONE means that + * the position should not be updated. The currently configured playback + * segment can be queried with #GST_QUERY_SEGMENT. * * Returns: A new seek event. */ diff --git a/gst/gstevent.h b/gst/gstevent.h index 14cea51..9ad9ab0 100644 --- a/gst/gstevent.h +++ b/gst/gstevent.h @@ -232,9 +232,7 @@ typedef enum { * be considerably slower for some formats. * @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be * faster but less accurate. - * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback - * of the segment completes, no EOS will be emmited but a - * SEGMENT_DONE message will be posted on the bus. + * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. * * Flags to be used with #gst_element_seek() or #gst_event_new_seek() * @@ -244,6 +242,12 @@ typedef enum { * An accurate seek might be slower for formats that don't have any indexes * or timestamp markers in the stream. Specifying this flag might require a * complete scan of the file in those cases. + * + * When perfoming a segment seek: after the playback of the segment completes, + * no EOS will be emmited byt the element that performed the seek but a SEGMENT_DONE + * message will be posted on the bus by the element. When this message is posted, it is + * possible to send a new seek event to continue playback. With this seek method it + * is possible to perform seemless looping or simple linear editing. */ typedef enum { GST_SEEK_FLAG_NONE = 0, diff --git a/gst/gstmessage.h b/gst/gstmessage.h index b95d041..15c80c7 100644 --- a/gst/gstmessage.h +++ b/gst/gstmessage.h @@ -55,6 +55,8 @@ typedef struct _GstMessageClass GstMessageClass; * @GST_MESSAGE_SEGMENT_DONE: pipeline completed playback of a segment. * @GST_MESSAGE_DURATION: The duration of a pipeline changed. * @GST_MESSAGE_ANY: mask for all of the above messages. + * + * The different message types that are available. */ /* NOTE: keep in sync with quark registration in gstmessage.c */ typedef enum @@ -149,9 +151,8 @@ GQuark gst_message_type_to_quark (GstMessageType type); * gst_message_ref: * @msg: the message to ref * - * Convinience macro to increase the reference count of the message. - * - * Returns: the refed message. + * Convinience macro to increase the reference count of the message. Returns the + * reffed message. */ #define gst_message_ref(msg) GST_MESSAGE (gst_mini_object_ref (GST_MINI_OBJECT (msg))) /** @@ -167,11 +168,9 @@ GQuark gst_message_type_to_quark (GstMessageType type); * gst_message_copy: * @msg: the message to copy * - * Creates a copy of the message. + * Creates a copy of the message. Returns a copy of the message. * * MT safe - * - * Returns: the new message. */ #define gst_message_copy(msg) GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg))) /** @@ -179,11 +178,9 @@ GQuark gst_message_type_to_quark (GstMessageType type); * @msg: the message to make writable * * Checks if a message is writable. If not, a writable copy is made and - * returned. + * returned. Returns a message (possibly a duplicate) that is writable. * * MT safe - * - * Returns: a message (possibly a duplicate) that it writable. */ #define gst_message_make_writable(msg) GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg))) diff --git a/gst/gstpad.h b/gst/gstpad.h index 03a2358..aef9b66 100644 --- a/gst/gstpad.h +++ b/gst/gstpad.h @@ -118,19 +118,37 @@ typedef enum { * @ret: a #GstFlowReturn value * * Macro to test if the given #GstFlowReturn value indicates a fatal - * error. + * error. This macro is mainly used in elements to decide when an error + * message should be posted on the bus. */ #define GST_FLOW_IS_FATAL(ret) ((ret) <= GST_FLOW_UNEXPECTED) G_CONST_RETURN gchar* gst_flow_get_name (GstFlowReturn ret); GQuark gst_flow_to_quark (GstFlowReturn ret); +/** + * GstActivateMode: + * @GST_ACTIVATE_NONE: Pad will not handle dataflow + * @GST_ACTIVATE_PUSH: Pad handles dataflow in downstream push mode + * @GST_ACTIVATE_PULL: Pad handles dataflow in upstream pull mode + * + * The status of a GstPad. After activating a pad, which usually happens when the + * parent element goes from READY to PAUSED, the GstActivateMode defines if the + * pad operates in push or pull mode. + */ typedef enum { GST_ACTIVATE_NONE, GST_ACTIVATE_PUSH, GST_ACTIVATE_PULL, } GstActivateMode; +/** + * GST_PAD_MODE_ACTIVATE: + * @mode: a #GstActivateMode + * + * Macro to test if the given #GstActivateMode value indicates that datapassing + * is possible or not. + */ #define GST_PAD_MODE_ACTIVATE(mode) ((mode) != GST_ACTIVATE_NONE) /* pad states */ @@ -144,11 +162,25 @@ typedef gboolean (*GstPadActivateModeFunction) (GstPad *pad, gboolean active); * @pad: the #GstPad that performed the chain. * @buffer: the #GstBuffer that is chained. * - * A function that will be called when chaining buffers. + * A function that will be called on sinkpads when chaining buffers. * - * Returns: GST_FLOW_OK for success + * Returns: GST_FLOW_OK for success */ typedef GstFlowReturn (*GstPadChainFunction) (GstPad *pad, GstBuffer *buffer); +/** + * GstPadGetRangeFunction: + * @pad: the #GstPad to perform the getrange on. + * @offset: the offset of the range + * @length: the length of the range + * @buffer: a memory location to hold the result buffer + * + * This function will be called on sourcepads when a peer element + * request a buffer at the specified offset and length. If this function + * returns GST_FLOW_OK, the result buffer will be stored in @buffer. The + * contents of @buffer is invalid for any other return value. + * + * Returns: GST_FLOW_OK for success + */ typedef GstFlowReturn (*GstPadGetRangeFunction) (GstPad *pad, guint64 offset, guint length, GstBuffer **buffer); @@ -178,7 +210,6 @@ typedef gboolean (*GstPadCheckGetRangeFunction) (GstPad *pad); * Returns: a newly allocated #GList of pads that are linked to the given pad on * the inside of the parent element. * The caller must call g_list_free() on it after use. - * */ typedef GList* (*GstPadIntLinkFunction) (GstPad *pad); @@ -190,7 +221,7 @@ typedef GList* (*GstPadIntLinkFunction) (GstPad *pad); * * The signature of the query types function. * - * Returns: an array of query types + * Returns: a constant array of query types */ typedef const GstQueryType* (*GstPadQueryTypeFunction) (GstPad *pad); @@ -266,7 +297,6 @@ typedef gboolean (*GstPadDispatcherFunction) (GstPad *pad, gpointer data); * Callback used by gst_pad_set_blocked_async(). Gets called when the blocking * operation succeeds. */ - typedef void (*GstPadBlockCallback) (GstPad *pad, gboolean blocked, gpointer user_data); /** @@ -286,7 +316,7 @@ typedef enum { /** * GstPadFlags: * @GST_PAD_BLOCKED: is dataflow on a pad blocked - * @GST_PAD_FLUSHING: is pad empying buffers + * @GST_PAD_FLUSHING: is pad refusing buffers * @GST_PAD_IN_GETCAPS: GstPadGetCapsFunction() is running now * @GST_PAD_IN_SETCAPS: GstPadSetCapsFunction() is running now * @GST_PAD_FLAG_LAST: offset to define more flags @@ -471,9 +501,7 @@ GstPad* gst_pad_new_from_template (GstPadTemplate *templ, const gchar *name); * gst_pad_get_name: * @pad: the pad to get the name from * - * Returns a copy of the name of the pad. - * - * Returns: the name of the pad. g_free() after usage. + * Get a copy of the name of the pad. g_free() after usage. * * MT safe. */ @@ -482,11 +510,9 @@ GstPad* gst_pad_new_from_template (GstPadTemplate *templ, const gchar *name); * gst_pad_get_parent: * @pad: the pad to get the parent of * - * Returns the parent of @pad. This function increases the refcount + * Get the parent of @pad. This function increases the refcount * of the parent object so you should gst_object_unref() it after usage. - * - * Returns: parent of the object, this can be NULL if the pad has no - * parent. unref after usage. + * Can return NULL if the pad did not have a parent. * * MT safe. */ diff --git a/gst/gstparse.h b/gst/gstparse.h index e259293..7deea1b 100644 --- a/gst/gstparse.h +++ b/gst/gstparse.h @@ -37,6 +37,18 @@ GQuark gst_parse_error_quark (void); */ #define GST_PARSE_ERROR gst_parse_error_quark () +/** + * GstParseError: + * @GST_PARSE_ERROR_SYNTAX: A syntax error occured. + * @GST_PARSE_ERROR_NO_SUCH_ELEMENT: The description contained an unknown element + * @GST_PARSE_ERROR_NO_SUCH_PROPERTY: An element did not have a specified property + * @GST_PARSE_ERROR_LINK: There was an error linking two pads. + * @GST_PARSE_ERROR_COULD_NOT_SET_PROPERTY: There was an error setting a property + * @GST_PARSE_ERROR_EMPTY_BIN: An empty bin was specified. + * @GST_PARSE_ERROR_EMPTY: An empty description was specified + * + * The different parsing errors that can occur. + */ typedef enum { GST_PARSE_ERROR_SYNTAX, diff --git a/gst/gsttask.c b/gst/gsttask.c index 29ed4e7..96b6506 100644 --- a/gst/gsttask.c +++ b/gst/gsttask.c @@ -49,10 +49,10 @@ * the function it will acquire the provided lock. * * Stopping a task with gst_task_stop() will not immediatly make sure the task is - * not running anymnore. Use gst_task_join() to make sure the task is completely + * not running anymore. Use gst_task_join() to make sure the task is completely * stopped and the thread is stopped. * - * After creating a GstTask, use gst_object_unref() to free its resources. this can + * After creating a GstTask, use gst_object_unref() to free its resources. This can * only be done it the task is not running anymore. */ @@ -132,6 +132,8 @@ gst_task_finalize (GObject * object) GST_DEBUG ("task %p finalize", task); + /* task thread cannot be running here since it holds a ref + * to the task so that the finalize could not have happened */ g_cond_free (task->cond); task->cond = NULL; @@ -174,7 +176,7 @@ gst_task_func (GstTask * task, GstTaskClass * tclass) g_static_rec_mutex_lock_full (lock, t); GST_LOCK (task); - if (task->state == GST_TASK_STOPPED) + if (G_UNLIKELY (task->state == GST_TASK_STOPPED)) goto done; } GST_UNLOCK (task); @@ -260,7 +262,8 @@ gst_task_create (GstTaskFunction func, gpointer data) * @task: The #GstTask to use * @mutex: The GMutex to use * - * Set the mutex used by the task. + * Set the mutex used by the task. The mutex will be acquired before + * calling the #GstTaskFunction. * * MT safe. */ @@ -312,7 +315,8 @@ gst_task_get_state (GstTask * task) * gst_task_start: * @task: The #GstTask to start * - * Starts @task. + * Starts @task. The @task must have a lock associated with it using + * #gst_task_set_lock() or thsi function will return FALSE. * * Returns: TRUE if the task could be started. * @@ -372,7 +376,9 @@ no_lock: * gst_task_stop: * @task: The #GstTask to stop * - * Stops @task. + * Stops @task. This method merely schedules the task to stop and + * will not wait for the task to have completely stopped. Use + * #gst_task_join() to stop and wait for completion. * * Returns: TRUE if the task could be stopped. * @@ -411,7 +417,10 @@ gst_task_stop (GstTask * task) * gst_task_pause: * @task: The #GstTask to pause * - * Pauses @task. + * Pauses @task. This method can also be called on a task in the + * stopped state, in which case a thread will be started and will remain + * in the paused state. This function does not wait for the task to complete + * the paused state. * * Returns: TRUE if the task could be paused. * @@ -461,7 +470,8 @@ gst_task_pause (GstTask * task) * * The task will automatically be stopped with this call. * - * This function cannot be called from within a task function. + * This function cannot be called from within a task function as this + * will cause a deadlock. * * Returns: TRUE if the task could be joined. * diff --git a/gst/gsttask.h b/gst/gsttask.h index 5968ea0..a0d4380 100644 --- a/gst/gsttask.h +++ b/gst/gsttask.h @@ -27,6 +27,13 @@ G_BEGIN_DECLS +/** + * GstTaskFunction: + * @data: user data passed to the function + * + * A function that will repeadedly be called in the thread created by + * a GstTask. + */ typedef void (*GstTaskFunction) (void *data); /* --- standard type macros --- */ @@ -63,11 +70,41 @@ typedef enum { */ #define GST_TASK_STATE(task) (GST_TASK_CAST(task)->state) +/** + * GST_TASK_GET_COND: + * @task: Task to get the cond of + * + * Get access to the cond of the task. + */ #define GST_TASK_GET_COND(task) (GST_TASK_CAST(task)->cond) +/** + * GST_TASK_WAIT: + * @task: Task to wait for + * + * Wait for the task cond to be signalled + */ #define GST_TASK_WAIT(task) g_cond_wait(GST_TASK_GET_COND (task), GST_GET_LOCK (task)) +/** + * GST_TASK_SIGNAL: + * @task: Task to signal + * + * Signal the task cond + */ #define GST_TASK_SIGNAL(task) g_cond_signal(GST_TASK_GET_COND (task)) +/** + * GST_TASK_BROADCAST: + * @task: Task to broadcast + * + * Send a broadcast signal to all waiting task conds + */ #define GST_TASK_BROADCAST(task) g_cond_breadcast(GST_TASK_GET_COND (task)) +/** + * GST_TASK_GET_LOCK: + * @task: Task to get the lock of + * + * Get access to the task lock. + */ #define GST_TASK_GET_LOCK(task) (GST_TASK_CAST(task)->lock) /** diff --git a/gst/gstutils.c b/gst/gstutils.c index 5cc7ba0..9dc594b 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -1640,7 +1640,7 @@ gst_element_query_position (GstElement * element, GstFormat * format, * @element: a #GstElement to invoke the duration query on. * @format: a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @cur: A location in which to store the total duration, or NULL. + * @duration: A location in which to store the total duration, or NULL. * * Queries an element for the total stream duration. * @@ -2411,7 +2411,7 @@ gst_pad_query_position (GstPad * pad, GstFormat * format, gint64 * cur) * @pad: a #GstPad to invoke the duration query on. * @format: a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @cur: A location in which to store the total duration, or NULL. + * @duration: A location in which to store the total duration, or NULL. * * Queries a pad for the total stream duration. * diff --git a/gst/gstutils.h b/gst/gstutils.h index d2fbc5a..40696f5 100644 --- a/gst/gstutils.h +++ b/gst/gstutils.h @@ -476,9 +476,6 @@ gboolean g_static_rec_cond_timed_wait (GCond *cond, #endif /* element functions */ -GstFlowReturn gst_element_abort_preroll (GstElement *element); -GstFlowReturn gst_element_finish_preroll (GstElement *element, GstPad *pad); - void gst_element_create_all_pads (GstElement *element); GstPad* gst_element_get_compatible_pad (GstElement *element, GstPad *pad, const GstCaps *caps);