mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-26 17:18:15 +00:00
Code Issues 1 Projects Releases Wiki Activity

And 2% more doc coverage.

Browse source 
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.
This commit is contained in:
Wim Taymans 2005-10-21 11:36:32 +00:00
parent 0e3178c111
commit e1a166a584
13 changed files with 226 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
ChangeLog
View file

@ -1,3 +1,19 @@
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

2
docs/gst/gstreamer-docs.sgml
View file

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

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

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

41
gst/gstelement.h
View file

@ -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 >*/
{

44
gst/gstevent.c
View file

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

10
gst/gstevent.h
View file

@ -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,

15
gst/gstmessage.h
View file

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

54
gst/gstpad.h
View file

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

12
gst/gstparse.h
View file

@ -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,

26
gst/gsttask.c
View file

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

37
gst/gsttask.h
View file

@ -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)
/**

4
gst/gstutils.c
View file

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

3
gst/gstutils.h
View file

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