## 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                 (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

      "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  ((guint64)-1)

Constant to define an undefined clock time

### GST_SECOND

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

Constant that defines one GStreamer second

### GST_MSECOND

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

Constant that defines one GStreamer millisecond

### GST_USECOND

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

Constant that defines one GStreamer microsecond

### GST_NSECOND

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

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_OK` | timeout happened
`GST_CLOCK_ENTRY_EARLY` | request for timout that has been passed
`GST_CLOCK_ENTRY_RESTART` | need 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_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_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_STOPPED` | The clock is stopped.
`GST_CLOCK_TIMEOUT` | The operation timed out.
`GST_CLOCK_EARLY` | The operation was scheduled too late.
`GST_CLOCK_ERROR` | An error occured
`GST_CLOCK_UNSUPPORTED` | Operation 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_SYNC` | This clock can do a single sync timeut request
`GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC` | This clock can do a single async timeout request
`GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC` | This clock can do sync periodic timeout requests
`GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC` | This clock can do async periodic timeout callbacks
`GST_CLOCK_FLAG_CAN_SET_RESOLUTION` | The resolution of this clock can be changed
`GST_CLOCK_FLAG_CAN_SET_SPEED` | The 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;

The GstClock object

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

"`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