GstClock

GstClock — Abstract class for global clocks

Synopsis


#include <gst/gst.h>


typedef     GstClockTime;
typedef     GstClockTimeDiff;
typedef     GstClockID;
#define     GST_CLOCK_TIME_NONE
#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)
struct      GstClockEntry;
gboolean    (*GstClockCallback)             (GstClock *clock,
                                             GstClockTime time,
                                             GstClockID id,
                                             gpointer user_data);
enum        GstClockEntryStatus;
enum        GstClockEntryType;
#define     GST_CLOCK_ENTRY_TRACE_NAME
#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)
struct      GstClock;
gdouble     gst_clock_set_speed             (GstClock *clock,
                                             gdouble speed);
gdouble     gst_clock_get_speed             (GstClock *clock);
guint64     gst_clock_set_resolution        (GstClock *clock,
                                             guint64 resolution);
guint64     gst_clock_get_resolution        (GstClock *clock);
void        gst_clock_set_active            (GstClock *clock,
                                             gboolean active);
gboolean    gst_clock_is_active             (GstClock *clock);
void        gst_clock_reset                 (GstClock *clock);
gboolean    gst_clock_handle_discont        (GstClock *clock,
                                             guint64 time);
GstClockTime gst_clock_get_time             (GstClock *clock);
GstClockID  gst_clock_get_next_id           (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_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);
void        gst_clock_id_unlock             (GstClockID id);
void        gst_clock_id_free               (GstClockID id);

Object Hierarchy


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

Properties


  "event-diff"           guint64              : Read / Write / Construct
  "max-diff"             gint64               : Read / Write
  "stats"                gboolean             : Read / Write

Description

GStreamer uses a global clock to synchronise the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class.

The clock time is always measured in nanoseconds, with the clock being set to 0 when the pipeline goes to READY. Usually all renderers sync to the global clock so that the clock is always a good measure of the time in the pipeline.

Details

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 detatype to hold the handle to an outstanding async clock callback


GST_CLOCK_TIME_NONE

#define GST_CLOCK_TIME_NONE  		((GstClockTime)-1)

Constant to define an undefined clock time


GST_SECOND

#define GST_SECOND  ((guint64) G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer second


GST_MSECOND

#define GST_MSECOND ((guint64) GST_SECOND / G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer millisecond


GST_USECOND

#define GST_USECOND ((guint64) GST_SECOND / G_GINT64_CONSTANT (1000000))

Constant that defines one GStreamer microsecond


GST_NSECOND

#define GST_NSECOND ((guint64) GST_SECOND / G_GINT64_CONSTANT (1000000000))

Constant that defines one GStreamer nanosecond


GST_CLOCK_DIFF()

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

Calculate a difference between to clock times.

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)

Convert a GstClockTime to a GTimeVal

t :The GstClockTime to convert
tv :The target timeval

struct GstClockEntry

struct GstClockEntry {

  /* --- protected --- */
  GstClock	 	*clock;
  GstClockEntryType 	 type;
  GstClockTime 		 time;
  GstClockTime 		 interval;
  GstClockEntryStatus 	 status;
  GstClockCallback 	 func;
  gpointer		 user_data;
};

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


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 id that expired
user_data :user data passed in the async_wait call
Returns :

enum GstClockEntryStatus

typedef enum {
  /* --- protected --- */
  GST_CLOCK_ENTRY_OK,
  GST_CLOCK_ENTRY_EARLY,
  GST_CLOCK_ENTRY_RESTART
} GstClockEntryStatus;

The status of a clock timeout.

GST_CLOCK_ENTRY_OKtimeout happened
GST_CLOCK_ENTRY_EARLYrequest for timout that has been passed
GST_CLOCK_ENTRY_RESTARTneed to restart the timeout request

enum GstClockEntryType

typedef enum {
  /* --- protected --- */
  GST_CLOCK_ENTRY_SINGLE,
  GST_CLOCK_ENTRY_PERIODIC
} GstClockEntryType;

The type of the clock entry

GST_CLOCK_ENTRY_SINGLEa single shot timeout
GST_CLOCK_ENTRY_PERIODICa periodic timeout request

GST_CLOCK_ENTRY_TRACE_NAME

#define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"

The name used for tracing clock entry allocations.


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_STOPPED 	= 0,
  GST_CLOCK_TIMEOUT 	= 1,
  GST_CLOCK_EARLY 	= 2,
  GST_CLOCK_ERROR 	= 3,
  GST_CLOCK_UNSUPPORTED	= 4
} GstClockReturn;

