org.gstreamer
Class Clock

java.lang.Object
  org.gstreamer.lowlevel.NativeValue
      org.gstreamer.lowlevel.Handle
          org.gstreamer.lowlevel.NativeObject
              org.gstreamer.lowlevel.RefCountedObject
                  org.gstreamer.GObject
                      org.gstreamer.GstObject
                          org.gstreamer.Clock

public class Clock
extends GstObject

Abstract class for global clocks.

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

The Clock 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 stream 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 ClockID for the periodic or single shot notification using newSingleShotID(org.gstreamer.ClockTime) or newPeriodicID(org.gstreamer.ClockTime, org.gstreamer.ClockTime).

To perform a blocking wait for the specific time of the ClockID 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 repeadedly called automatically until it is unscheduled. To schedule a sync periodic callback, gst_clock_id_wait() should be called repeadedly.

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.

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.

These clock operations do not operate on the stream time, so the callbacks will also occur when not in State.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 State.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 repeadedly sampling the master clock and the slave clock and recalibrating the slave clock with setCalibration(org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime). 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 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.

Nested Class Summary

Nested classes/interfaces inherited from class org.gstreamer.GObject

GObject.GCallback

Nested classes/interfaces inherited from class org.gstreamer.lowlevel.NativeObject

NativeObject.Initializer

Field Summary

Fields inherited from class org.gstreamer.lowlevel.NativeObject

defaultInit, ownsHandle

Constructor Summary

Clock(NativeObject.Initializer init)

Method Summary

void	getCalibration(ClockTime internal, ClockTime external, ClockTime rateNumerator, ClockTime rateDenominator) Gets the internal rate and reference time of clock.
ClockTime	getInternalTime() Gets the current internal time of this clock.
Clock	getMaster() Gets the master clock that this clock is slaved to or null when the clock is not slaved to any master clock.
ClockTime	getResolution() Gets the accuracy of the clock.
ClockTime	getTime() Gets the current time of the given clock.
ClockID	newPeriodicID(ClockTime startTime, ClockTime interval) Gets an ID from this clock to trigger a periodic notification.
ClockID	newSingleShotID(ClockTime time) Gets a ClockID from this clock to trigger a single shot notification at the requested time.
void	setCalibration(ClockTime internal, ClockTime external, ClockTime rateNumerator, ClockTime rateDenominator) Adjusts the rate and time of this clock.
boolean	setMaster(Clock master) Set master as the master clock for this clock.
ClockTime	setResolution(ClockTime resolution) Sets the accuracy of the clock.

Methods inherited from class org.gstreamer.GstObject

addListenerProxy, getName, getParent, initializer, initializer, objectFor, objectFor, ref, removeListenerProxy, setName, steal, toString, unref

Methods inherited from class org.gstreamer.GObject

addCallback, connect, connect, connect, disconnect, disconnect, disposeNativeHandle, g_signal_connect, get, getPointer, getPropertyDefaultValue, getPropertyMaximumValue, getPropertyMinimumValue, invalidate, objectFor, removeCallback, set

Methods inherited from class org.gstreamer.lowlevel.NativeObject

classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, isDisposed, nativeValue, objectFor, objectFor

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Clock

public Clock(NativeObject.Initializer init)

Method Detail

setResolution

public ClockTime setResolution(ClockTime resolution)

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

resolution - the new resolution of the clock.

Returns:

the new resolution of the clock.

getResolution

public ClockTime getResolution()

Gets the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by getTime().

Returns:

the resolution of the clock in nanoseconds.

getTime

public ClockTime getTime()

Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate. Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input.

Returns:

the time of the clock. Or ClockTime.NONE when given incorrect input.

getInternalTime

public ClockTime getInternalTime()

Gets the current internal time of this clock. The time is returned unadjusted for the offset and the rate. Thread safe.

Returns:

the internal time of the clock. Or ClockTime.NONE when given wrong input.

getMaster

public Clock getMaster()

Gets the master clock that this clock is slaved to or null when the clock is not slaved to any master clock.

Returns:

A master Clock or null when this clock is not slaved to a master clock.

setMaster

public boolean setMaster(Clock master)

Set master as the master clock for this clock. This clock will be automatically calibrated so that getTime() 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 getCalibration(org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime). 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:

master - a master Clock

Returns:

true if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the CAN_SET_MASTER flag will make this function return false.

getCalibration

public void getCalibration(ClockTime internal,
                           ClockTime external,
                           ClockTime rateNumerator,
                           ClockTime rateDenominator)

Gets the internal rate and reference time of clock. See setCalibration(org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime, org.gstreamer.ClockTime) for more information.

internal, external, rate_num, and rate_denom can be left NULL if the caller is not interested in the values. Thread safe.

Parameters:

internal - a reference internal time

external - a reference external time

rateNumerator - the numerator of the rate of the clock relative to its internal time

rateDenominator - the denominator of the rate of the clock

setCalibration

public void setCalibration(ClockTime internal,
                           ClockTime external,
                           ClockTime rateNumerator,
                           ClockTime rateDenominator)

Adjusts the rate and time of this 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 getTime() 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 getInternalTime() when this function is called.

Subsequent calls to gst_clock_get_time() will return clock times computed as follows:

time = (internal_time - internal) * rateNumerator/ rateDenominator + 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 getTime() always returns increasing values so when you move the clock backwards, getTime() will report the previous value until the clock catches up. Thread safe.

Parameters:

internal - a reference internal time

external - a reference external time

rateNumerator - the numerator of the rate of the clock relative to its internal time

rateDenominator - the denominator of the rate of the clock

newSingleShotID

public ClockID newSingleShotID(ClockTime time)

Gets a ClockID from this clock to trigger a single shot notification at the requested time.

Thread safe.

Parameters:

time - The requested time

Returns:

A ClockID that can be used to request the time notification.

newPeriodicID

public ClockID newPeriodicID(ClockTime startTime,
                             ClockTime interval)

Gets an ID from this 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.

Thread safe.

Parameters:

startTime - The requested start time.

interval - The requested interval.

Returns:

A ClockID that can be used to request the time notification.