## GstClock GstClock — Abstract class for global clocks |

## Functions

#define | GST_CLOCK_TIME_IS_VALID()
#define | GST_CLOCK_STIME_IS_VALID()
#define | GST_TIME_AS_SECONDS()
#define | GST_TIME_AS_MSECONDS()
#define | GST_TIME_AS_USECONDS()
#define | GST_TIME_AS_NSECONDS()
#define | GST_CLOCK_DIFF()
#define | GST_TIMEVAL_TO_TIME()
#define | GST_TIME_TO_TIMEVAL()
#define | GST_TIMESPEC_TO_TIME()
#define | GST_TIME_TO_TIMESPEC()
gboolean | (*GstClockCallback) ()
#define | GST_CLOCK_ENTRY()
#define | GST_CLOCK_ENTRY_CLOCK()
#define | GST_CLOCK_ENTRY_TYPE()
#define | GST_CLOCK_ENTRY_TIME()
#define | GST_CLOCK_ENTRY_INTERVAL()
#define | GST_CLOCK_ENTRY_STATUS()
#define | GST_CLOCK_FLAGS()
gboolean | gst_clock_add_observation ()
gboolean | gst_clock_add_observation_unapplied ()
gboolean | gst_clock_set_master ()
GstClock * | gst_clock_get_master ()
GstClockTime | gst_clock_set_resolution ()
GstClockTime | gst_clock_get_resolution ()
GstClockTime | gst_clock_get_time ()
GstClockID | gst_clock_new_single_shot_id ()
GstClockID | gst_clock_new_periodic_id ()
gboolean | gst_clock_single_shot_id_reinit ()
gboolean | gst_clock_periodic_id_reinit ()
GstClockTime | gst_clock_get_internal_time ()
GstClockTime | gst_clock_adjust_unlocked ()
GstClockTime | gst_clock_unadjust_unlocked ()
GstClockTime | gst_clock_adjust_with_calibration ()
GstClockTime | gst_clock_unadjust_with_calibration ()
void | gst_clock_get_calibration ()
void | gst_clock_set_calibration ()
GstClockTime | gst_clock_get_timeout ()
void | gst_clock_set_timeout ()
gboolean | gst_clock_wait_for_sync ()
gboolean | gst_clock_is_synced ()
void | gst_clock_set_synced ()
GstClockTime | gst_clock_id_get_time ()
GstClockReturn | gst_clock_id_wait ()
GstClockReturn | gst_clock_id_wait_async ()
void | gst_clock_id_unschedule ()
gint | gst_clock_id_compare_func ()
GstClockID | gst_clock_id_ref ()
void | gst_clock_id_unref ()

## Properties

guint64 | timeout | Read / Write
gint | window-size | Read / Write
gint | window-threshold | Read / Write

## Signals

void | synced | Run Last

## Types and Values

struct | GstClock
struct | GstClockClass
typedef | GstClockTime
typedef | GstClockTimeDiff
typedef | GstClockID
#define | GST_CLOCK_TIME_NONE
#define | GST_CLOCK_STIME_NONE
#define | GST_SECOND
#define | GST_MSECOND
#define | GST_USECOND
#define | GST_NSECOND
struct | GstClockEntry
enum | GstClockEntryType
enum | GstClockReturn
enum | GstClockFlags

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstClock
                    ╰── GstSystemClock

## Includes

    #include <gst/gst.h>

## Description

GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class or, more conveniently, by subclassing GstSystemClock.

The GstClock returns a monotonically increasing time with the method `gst_clock_get_time()`. Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds. Since the baseline of the clock is undefined, the clock time returned is not meaningful in itself, what matters are the deltas between two clock times. The time returned by a clock is called the absolute time.

The pipeline uses the clock to calculate the running time. Usually all renderers synchronize to the global clock using the buffer timestamps, the newsegment events and the element's base time, see GstPipeline.

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.

