Commit 55bf3d09 authored by Wim Taymans's avatar Wim Taymans

Documented the clocks.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstclock.c:
* gst/gstclock.h:
Documented the clocks.
parent d5dea919
2005-10-28 Wim Taymans <wim@fluendo.com>
* docs/gst/gstreamer-sections.txt:
* gst/gstclock.c:
* gst/gstclock.h:
Documented the clocks.
2005-10-28 Stefan Kost <ensonic@users.sf.net>
* docs/gst/gstreamer-sections.txt:
......
......@@ -344,7 +344,6 @@ GstClockReturn
GstClockFlags
GST_CLOCK_FLAGS
GST_CLOCK_BROADCAST
GST_CLOCK_CAST
GST_CLOCK_COND
GST_CLOCK_TIMED_WAIT
GST_CLOCK_WAIT
......@@ -372,6 +371,7 @@ GST_TYPE_CLOCK
GST_CLOCK_CLASS
GST_IS_CLOCK_CLASS
GST_CLOCK_GET_CLASS
GST_CLOCK_CAST
GST_TYPE_CLOCK_ENTRY_TYPE
GST_TYPE_CLOCK_FLAGS
GST_TYPE_CLOCK_RETURN
......
......@@ -26,16 +26,58 @@
* @short_description: Abstract class for global clocks
* @see_also: #GstSystemClock
*
* GStreamer uses a global clock to synchronise the plugins in a pipeline.
* GStreamer uses a global clock to synchronize the plugins in a pipeline.
* Different clock implementations are possible by implementing this abstract
* base class.
*
* The clock time is always measured in nanoseconds and always increases. The
* pipeline uses the clock to calculate the stream time.
* Usually all renderers sync to the global clock using the buffer timestamps,
* The #GstClock returns a monotonically increasing time with the method
* gst_clock_get_time(). Its accuracy and base time depends on the specific clock
* implementation but time is always expessed in nanoseconds. Since the
* baseline of the clock is undefined, the clock time returned is not
* meaningfull in itself, what matters are the deltas between two clock
* times.
*
* The pipeline uses the clock to calculate the stream time.
* Usually all renderers synchronize to the global clock using the buffer timestamps,
* the newsegment events and the element's base time.
*
* The time of the clock in itself is not very useful for an application.
*
* A clock implementation can support periodic and single shot clock notifications
* both synchronous and asynchronous.
*
* One first needs to create a #GstClockID for the periodic or single shot
* notification using gst_clock_new_single_shot_id() or gst_clock_new_periodic_id().
*
* To perform a blocking wait for the specific time of the #GstClockID use the
* gst_clock_id_wait(). To receive a callback when the specific time is reached
* in the clock use gst_clock_id_wait_async(). Both these calls can be interrupted
* with the gst_clock_id_unschedule() call. If the blocking wait is unscheduled
* a return value of GST_CLOCK_UNSCHEDULED is returned.
*
* The async callbacks can happen from any thread, either provided by the
* core or from a streaming thread. The application should be prepared for this.
*
* A #GstClockID that has been unscheduled cannot be used again for any wait
* operation.
*
* It is possible to perform a blocking wait on the same #GstClockID from multiple
* threads. However, registering the same #GstClockID for multiple async notifications is
* not possible, the callback will only be called once.
*
* None of the wait operations unref the #GstClockID, the owner is
* responsible for unreffing the ids itself. This holds for both periodic and
* single shot notifications. The reason being that the owner of the #GstClockID
* has to keep a handle to the #GstClockID to unblock the wait on FLUSHING events
* or state changes and if we unref it automatically, the handle might be
* invalid.
*
* These clock operations do not operate on the stream time, so the callbacks
* will also occur when not in PLAYING state as if the clock just keeps on
* running. Some clocks however do not progress when the element that provided
* the clock is not PLAYING.
*
* Last reviewed on 2005-10-28 (0.9.4)
*/
#include <time.h>
......
......@@ -44,6 +44,11 @@ G_BEGIN_DECLS
*/
typedef guint64 GstClockTime;
/**
* GST_TYPE_CLOCK_TIME:
*
* The GType of a GstClockTime.
*/
#define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
/**
......@@ -55,14 +60,14 @@ typedef gint64 GstClockTimeDiff;
/**
* GstClockID:
*
* A detatype to hold the handle to an outstanding async clock callback
* A datatype to hold the handle to an outstanding async clock callback.
*/
typedef gpointer GstClockID;
/**
* GST_CLOCK_TIME_NONE:
*
* Constant to define an undefined clock time
* Constant to define an undefined clock time.
*/
#define GST_CLOCK_TIME_NONE ((GstClockTime) -1)
/**
......@@ -76,19 +81,19 @@ typedef gpointer GstClockID;
/**
* GST_SECOND:
*
* Constant that defines one GStreamer second
* Constant that defines one GStreamer second.
*/
#define GST_SECOND (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
/**
* GST_MSECOND:
*
* Constant that defines one GStreamer millisecond
* Constant that defines one GStreamer millisecond.
*/
#define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
/**
* GST_USECOND:
*
* Constant that defines one GStreamer microsecond
* Constant that defines one GStreamer microsecond.
*/
#define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
/**
......@@ -155,7 +160,18 @@ G_STMT_START { \
} G_STMT_END
/* timestamp debugging macros */
/**
* GST_TIME_FORMAT:
*
* A format that can be used in printf like format strings to format
* a GstClockTime value.
*/
#define GST_TIME_FORMAT "u:%02u:%02u.%09u"
/**
* GST_TIME_ARGS:
*
* Format the GstClockTime argument for the GST_TIME_FORMAT format string.
*/
#define GST_TIME_ARGS(t) \
(guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)), \
(guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60), \
......@@ -310,11 +326,45 @@ typedef enum {
*/
#define GST_CLOCK_FLAGS(clock) (GST_CLOCK(clock)->flags)
/**
* GST_CLOCK_COND:
* @clock: the clock to query
*
* Gets the #GCond that gets signaled when the entries of the clock
* changed.
*/
#define GST_CLOCK_COND(clock) (GST_CLOCK_CAST(clock)->entries_changed)
/**
* GST_CLOCK_WAIT:
* @clock: the clock to wait on
*
* Wait on the clock until the entries changed.
*/
#define GST_CLOCK_WAIT(clock) g_cond_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock))
/**
* GST_CLOCK_TIMED_WAIT:
* @clock: the clock to wait on
* @tv: a GTimeVal to wait.
*
* Wait on the clock until the entries changed or the specified timeout
* occured.
*/
#define GST_CLOCK_TIMED_WAIT(clock,tv) g_cond_timed_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock),tv)
/**
* GST_CLOCK_BROADCAST:
* @clock: the clock to broadcast
*
* Signal that the entries in the clock have changed.
*/
#define GST_CLOCK_BROADCAST(clock) g_cond_broadcast(GST_CLOCK_COND(clock))
/**
* GstClock:
* @flags: The flags specifying the capabilities of the clock.
*
* GstClock base structure. The values of this structure are
* protected for subclasses, use the methods to use the #GstClock.
*/
struct _GstClock {
GstObject object;
......
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