+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
<!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">
&GstSystemClock;
&GstTagList;
&GstTagSetter;
+ &GstTask;
&GstTypeFind;
&GstTypeFindFactory;
&GstUriHandler;
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
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
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>
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
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
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 */
#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)
/**
* @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 >*/
{
* 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"
* 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:
*
* 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.
* 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.
*/
* 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()
*
* 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,
* @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
* 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)))
/**
* 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)))
/**
* @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)))
* @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 */
* @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);
* 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);
*
* 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);
* 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);
/**
/**
* 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
* 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.
*/
* 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.
*/
*/
#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,
* 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.
*/
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;
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);
* @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.
*/
* 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.
*
* 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.
*
* 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.
*
*
* 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.
*
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 --- */
*/
#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)
/**
* @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.
*
* @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.
*
#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);
projects / platform / upstream / gstreamer.git / commitdiff