Clock

Object Hierarchy:

Description:

[ CCode ( type_id = "gst_clock_get_type ()" ) ]
public abstract class Clock : Object

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

The Clock returns a monotonically increasing time with the method 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 SEGMENT events and the element's base time, see Pipeline.

A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous.

One first needs to create a ClockID for the periodic or single shot notification using new_single_shot_id or new_periodic_id.

To perform a blocking wait for the specific time of the ClockID use id_wait. To receive a callback when the specific time is reached in the clock use id_wait_async. Both these calls can be interrupted with the id_unschedule call. If the blocking wait is unscheduled a return value of UNSCHEDULED is returned.

Periodic callbacks scheduled async will be repeatedly called automatically until they are unscheduled. To schedule a sync periodic callback, 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 ClockID that has been unscheduled cannot be used again for any wait operation, a new ClockID should be created and the old unscheduled one should be destroyed with id_unref.

It is possible to perform a blocking wait on the same ClockID from multiple threads. However, registering the same ClockID 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 ClockID, 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 ClockID has to keep a handle to the ClockID 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 CAN_SET_MASTER flag set, it can be slaved to another Clock with 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 set_calibration. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the Pipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the 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.

All known sub-classes:

SystemClock

Namespace: Gst

Package: gstreamer-1.0

Content:

Properties:

public uint64 timeout { get; set; }
public int window_size { get; set; }
public int window_threshold { get; set; }

Static methods:

public static int id_compare_func (void* id1, void* id2)
Compares the two ClockID instances.
public static Clock? id_get_clock (ClockID id)
This function returns the underlying clock.
public static ClockTime id_get_time (ClockID id)
Gets the time of the clock ID
public static ClockID id_ref (ClockID id)
Increases the refcount of given id.
public static void id_unref (owned ClockID id)
Unrefs given id.
public static void id_unschedule (ClockID id)
Cancels an outstanding request with id.
public static bool id_uses_clock (ClockID id, Clock clock)
This function returns whether id uses clock as the underlying clock.
public static ClockReturn id_wait (ClockID id, out ClockTimeDiff jitter)
Performs a blocking wait on id.
public static ClockReturn id_wait_async (ClockID id, owned ClockCallback func)
Registers a callback on the given ClockID id with the given function and user_data.

Creation methods:

protected Clock ()

Methods:

public bool add_observation (ClockTime slave, ClockTime master, out double r_squared)
The time master of the master clock and the time slave of the slave clock are added to the list of observations.
public bool add_observation_unapplied (ClockTime slave, ClockTime master, out double r_squared, out ClockTime @internal, out ClockTime external, out ClockTime rate_num, out ClockTime rate_denom)
Add a clock observation to the internal slaving algorithm the same as add_observation, and return the result of the master clock estimation, without updating the internal calibration.
public ClockTime adjust_unlocked (ClockTime @internal)
Converts the given internal clock time to the external time, adjusting for the rate and reference time set with set_calibration and making sure that the returned time is increasing.
public ClockTime adjust_with_calibration (ClockTime internal_target, ClockTime cinternal, ClockTime cexternal, ClockTime cnum, ClockTime cdenom)
Converts the given internal_target clock time to the external time, using the passed calibration parameters.
public virtual ClockTime change_resolution (ClockTime old_resolution, ClockTime new_resolution)
Change the resolution of the clock.
public void get_calibration (out ClockTime @internal, out ClockTime external, out ClockTime rate_num, out ClockTime rate_denom)
Gets the internal rate and reference time of this .
public virtual ClockTime get_internal_time ()
Gets the current internal time of the given clock.
public Clock? get_master ()
Gets the master clock that this is slaved to or null when the clock is not slaved to any master clock.
public virtual ClockTime get_resolution ()
Gets the accuracy of the clock.
public ClockTime get_time ()
Gets the current time of the given clock.
public ClockTime get_timeout ()
Gets the amount of time that master and slave clocks are sampled.
public bool is_synced ()
Checks if the clock is currently synced, by looking at whether NEEDS_STARTUP_SYNC is set.
public ClockID new_periodic_id (ClockTime start_time, ClockTime interval)
Gets an ID from this to trigger a periodic notification.
public ClockID new_single_shot_id (ClockTime time)
Gets a ClockID from this to trigger a single shot notification at the requested time.
public bool periodic_id_reinit (ClockID id, ClockTime start_time, ClockTime interval)
Reinitializes the provided periodic id to the provided start time and interval.
public void set_calibration (ClockTime @internal, ClockTime external, ClockTime rate_num, ClockTime rate_denom)
Adjusts the rate and time of this.
public bool set_master (Clock? master)
Sets master as the master clock for this.
public ClockTime set_resolution (ClockTime resolution)
Sets the accuracy of the clock.
public void set_synced (bool synced)
Sets this to synced and emits the synced signal, and wakes up any thread waiting in wait_for_sync.
public void set_timeout (ClockTime timeout)
Sets the amount of time, in nanoseconds, to sample master and slave clocks
public bool single_shot_id_reinit (ClockID id, ClockTime time)
Reinitializes the provided single shot id to the provided time.
public ClockTime unadjust_unlocked (ClockTime external)
Converts the given external clock time to the internal time of this, using the rate and reference time set with set_calibration.
public ClockTime unadjust_with_calibration (ClockTime external_target, ClockTime cinternal, ClockTime cexternal, ClockTime cnum, ClockTime cdenom)
Converts the given external_target clock time to the internal time, using the passed calibration parameters.
public virtual void unschedule (ClockEntry entry)
Unblock a blocking or async wait operation.
public virtual ClockReturn wait (ClockEntry entry, out ClockTimeDiff jitter)
Perform a blocking wait on the given ClockEntry and return the jitter.
public virtual ClockReturn wait_async (ClockEntry entry)
Perform an asynchronous wait on the given ClockEntry.
public bool wait_for_sync (ClockTime timeout)
Waits until this is synced for reporting the current time.

Signals:

public signal void synced (bool synced)
Signaled on clocks with NEEDS_STARTUP_SYNC set once the clock is synchronized, or when it completely lost synchronization.

Inherited Members:

All known members inherited from class Gst.Object

All known members inherited from class GLib.Object