Periodic callbacks scheduled async will be repeatedly called automatically until it is unscheduled. To schedule a sync periodic callback, `gst_clock_id_wait()` should be called repeatedly.

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, a new GstClockID should be created and the old unscheduled one should be destroyed with `gst_clock_id_unref()`.

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 for the thread registering the entry last.

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 the entry would be unreffed automatically, the handle might become invalid without any notification.

These clock operations do not operate on the running 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.

When a clock has the GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be slaved to another GstClock with the `gst_clock_set_master()`. The clock will then automatically be synchronized to this master clock by repeatedly sampling the master clock and the slave clock and recalibrating the slave clock with `gst_clock_set_calibration()`. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the GstPipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the `gst_clock_get_calibration()` function.

The master/slave synchronisation can be tuned with the “timeout”, “window-size” and “window-threshold” properties. The “timeout” property defines the interval to sample the master clock and run the calibration functions. “window-size” defines the number of samples to use when calibrating and “window-threshold” defines the minimum number of samples before the calibration is performed.

## Functions

### GST_CLOCK_TIME_IS_VALID()

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

Tests if a given GstClockTime represents a valid defined time.

#### Parameters

time | clock time to validate |

### GST_CLOCK_STIME_IS_VALID()

    #define GST_CLOCK_STIME_IS_VALID(time)   (((GstClockTimeDiff)(time)) != GST_CLOCK_STIME_NONE)

Tests if a given GstClockTimeDiff of gint64 represents a valid defined time.

#### Parameters

time | signed clock time to validate |

Since: 1.6

### GST_TIME_AS_SECONDS()

    #define GST_TIME_AS_SECONDS(time)  ((time) / GST_SECOND)

Convert a GstClockTime to seconds.

#### Parameters

time | the time |

### GST_TIME_AS_MSECONDS()

    #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))

Convert a GstClockTime to milliseconds (1/1000 of a second).

#### Parameters

time | the time |

### GST_TIME_AS_USECONDS()

    #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))

Convert a GstClockTime to microseconds (1/1000000 of a second).

#### Parameters

time | the time |

### GST_TIME_AS_NSECONDS()

    #define GST_TIME_AS_NSECONDS(time) (time)

Convert a GstClockTime to nanoseconds (1/1000000000 of a second).

#### Parameters

time | the time |

### GST_CLOCK_DIFF()

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

Calculate a difference between two clock times as a GstClockTimeDiff. The difference is calculated as `e` - `s` .

#### Parameters

s | the first time |
e | the second time |

### GST_TIMEVAL_TO_TIME()

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

Convert a GTimeVal to a GstClockTime.

#### Parameters

tv | the timeval to convert |

### GST_TIME_TO_TIMEVAL()

    #define             GST_TIME_TO_TIMEVAL(t,tv)

Convert a GstClockTime to a GTimeVal

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

#### Parameters

t | The GstClockTime to convert |
tv | The target timeval |

### GST_TIMESPEC_TO_TIME()

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

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

#### Parameters

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)

#### Parameters

t | The GstClockTime to convert |
ts | The target timespec |

### GstClockCallback ()

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

The function prototype of the callback.

#### Parameters

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 `gst_clock_id_wait_async()` function |

#### Returns

`TRUE` or `FALSE` (currently unused)

### GST_CLOCK_ENTRY()

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

Cast to a clock entry

#### Parameters

entry | the entry to cast |

### GST_CLOCK_ENTRY_CLOCK()

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

Get the owner clock of the entry

#### Parameters

entry | the entry to query |

### GST_CLOCK_ENTRY_TYPE()

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

Get the type of the clock entry

#### Parameters

entry | the entry to query |

### GST_CLOCK_ENTRY_TIME()

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

Get the requested time of this entry

#### Parameters

entry | the entry to query |

### GST_CLOCK_ENTRY_INTERVAL()

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

Get the interval of this periodic entry

#### Parameters

entry | the entry to query |

