Commit e1a166a5 authored by Wim Taymans's avatar Wim Taymans

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.
parent 0e3178c1
2005-10-21 Wim Taymans <wim@fluendo.com>
* 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 <wingo@pobox.com>
* gst/base/gstbasesrc.c (gst_base_src_query): Clean up percent
......
......@@ -43,6 +43,7 @@
<!ENTITY GstSystemClock SYSTEM "xml/gstsystemclock.xml">
<!ENTITY GstTagList SYSTEM "xml/gsttaglist.xml">
<!ENTITY GstTagSetter SYSTEM "xml/gsttagsetter.xml">
<!ENTITY GstTask SYSTEM "xml/gsttask.xml">
<!ENTITY GstTrace SYSTEM "xml/gsttrace.xml">
<!ENTITY GstTypeFind SYSTEM "xml/gsttypefind.xml">
<!ENTITY GstTypeFindFactory SYSTEM "xml/gsttypefindfactory.xml">
......@@ -153,6 +154,7 @@ Windows. It is released under the GNU Library General Public License
&GstSystemClock;
&GstTagList;
&GstTagSetter;
&GstTask;
&GstTypeFind;
&GstTypeFindFactory;
&GstUriHandler;
......
......@@ -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
<SUBSECTION Standard>
......@@ -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
......
......@@ -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 >*/
{
......
......@@ -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.
* <example>
* <title>performing a seek on a pipeline</title>
* <programlisting>
* 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");
* ...
* </programlisting>
* </example>
*/
#include <string.h> /* 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.
*/
......
......@@ -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,
......
......@@ -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)))
......
......@@ -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.
*/
......
......@@ -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,
......
......@@ -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.
*
......
......@@ -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)
/**
......
......@@ -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.
*
......
......@@ -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);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment