GstClock

GstClock —

Synopsis


#include <gst/gst.h>


            GstClock;
typedef     GstClockTime;
typedef     GstClockTimeDiff;
typedef     GstClockID;
#define     GST_CLOCK_TIME_NONE
#define     GST_CLOCK_TIME_IS_VALID         (time)
#define     GST_SECOND
#define     GST_MSECOND
#define     GST_USECOND
#define     GST_NSECOND
#define     GST_CLOCK_DIFF                  (s, e)
#define     GST_TIMEVAL_TO_TIME             (tv)
#define     GST_TIME_TO_TIMEVAL             (t,tv)
#define     GST_TIMESPEC_TO_TIME            (ts)
#define     GST_TIME_TO_TIMESPEC            (t,ts)
#define     GST_CLOCK_ENTRY_TRACE_NAME
            GstClockEntry;
gboolean    (*GstClockCallback)             (GstClock *clock,
                                             GstClockTime time,
                                             GstClockID id,
                                             gpointer user_data);
enum        GstClockEntryType;
#define     GST_CLOCK_ENTRY                 (entry)
#define     GST_CLOCK_ENTRY_CLOCK           (entry)
#define     GST_CLOCK_ENTRY_TYPE            (entry)
#define     GST_CLOCK_ENTRY_TIME            (entry)
#define     GST_CLOCK_ENTRY_INTERVAL        (entry)
#define     GST_CLOCK_ENTRY_STATUS          (entry)
enum        GstClockReturn;
enum        GstClockFlags;
#define     GST_CLOCK_FLAGS                 (clock)
#define     GST_CLOCK_BROADCAST             (clock)
#define     GST_CLOCK_COND                  (clock)
#define     GST_CLOCK_TIMED_WAIT            (clock,tv)
#define     GST_CLOCK_WAIT                  (clock)
gboolean    gst_clock_add_observation       (GstClock *clock,
                                             GstClockTime slave,
                                             GstClockTime master,
                                             gdouble *r_squared);
gboolean    gst_clock_set_master            (GstClock *clock,
                                             GstClock *master);
GstClock*   gst_clock_get_master            (GstClock *clock);
GstClockTime gst_clock_set_resolution       (GstClock *clock,
                                             GstClockTime resolution);
GstClockTime gst_clock_get_resolution       (GstClock *clock);
GstClockTime gst_clock_get_time             (GstClock *clock);
GstClockID  gst_clock_new_single_shot_id    (GstClock *clock,
                                             GstClockTime time);
GstClockID  gst_clock_new_periodic_id       (GstClock *clock,
                                             GstClockTime start_time,
                                             GstClockTime interval);
GstClockTime gst_clock_get_internal_time    (GstClock *clock);
GstClockTime gst_clock_adjust_unlocked      (GstClock *clock,
                                             GstClockTime internal);
void        gst_clock_get_calibration       (GstClock *clock,
                                             GstClockTime *internal,
                                             GstClockTime *external,
                                             GstClockTime *rate_num,
                                             GstClockTime *rate_denom);
void        gst_clock_set_calibration       (GstClock *clock,
                                             GstClockTime internal,
                                             GstClockTime external,
                                             GstClockTime rate_num,
                                             GstClockTime rate_denom);
GstClockTime gst_clock_id_get_time          (GstClockID id);
GstClockReturn gst_clock_id_wait            (GstClockID id,
                                             GstClockTimeDiff *jitter);
GstClockReturn gst_clock_id_wait_async      (GstClockID id,
                                             GstClockCallback func,
                                             gpointer user_data);
void        gst_clock_id_unschedule         (GstClockID id);
gint        gst_clock_id_compare_func       (gconstpointer id1,
                                             gconstpointer id2);
GstClockID  gst_clock_id_ref                (GstClockID id);
void        gst_clock_id_unref              (GstClockID id);
#define     GST_TYPE_CLOCK_TIME


Object Hierarchy


  GObject
   +----GstObject
         +----GstClock
               +----GstSystemClock

Properties


  "stats"                gboolean              : Read / Write
  "timeout"              guint64               : Read / Write
  "window-size"          gint                  : Read / Write
  "window-threshold"     gint                  : Read / Write

Description

Details

GstClock

typedef struct _GstClock GstClock;

GstClock base structure. The values of this structure are protected for subclasses, use the methods to use the GstClock.


GstClockTime

typedef guint64	GstClockTime;

A datatype to hold a time, measured in nanoseconds.


GstClockTimeDiff

typedef gint64 GstClockTimeDiff;

A datatype to hold a timedifference, measured in nanoseconds.


GstClockID

typedef gpointer GstClockID;

A datatype to hold the handle to an outstanding sync or async clock callback.


GST_CLOCK_TIME_NONE

#define GST_CLOCK_TIME_NONE		((GstClockTime) -1)

Constant to define an undefined clock time.


GST_CLOCK_TIME_IS_VALID()

#define GST_CLOCK_TIME_IS_VALID(time)	((time) != GST_CLOCK_TIME_NONE)

Tests if a given GstClockTime represents a valid defined time.

time : clock time to validate

GST_SECOND

#define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer second.


GST_MSECOND

#define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer millisecond.


GST_USECOND

#define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))

Constant that defines one GStreamer microsecond.


GST_NSECOND

#define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))

Constant that defines one GStreamer nanosecond


GST_CLOCK_DIFF()

#define GST_CLOCK_DIFF(s, e)		(GstClockTimeDiff)((e) - (s))

Calculate a difference between two clock times as a GstClockTimeDiff.

s : the first time
e : the second time

GST_TIMEVAL_TO_TIME()

#define GST_TIMEVAL_TO_TIME(tv)		((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)

Convert a GTimeVal to a GstClockTime.

tv : the timeval to convert

GST_TIME_TO_TIMEVAL()

#define     GST_TIME_TO_TIMEVAL(t,tv)

Note: on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds, which is about 68 years. Expect trouble if you want to schedule stuff in your pipeline for 2038.

Convert a GstClockTime to a GTimeVal

t : The GstClockTime to convert
tv : The target timeval

GST_TIMESPEC_TO_TIME()

#define GST_TIMESPEC_TO_TIME(ts)		((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)

Convert a struct timespec (see man pselect) to a GstClockTime.

ts : the timespec to convert

GST_TIME_TO_TIMESPEC()

#define     GST_TIME_TO_TIMESPEC(t,ts)

Convert a GstClockTime to a struct timespec (see man pselect)

t : The GstClockTime to convert
ts : The target timespec

GST_CLOCK_ENTRY_TRACE_NAME

#define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"

The name used for tracing clock entry allocations.


GstClockEntry

typedef struct {
  gint			refcount;
} GstClockEntry;

All pending timeouts or periodic notifies are converted into an entry.

gint refcount; reference counter (read-only)

GstClockCallback ()

gboolean    (*GstClockCallback)             (GstClock *clock,
                                             GstClockTime time,
                                             GstClockID id,
                                             gpointer user_data);

The function prototype of the callback.

clock : The clock that triggered the callback
time : The time it was triggered
id : The GstClockID that expired
user_data : user data passed in the async_wait call
Returns : TRUE or FALSE (currently unused)

enum GstClockEntryType

typedef enum {
  GST_CLOCK_ENTRY_SINGLE,
  GST_CLOCK_ENTRY_PERIODIC
} GstClockEntryType;

The type of the clock entry

GST_CLOCK_ENTRY_SINGLE a single shot timeout
GST_CLOCK_ENTRY_PERIODIC a periodic timeout request

GST_CLOCK_ENTRY()

#define GST_CLOCK_ENTRY(entry)		((GstClockEntry *)(entry))

Cast to a clock entry

entry : the entry to cast

GST_CLOCK_ENTRY_CLOCK()

#define GST_CLOCK_ENTRY_CLOCK(entry)	((entry)->clock)

Get the owner clock of the entry

entry : the entry to query

GST_CLOCK_ENTRY_TYPE()

#define GST_CLOCK_ENTRY_TYPE(entry)	((entry)->type)

Get the type of the clock entry

entry : the entry to query

GST_CLOCK_ENTRY_TIME()

#define GST_CLOCK_ENTRY_TIME(entry)	((entry)->time)

Get the requested time of this entry

entry : the entry to query

GST_CLOCK_ENTRY_INTERVAL()

#define GST_CLOCK_ENTRY_INTERVAL(entry)	((entry)->interval)

Get the interval of this periodic entry

entry : the entry to query

GST_CLOCK_ENTRY_STATUS()

#define GST_CLOCK_ENTRY_STATUS(entry)	((entry)->status)

The status of the entry

entry : the entry to query

enum GstClockReturn

typedef enum
{
  GST_CLOCK_OK		=  0,
  GST_CLOCK_EARLY	=  1,
  GST_CLOCK_UNSCHEDULED	=  2,
  GST_CLOCK_BUSY	=  3,
  GST_CLOCK_BADTIME	=  4,
  GST_CLOCK_ERROR	=  5,
  GST_CLOCK_UNSUPPORTED	=  6,
} GstClockReturn;

The return value of a clock operation.

GST_CLOCK_OK The operation succeded.
GST_CLOCK_EARLY The operation was scheduled too late.
GST_CLOCK_UNSCHEDULED The clockID was unscheduled
GST_CLOCK_BUSY The ClockID is busy
GST_CLOCK_BADTIME A bad time was provided to a function.
GST_CLOCK_ERROR An error occured
GST_CLOCK_UNSUPPORTED Operation is not supported

enum GstClockFlags

typedef enum {
  GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (GST_OBJECT_FLAG_LAST << 0),
  GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (GST_OBJECT_FLAG_LAST << 1),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (GST_OBJECT_FLAG_LAST << 2),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (GST_OBJECT_FLAG_LAST << 3),
  GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (GST_OBJECT_FLAG_LAST << 4),
  GST_CLOCK_FLAG_CAN_SET_MASTER         = (GST_OBJECT_FLAG_LAST << 5),
  /* padding */
  GST_CLOCK_FLAG_LAST		        = (GST_OBJECT_FLAG_LAST << 8),
} GstClockFlags;

The capabilities of this clock

GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC clock can do a single sync timeout request
GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC clock can do a single async timeout request
GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC clock can do sync periodic timeout requests
GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC clock can do async periodic timeout callbacks
GST_CLOCK_FLAG_CAN_SET_RESOLUTION clock's resolution can be changed
GST_CLOCK_FLAG_CAN_SET_MASTER clock can be slaved to a master clock
GST_CLOCK_FLAG_LAST subclasses can add additional flags starting from this flag

GST_CLOCK_FLAGS()

#define GST_CLOCK_FLAGS(clock)  (GST_CLOCK(clock)->flags)

Gets the GstClockFlags clock flags.

clock : the clock to query

GST_CLOCK_BROADCAST()

#define GST_CLOCK_BROADCAST(clock)       g_cond_broadcast(GST_CLOCK_COND(clock))

Signal that the entries in the clock have changed.

clock : the clock to broadcast

GST_CLOCK_COND()

#define GST_CLOCK_COND(clock)            (GST_CLOCK_CAST(clock)->entries_changed)

Gets the GCond that gets signaled when the entries of the clock changed.

clock : the clock to query

GST_CLOCK_TIMED_WAIT()

#define GST_CLOCK_TIMED_WAIT(clock,tv)   g_cond_timed_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock),tv)

Wait on the clock until the entries changed or the specified timeout occured.

clock : the clock to wait on
tv : a GTimeVal to wait.

GST_CLOCK_WAIT()

#define GST_CLOCK_WAIT(clock)            g_cond_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock))

Wait on the clock until the entries changed.

clock : the clock to wait on

gst_clock_add_observation ()

gboolean    gst_clock_add_observation       (GstClock *clock,
                                             GstClockTime slave,
                                             GstClockTime master,
                                             gdouble *r_squared);

