Properties

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.

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.

gst_clock_add_observation ()

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.

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

gst_clock_adjust_unlocked ()

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.

gst_clock_unadjust_unlocked ()

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.

gst_clock_set_calibration ()

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.

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.

gst_clock_id_wait_async ()

Register a callback on the given GstClockIDid 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.

gst_clock_id_unschedule ()

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.