The return value of a clock operation.

GST_CLOCK_STOPPEDThe clock is stopped.
GST_CLOCK_TIMEOUTThe operation timed out.
GST_CLOCK_EARLYThe operation was scheduled too late.
GST_CLOCK_ERRORAn error occured
GST_CLOCK_UNSUPPORTEDOperation is not supported

enum GstClockFlags

typedef enum
{
  GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (1 << 1),
  GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (1 << 2),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (1 << 3),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (1 << 4),
  GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (1 << 5),
  GST_CLOCK_FLAG_CAN_SET_SPEED          = (1 << 6)
} GstClockFlags;

The capabilities of this clock

GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNCThis clock can do a single sync timeut request
GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNCThis clock can do a single async timeout request
GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNCThis clock can do sync periodic timeout requests
GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNCThis clock can do async periodic timeout callbacks
GST_CLOCK_FLAG_CAN_SET_RESOLUTIONThe resolution of this clock can be changed
GST_CLOCK_FLAG_CAN_SET_SPEEDThe speed of this clock can be changed

GST_CLOCK_FLAGS()

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

Get the clock flags

clock :the clock to query

struct GstClock

struct GstClock;


gst_clock_set_speed ()

gdouble     gst_clock_set_speed             (GstClock *clock,
                                             gdouble speed);

Sets the speed on the given clock. 1.0 is the default speed.

clock : a GstClock to modify
speed : the speed to set on the clock
Returns : the new speed of the clock.

gst_clock_get_speed ()

gdouble     gst_clock_get_speed             (GstClock *clock);

Gets the speed of the given clock.

clock : a GstClock to query
Returns : the speed of the clock.

gst_clock_set_resolution ()

guint64     gst_clock_set_resolution        (GstClock *clock,
                                             guint64 resolution);

Set the accuracy of the clock.

clock : The clock set the resolution on
resolution : The resolution to set
Returns : the new resolution of the clock.

gst_clock_get_resolution ()

guint64     gst_clock_get_resolution        (GstClock *clock);

Get the accuracy of the clock.

clock : The clock get the resolution of
Returns : the resolution of the clock in microseconds.

gst_clock_set_active ()

void        gst_clock_set_active            (GstClock *clock,
                                             gboolean active);

Activates or deactivates the clock based on the active parameter. As soon as the clock is activated, the time will start ticking.

clock : a GstClock to set state of
active : flag indicating if the clock should be activated (TRUE) or deactivated

gst_clock_is_active ()

gboolean    gst_clock_is_active             (GstClock *clock);

Checks if the given clock is active.

clock : a GstClock to query
Returns : TRUE if the clock is active.

gst_clock_reset ()

void        gst_clock_reset                 (GstClock *clock);

Reset the clock to time 0.

clock : a GstClock to reset

gst_clock_handle_discont ()

gboolean    gst_clock_handle_discont        (GstClock *clock,
                                             guint64 time);

Notifies the clock of a discontinuity in time.

clock : a GstClock to notify of the discontinuity
time : The new time
Returns : TRUE if the clock was updated. It is possible that the clock was not updated by this call because only the first discontinuitity in the pipeline is honoured.

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.

clock : a GstClock to query
Returns : the time of the clock.

gst_clock_get_next_id ()

GstClockID  gst_clock_get_next_id           (GstClock *clock);

Get the clockid of the next event.

clock : The clock to query
Returns : a clockid or NULL is no event is pending.

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.

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.

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.

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.

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

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.

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.

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.

gst_clock_id_unschedule ()

void        gst_clock_id_unschedule         (GstClockID id);

Cancel an outstanding async notification request with the given ID.

id : The id to unschedule

gst_clock_id_unlock ()

void        gst_clock_id_unlock             (GstClockID id);

Unlock the givan ClockID.

id : The clockid to unlock

gst_clock_id_free ()

void        gst_clock_id_free               (GstClockID id);

Free the resources held by the given id

id : The clockid to free

Properties

"event-diff" (guint64 : Read / Write / Construct)

The amount of time that may elapse until 2 events are treated as happening at different times.

"max-diff" (gint64 : Read / Write)

Maximum allowed diff for clock sync requests against the real time.

"stats" (gboolean : Read / Write)

Boolean property to activate stat generation on the clock.

See Also

GstSystemClock