### GST_CLOCK_ENTRY_STATUS()

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

The status of the entry

#### Parameters

entry | the entry to query |

### GST_CLOCK_FLAGS()

    #define GST_CLOCK_FLAGS(clock)  GST_OBJECT_FLAGS(clock)

Gets the GstClockFlags clock flags.

#### Parameters

clock | the clock to query |

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

If this functions returns `TRUE`, `r_squared` will contain the correlation coefficient of the interpolation. A value of 1.0 means a perfect regression was performed. This value can be used to control the sampling frequency of the master and slave clocks.

#### Parameters

clock | a GstClock |
slave | a time on the slave |
master | a time on the master |
r_squared | a pointer to hold the result. | [out]

#### Returns

`TRUE` if enough observations were added to run the regression algorithm.

MT safe.

### gst_clock_add_observation_unapplied ()

    gboolean
    gst_clock_add_observation_unapplied (GstClock *clock,
                                         GstClockTime slave,
                                         GstClockTime master,
                                         gdouble *r_squared,
                                         GstClockTime *internal,
                                         GstClockTime *external,
                                         GstClockTime *rate_num,
                                         GstClockTime *rate_denom);

Add a clock observation to the internal slaving algorithm the same as `gst_clock_add_observation()`, and return the result of the master clock estimation, without updating the internal calibration.

The caller can then take the results and call `gst_clock_set_calibration()` with the values, or some modified version of them.

#### Parameters

clock | a GstClock |
slave | a time on the slave |
master | a time on the master |
r_squared | a pointer to hold the result. | [out]
internal | a location to store the internal time. | [out][allow-none]
external | a location to store the external time. | [out][allow-none]
rate_num | a location to store the rate numerator. | [out][allow-none]
rate_denom | a location to store the rate denominator. | [out][allow-none]

Since: 1.6

### 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()`.

`master` can be `NULL` in which case `clock` will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets.

#### Parameters

clock | a GstClock |
master | a master GstClock. | [allow-none]

#### Returns

`TRUE` if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return `FALSE`.

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.

#### Parameters

clock | a GstClock |

#### Returns

a master GstClock or `NULL` when this clock is not slaved to a master clock. Unref after usage.

MT safe.

[transfer full][nullable]

### gst_clock_set_resolution ()

    GstClockTime
    gst_clock_set_resolution (GstClock *clock,
                              GstClockTime resolution);

Set the accuracy of the clock. Some clocks have the possibility to operate with different accuracy at the expense of more resource usage. There is normally no need to change the default resolution of a clock. The resolution of a clock can only be changed if the clock has the GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set.

#### Parameters

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. The accuracy of the clock is the granularity of the values returned by `gst_clock_get_time()`.

#### Parameters

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.

#### Parameters

clock | a GstClock to query |

#### Returns

the time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input.

MT safe.

### gst_clock_new_single_shot_id ()

    GstClockID
    gst_clock_new_single_shot_id (GstClock *clock,
                                  GstClockTime time);

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

Free-function: gst_clock_id_unref

#### Parameters

clock | The GstClockID to get a single shot notification from |
time | the requested time |

#### Returns

a GstClockID that can be used to request the time notification.

MT safe.

[transfer full]

### gst_clock_new_periodic_id ()

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

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

Free-function: gst_clock_id_unref

#### Parameters

clock | The GstClockID to get a periodic notification id from |
start_time | the requested start time |
interval | the requested interval |

#### Returns

a GstClockID that can be used to request the time notification.

MT safe.

[transfer full]

### gst_clock_single_shot_id_reinit ()

    gboolean
    gst_clock_single_shot_id_reinit (GstClock *clock,
                                     GstClockID id,
                                     GstClockTime time);

Reinitializes the provided single shot `id` to the provided time. Does not modify the reference count.

#### Parameters

clock | a GstClock |
id | a GstClockID |
time | The requested time. |

#### Returns

`TRUE` if the GstClockID could be reinitialized to the provided `time` , else `FALSE`.