The time master of the master clock and the time slave of the slave clock are added to the list of observations. If enough observations are available, a linear regression algorithm is run on the observations and clock is recalibrated.

clock : a GstClock
slave : a time on the slave
master : a time on the master
r_squared : a pointer to hold the result
Returns : TRUE if enough observations were added to run the regression algorithm. MT safe.

gst_clock_set_master ()

gboolean    gst_clock_set_master            (GstClock *clock,
                                             GstClock *master);

Set master as the master clock for clock. clock will be automatically calibrated so that gst_clock_get_time() reports the same time as the master clock.

A clock provider that slaves its clock to a master can get the current calibration values with gst_clock_get_calibration().

clock : a GstClock
master : a master GstClock
Returns : TRUE if the clock is capable of being slaved to a master clock. MT safe.

gst_clock_get_master ()

GstClock*   gst_clock_get_master            (GstClock *clock);

Get the master clock that clock is slaved to or NULL when the clock is not slaved to any master clock.

clock : a GstClock
Returns : a master GstClock or NULL when this clock is not slaved to a master clock. Unref after usage. MT safe.

gst_clock_set_resolution ()

GstClockTime gst_clock_set_resolution       (GstClock *clock,
                                             GstClockTime resolution);

Set the accuracy of the clock.

clock : a GstClock
resolution : The resolution to set
Returns : the new resolution of the clock.

gst_clock_get_resolution ()

GstClockTime gst_clock_get_resolution       (GstClock *clock);

Get the accuracy of the clock.

clock : a GstClock
Returns : the resolution of the clock in units of GstClockTime. MT safe.

gst_clock_get_time ()

GstClockTime gst_clock_get_time             (GstClock *clock);

Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate.

clock : a GstClock to query
Returns : the time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input. MT safe.

gst_clock_new_single_shot_id ()

GstClockID  gst_clock_new_single_shot_id    (GstClock *clock,
                                             GstClockTime time);

Get an ID from the given clock to trigger a single shot notification at the requested time. The single shot id should be unreffed after usage.

clock : The clockid to get a single shot notification from
time : the requested time
Returns : An id that can be used to request the time notification. MT safe.

gst_clock_new_periodic_id ()

GstClockID  gst_clock_new_periodic_id       (GstClock *clock,
                                             GstClockTime start_time,
                                             GstClockTime interval);

Get an ID from the given clock to trigger a periodic notification. The periodeic notifications will be start at time start_time and will then be fired with the given interval. The id should be unreffed after usage.

clock : The clockid to get a periodic notification id from
start_time : the requested start time
interval : the requested interval
Returns : An id that can be used to request the time notification. MT safe.

gst_clock_get_internal_time ()

GstClockTime gst_clock_get_internal_time    (GstClock *clock);

Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate.

clock : a GstClock to query
Returns : the internal time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input. MT safe.

gst_clock_adjust_unlocked ()

GstClockTime gst_clock_adjust_unlocked      (GstClock *clock,
                                             GstClockTime internal);

Converts the given internal clock time to the real time, adjusting for the rate and reference time set with gst_clock_set_calibration() and making sure that the returned time is increasing. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses.

clock : a GstClock to use
internal : a clock time
Returns : the converted time of the clock. MT safe.

gst_clock_get_calibration ()

void        gst_clock_get_calibration       (GstClock *clock,
                                             GstClockTime *internal,
                                             GstClockTime *external,
                                             GstClockTime *rate_num,
                                             GstClockTime *rate_denom);

Gets the internal rate and reference time of clock. See gst_clock_set_calibration() for more information.

internal, external, rate_num, and rate_denom can be left NULL if the caller is not interested in the values.

MT safe.

clock : a GstClock
internal : a location to store the internal time
external : a location to store the external time
rate_num : a location to store the rate numerator
rate_denom : a location to store the rate denominator

gst_clock_set_calibration ()