### gst_clock_periodic_id_reinit ()

    gboolean
    gst_clock_periodic_id_reinit (GstClock *clock,
                                  GstClockID id,
                                  GstClockTime start_time,
                                  GstClockTime interval);

Reinitializes the provided periodic `id` to the provided start time and interval. Does not modify the reference count.

#### Parameters

clock | a GstClock |
id | a GstClockID |
start_time | the requested start time |
interval | the requested interval |

#### Returns

`TRUE` if the GstClockID could be reinitialized to the provided `time` , else `FALSE`.

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

#### Parameters

clock | a GstClock to query |

#### Returns

the internal time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input.

MT safe.

### gst_clock_adjust_unlocked ()

    GstClockTime
    gst_clock_adjust_unlocked (GstClock *clock,
                               GstClockTime internal);

Converts the given `internal` clock time to the external 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.

This function is the reverse of `gst_clock_unadjust_unlocked()`.

#### Parameters

clock | a GstClock to use |
internal | a clock time |

#### Returns

the converted time of the clock.

### gst_clock_unadjust_unlocked ()

    GstClockTime
    gst_clock_unadjust_unlocked (GstClock *clock,
                                 GstClockTime external);

Converts the given `external` clock time to the internal time of `clock` , using the rate and reference time set with `gst_clock_set_calibration()`. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses.

This function is the reverse of `gst_clock_adjust_unlocked()`.

#### Parameters

clock | a GstClock to use |
external | an external clock time |

#### Returns

the internal time of the clock corresponding to `external` .

### gst_clock_adjust_with_calibration ()

    GstClockTime
    gst_clock_adjust_with_calibration (GstClock *clock,
                                       GstClockTime internal_target,
                                       GstClockTime cinternal,
                                       GstClockTime cexternal,
                                       GstClockTime cnum,
                                       GstClockTime cdenom);

Converts the given `internal_target` clock time to the external time, using the passed calibration parameters. This function performs the same calculation as `gst_clock_adjust_unlocked()` when called using the current calibration parameters, but doesn't ensure a monotonically increasing result as `gst_clock_adjust_unlocked()` does.

Note: The `clock` parameter is unused and can be NULL

#### Parameters

clock | a GstClock to use. | [allow-none]
internal_target | a clock time |
cinternal | a reference internal time |
cexternal | a reference external time |
cnum | the numerator of the rate of the clock relative to its internal time |
cdenom | the denominator of the rate of the clock |

#### Returns

the converted time of the clock.

Since: 1.6

### gst_clock_unadjust_with_calibration ()

    GstClockTime
    gst_clock_unadjust_with_calibration (GstClock *clock,
                                         GstClockTime external_target,
                                         GstClockTime cinternal,
                                         GstClockTime cexternal,
                                         GstClockTime cnum,
                                         GstClockTime cdenom);

Converts the given `external_target` clock time to the internal time, using the passed calibration parameters. This function performs the same calculation as `gst_clock_unadjust_unlocked()` when called using the current calibration parameters.

Note: The `clock` parameter is unused and can be NULL

#### Parameters

clock | a GstClock to use. | [allow-none]
external_target | a clock time |
cinternal | a reference internal time |
cexternal | a reference external time |
cnum | the numerator of the rate of the clock relative to its internal time |
cdenom | the denominator of the rate of the clock |

#### Returns

the converted time of the clock.

Since: 1.8

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

#### Parameters

clock | a GstClock |
internal | a location to store the internal time. | [out][allow-none]
external | a location to store the external time. | [out][allow-none]
rate_num | a location to store the rate numerator. | [out][allow-none]
rate_denom | a location to store the rate denominator. | [out][allow-none]

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

    1
    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.

#### Parameters

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_get_timeout ()

    GstClockTime
    gst_clock_get_timeout (GstClock *clock);

Get the amount of time that master and slave clocks are sampled.

#### Parameters