void        gst_clock_set_calibration       (GstClock *clock,
                                             GstClockTime internal,
                                             GstClockTime external,
                                             GstClockTime rate_num,
                                             GstClockTime rate_denom);

Adjusts the rate and time of clock. A rate of 1/1 is the normal speed of the clock. Values bigger than 1/1 make the clock go faster.

internal and external are calibration parameters that arrange that gst_clock_get_time() should have been external at internal time internal. This internal time should not be in the future; that is, it should be less than the value of gst_clock_get_internal_time() when this function is called.

Subsequent calls to gst_clock_get_time() will return clock times computed as follows:

  time = (internal_time - internal) * rate_num / rate_denom + external

This formula is implemented in gst_clock_adjust_unlocked(). Of course, it tries to do the integer arithmetic as precisely as possible.

Note that gst_clock_get_time() always returns increasing values so when you move the clock backwards, gst_clock_get_time() will report the previous value until the clock catches up.

MT safe.

clock : a GstClock to calibrate
internal : a reference internal time
external : a reference external time
rate_num : the numerator of the rate of the clock relative to its internal time
rate_denom : the denominator of the rate of the clock

gst_clock_id_get_time ()

GstClockTime gst_clock_id_get_time          (GstClockID id);

Get the time of the clock ID

id : The clockid to query
Returns : the time of the given clock id. MT safe.

gst_clock_id_wait ()

GstClockReturn gst_clock_id_wait            (GstClockID id,
                                             GstClockTimeDiff *jitter);

Perform a blocking wait on the given ID. The jitter arg can be NULL.

id : The clockid to wait on
jitter : A pointer that will contain the jitter
Returns : the result of the blocking wait. MT safe.

gst_clock_id_wait_async ()

GstClockReturn gst_clock_id_wait_async      (GstClockID id,
                                             GstClockCallback func,
                                             gpointer user_data);

Register a callback on the given clockid with the given function and user_data. When passing an id with an invalid time to this function, the callback will be called immediatly with a time set to GST_CLOCK_TIME_NONE. The callback will be called when the time of the id has been reached.

id : a GstClockID to wait on
func : The callback function
user_data : User data passed in the calback
Returns : the result of the non blocking wait. MT safe.

gst_clock_id_unschedule ()

void        gst_clock_id_unschedule         (GstClockID id);

Cancel an outstanding request with the given ID. This can either be an outstanding async notification or a pending sync notification. After this call, the id cannot be used anymore to receive sync or async notifications, you need to create a new GstClockID.

MT safe.

id : The id to unschedule

gst_clock_id_compare_func ()

gint        gst_clock_id_compare_func       (gconstpointer id1,
                                             gconstpointer id2);

Compares the two GstClockID instances. This function can be used as a GCompareFunc when sorting ids.

id1 : A clockid
id2 : A clockid to compare with
Returns : negative value if a < b; zero if a = b; positive value if a > b MT safe.

gst_clock_id_ref ()

GstClockID  gst_clock_id_ref                (GstClockID id);

Increase the refcount of the given clockid.

id : The clockid to ref
Returns : The same GstClockID with increased refcount. MT safe.

gst_clock_id_unref ()

void        gst_clock_id_unref              (GstClockID id);

Unref the given clockid. When the refcount reaches 0 the GstClockID will be freed.

MT safe.

id : The clockid to unref

GST_TYPE_CLOCK_TIME

#define GST_TYPE_CLOCK_TIME G_TYPE_UINT64

The GType of a GstClockTime.

Properties

The "stats" property

  "stats"                gboolean              : Read / Write

Enable clock stats.

Default value: FALSE


The "timeout" property

  "timeout"              guint64               : Read / Write

The amount of time, in nanoseconds, to sample master and slave clocks.

Default value: 100000000


The "window-size" property

  "window-size"          gint                  : Read / Write

The size of the window used to calculate rate and offset.

Allowed values: [2,1024]

Default value: 32


The "window-threshold" property

  "window-threshold"     gint                  : Read / Write

The threshold to start calculating rate and offset.

Allowed values: [2,1024]

Default value: 4