clock | a GstClock |

#### Returns

the interval between samples.

### gst_clock_set_timeout ()

    void
    gst_clock_set_timeout (GstClock *clock,
                           GstClockTime timeout);

Set the amount of time, in nanoseconds, to sample master and slave clocks

#### Parameters

clock | a GstClock |
timeout | a timeout |

### gst_clock_wait_for_sync ()

    gboolean
    gst_clock_wait_for_sync (GstClock *clock,
                             GstClockTime timeout);

Waits until `clock` is synced for reporting the current time. If `timeout` is `GST_CLOCK_TIME_NONE` it will wait forever, otherwise it will time out after `timeout` nanoseconds.

For asynchronous waiting, the GstClock::synced signal can be used.

This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock, or if the clock is already synced.

#### Parameters

clock | a GstClock |
timeout | timeout for waiting or `GST_CLOCK_TIME_NONE` |

#### Returns

`TRUE` if waiting was successful, or `FALSE` on timeout

Since: 1.6

### gst_clock_is_synced ()

    gboolean
    gst_clock_is_synced (GstClock *clock);

Checks if the clock is currently synced.

This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock.

#### Parameters

clock | a GstClock |

#### Returns

`TRUE` if the clock is currently synced

Since: 1.6

### gst_clock_set_synced ()

    void
    gst_clock_set_synced (GstClock *clock,
                          gboolean synced);

Sets `clock` to synced and emits the GstClock::synced signal, and wakes up any thread waiting in `gst_clock_wait_for_sync()`.

This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set on the clock, and is intended to be called by subclasses only.

#### Parameters

clock | a GstClock |
synced | if the clock is synced |

Since: 1.6

### gst_clock_id_get_time ()

    GstClockTime
    gst_clock_id_get_time (GstClockID id);

Get the time of the clock ID

#### Parameters

id | The GstClockID 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 `id` . `id` should have been created with `gst_clock_new_single_shot_id()` or `gst_clock_new_periodic_id()` and should not have been unscheduled with a call to `gst_clock_id_unschedule()`.

If the `jitter` argument is not `NULL` and this function returns GST_CLOCK_OK or GST_CLOCK_EARLY, it will contain the difference against the clock and the time of `id` when this method was called. Positive values indicate how late `id` was relative to the clock (in which case this function will return GST_CLOCK_EARLY). Negative values indicate how much time was spent waiting on the clock before this function returned.

#### Parameters

id | The GstClockID to wait on |
jitter | a pointer that will contain the jitter, can be `NULL`. | [out][allow-none]

#### Returns

the result of the blocking wait. GST_CLOCK_EARLY will be returned if the current clock time is past the time of `id` , GST_CLOCK_OK if `id` was scheduled in time. GST_CLOCK_UNSCHEDULED if `id` was unscheduled with `gst_clock_id_unschedule()`.

MT safe.

### gst_clock_id_wait_async ()

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

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

The callback `func` can be invoked from any thread, either provided by the core or from a streaming thread. The application should be prepared for this.

#### Parameters

id | a GstClockID to wait on |
func | The callback function |
user_data | User data passed in the callback |
destroy_data | GDestroyNotify for user_data |

#### 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 `id` . This can either be an outstanding async notification or a pending sync notification. After this call, `id` cannot be used anymore to receive sync or async notifications, you need to create a new GstClockID.

MT safe.

#### Parameters

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.

#### Parameters

id1 | A GstClockID |
id2 | A GstClockID 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 given `id` .

#### Parameters

id | The GstClockID to ref |

#### Returns

The same GstClockID with increased refcount.

MT safe.

[transfer full]

### gst_clock_id_unref ()

    void
    gst_clock_id_unref (GstClockID id);

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

MT safe.

#### Parameters

id | The GstClockID to unref. | [transfer full]

## Types and Values

### struct GstClock

    struct GstClock;

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

### struct GstClockClass

    struct GstClockClass {
      GstObjectClass        parent_class;

      /* vtable */
      GstClockTime          (*change_resolution)    (GstClock *clock,
                                                     GstClockTime old_resolution,
                                                     GstClockTime new_resolution);
      GstClockTime          (*get_resolution)       (GstClock *clock);

      GstClockTime          (*get_internal_time)    (GstClock *clock);

      /* waiting on an ID */
      GstClockReturn        (*wait)                 (GstClock *clock, GstClockEntry *entry,
                                                     GstClockTimeDiff *jitter);
      GstClockReturn        (*wait_async)           (GstClock *clock, GstClockEntry *entry);
      void                  (*unschedule)           (GstClock *clock, GstClockEntry *entry);
    };

GStreamer clock class. Override the vmethods to implement the clock functionality.

#### Members

`change_resolution` () | change the resolution of the clock. Not all values might be acceptable. The new resolution should be returned. |
`get_resolution` () | get the resolution of the clock. |
`get_internal_time` () | get the internal unadjusted time of the clock. implement `wait_jitter` instead. |
`wait` () | perform a blocking wait on the given GstClockEntry and return the jitter. |
`wait_async` () | perform an asynchronous wait for the given GstClockEntry. |
`unschedule` () | unblock a blocking or async wait operation. |

### GstClockTime

    typedef guint64 GstClockTime;

A datatype to hold a time, measured in nanoseconds.

### GstClockTimeDiff

    typedef gint64 GstClockTimeDiff;

A datatype to hold a time difference, 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_STIME_NONE

    #define GST_CLOCK_STIME_NONE             ((GstClockTimeDiff)G_MININT64)

Constant to define an undefined clock time.

### GST_SECOND

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

Constant that defines one GStreamer second.

### GST_MSECOND

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

Constant that defines one GStreamer millisecond.

### GST_USECOND

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

Constant that defines one GStreamer microsecond.

### GST_NSECOND

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

Constant that defines one GStreamer nanosecond

### struct GstClockEntry

    struct GstClockEntry {
      gint                  refcount;
    };

All pending timeouts or periodic notifies are converted into an entry. Note that GstClockEntry should be treated as an opaque structure. It must not be extended or allocated using a custom allocator.

#### Members

gint `refcount`; | reference counter (read-only) |

### enum GstClockEntryType

The type of the clock entry

#### Members

GST_CLOCK_ENTRY_SINGLE | a single shot timeout |
GST_CLOCK_ENTRY_PERIODIC | a periodic timeout request |

### enum GstClockReturn

The return value of a clock operation.

#### Members

GST_CLOCK_OK | The operation succeeded. |
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 occurred |
GST_CLOCK_UNSUPPORTED | Operation is not supported |
GST_CLOCK_DONE | The ClockID is done waiting |

### enum GstClockFlags

The capabilities of this clock

#### Members

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_NEEDS_STARTUP_SYNC | clock needs to be synced before it can be used (Since 1.6) |
GST_CLOCK_FLAG_LAST | subclasses can add additional flags starting from this flag |

## Property Details

### The `“timeout”` property

      “timeout”                  guint64

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

Flags: Read / Write

Default value: 100000000

### The `“window-size”` property

      “window-size”              gint

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

Flags: Read / Write

Allowed values: [2,1024]

Default value: 32

### The `“window-threshold”` property

      “window-threshold”         gint

The threshold to start calculating rate and offset.

Flags: Read / Write

Allowed values: [2,1024]

Default value: 4

## Signal Details

### The `“synced”` signal

    void
    user_function (GstClock *clock,
                   gboolean  synced,
                   gpointer  user_data)

Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once the clock is synchronized, or when it completely lost synchronization. This signal will not be emitted on clocks without the flag.

This signal will be emitted from an arbitrary thread, most likely not the application's main thread.

#### Parameters

clock | the clock |
synced | if the clock is synced now |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.6

## See Also

GstSystemClock, GstPipeline