javax.media

Interface Clock

All Known Subinterfaces:

Controller, Player, ServiceMediaHandler

public interface Clock

The Clock interface is implemented by objects that support the Java Media time model. For example, this interface might be implemented by an object that decodes and renders MPEG movies.

Clock and TimeBase

A Clock contains a TimeBase that provides a source of time, much like a crystal oscillator. The only information that a TimeBase provides is its current time; it does not provide any methods for influencing how time is kept. A Clock defines a transformation on the time that its TimeBase keeps, typically marking time for a particular media stream. The time that a Clock keeps is referred to as the media time.

Clock Transform

The transformation that a Clock defines on a TimeBase is defined by three parameters: rate, media start-time (mst), and time-base start-time (tbst). Given a time-base time (tbt), the media time (mt) can be calculated using the following transformation:

mt = mst + (tbt - tbst)*rate

The rate is simply a scale factor that is applied to the TimeBase. For example, a rate of 2.0 indicates that the Clock will run at twice the rate of its TimeBase. Similarly, a negative rate indicates that the Clock runs in the opposite direction of its TimeBase.

The time-base start-time and the media start-time define a common point in time at which the Clock and the TimeBase are synchronized.

Default Time Base

A Clock has a default TimeBase. For many objects that support the Clock interface, the default TimeBase is the system TimeBase. The system TimeBase can be obtained from Manager through the getSystemTimeBase method.

Some Clocks have a TimeBase other than the system TimeBase. For example, an audio renderer that implements the Clock interface might have a TimeBase that represents a hardware clock.

Using a Clock

You can get the TimeBase associated with a Clock by calling the getTimeBase method. To change the TimeBase that a Clock uses, you call the setTimeBase method. These get and set methods can be used together to synchronize different Clocks to the same TimeBase.

For example, an application might want to force a video renderer to sync to the TimeBase of an audio renderer. To do this, the application would call getTimeBase on the audio renderer and then use the value returned to call setTimeBase on the video renderer. This would ensure that the two rendering objects use the same source of time. You can reset a Clock to use its default TimeBase by calling setTimeBase(null).

Some Clocks are incapable of using another TimeBase. If this is the case, an IncompatibleTimeBaseException is thrown when setTimeBase is called.

Clock also provides methods for getting and setting a Clock's media time and rate:

• getMediaTime and setMediaTime
• getRate and setRate

Starting a Clock

Until a Clock's TimeBase transformation takes effect, the Clock is in the Stopped state. Once all three transformation parameters (media start-time, time-base start-time, and rate) have been provided to the Clock, it enters the Started state.

To start a Clock, syncStart is called with the time-base start-time as an argument. The new media start-time is taken as the current media time, and the current rate defines the Clock's rate parameter. When syncStart is called, the Clock and its TimeBase are locked in sync and the Clock is considered to be in the Started state.

When a Clock is stopped and then restarted (using syncStart), the media start-time for the restarted Clock is the current media time. The syncStart method is often used to synchronize two Clocks that share the same TimeBase. When the time-base start-time and rate of each clock are set to the same values and each Clock is set with the appropriate media start-time, the two Clocks will run in sync.

When syncStart is called with a new time-base start-time, the synchronization with the media time doesn't occur until the TimeBase reaches the time-base start-time. The getMediaTime method returns the untransformed media time until the TimeBase reaches the time-base start-time.

The getSyncTime method behaves slightly differently. Once syncStart is invoked, getSyncTime always reports the transformed time-base time, whether or not the time-base start-time has been reached. You can use getSyncTime to determine how much time remains before the time-base start-time is reached. When the time-base start-time is reached, both getMediaTime and getSyncTime return the same value.

Objects that implement the Clock interface can provide more convenient start methods than syncStart. For example, Player defines start, which should be used instead of syncStart to start a Player.

Stopping a Clock

A Stopped Clock is no longer synchronized to its TimeBase. When a Clock is Stopped, its media time no longer moves in rate-adjusted synchronization with the time-base time provided by its TimeBase.

There are two ways to explicitly stop a Clock: you can invoke stop or set a media stop-time. When stop is invoked, synchronization with the TimeBase immediately stops. When a media stop-time is set, synchronization stops when the media stop-time passes.

A Clock's rate affects how its media stop-time is interpreted. If its rate is positive, the Clock stops when the media time becomes greater than or equal to the stop time. If its rate is negative, the Clock stops when the media time becomes less than or equal to the stop time.

If the stop-time is set to a value that the Clock has already passed, the Clock immediately stops.

Once a stop-time is set, it remains in effect until it is changed or cleared. To clear a stop-time, call setStopTime with Clock.RESET. A Clock's stop-time is cleared automatically when it stops.

If no stop-time is ever set or if the stop-time is cleared, the only way to stop the Clock is to call the stop method.

Clock State

Conceptually, a Clock is always in one of two states: Started or Stopped. A Clock enters the Started state after syncStart has been called and the Clock is mapped to its TimeBase. A Clock returns to the Stopped state immediately when the stop method is called or the media time passes the stop time.

Certain methods can only be invoked when the Clock is in a particular state. If the Clock is in the wrong state when one of these methods is called, an error or exception is thrown.

Methods Restricted to Started Clocks

The mapToTimeBase method can only be called on a Clock in the Started state. If it is invoked on a Stopped Clock, a ClockStoppedException is thrown. This is because the Clock is not synchronized to a TimeBase when it is Stopped.

Methods Restricted to Stopped Clocks

The following methods can only be called on a Clock in the Stopped state. If invoked on a Started Clock, these methods throw a ClockStartedError.

• syncStart
• setTimeBase
• setMediaTime
• setRate

Resetting the rate, the media time, the time base, or the time-base start-time implies a complete remapping between the Clock and its TimeBase and is not allowed on a Started Clock.

Methods with Additional Restrictions

A race condition occurs if a new media stop-time is set when a Clock is already approaching a previously set media stop-time. In this situation, it impossible to guarantee when the Clock will stop. To prevent this race condition, setStopTime can only be set once on a Started Clock. A StopTimeSetError is thrown if setStopTime is called and the media stop-time has already been set.

There are no restrictions on calling setStopTime on a Stopped Clock; the stop time can always be reset if the Clock is Stopped.

Version:

1.43, 07/10/09

See Also:

TimeBase, Player

Field Summary

Fields

Modifier and Type	Field and Description
static Time	RESET Returned by getStopTime if the stop-time is unset.

Method Summary

Methods

Modifier and Type	Method and Description
long	getMediaNanoseconds() Get this Clock's current media time in nanoseconds.
Time	getMediaTime() Get this Clock's current media time.
float	getRate() Get the current temporal scale factor.
Time	getStopTime() Get the last value successfully set by setStopTime.
Time	getSyncTime() Get the current media time or the time until this Clock will synchronize to its TimeBase.
TimeBase	getTimeBase() Get the TimeBase that this Clock is using.
Time	mapToTimeBase(Time t) Get the TimeBase time corresponding to the specified media time.
void	setMediaTime(Time now) Set the Clock's media time.
float	setRate(float factor) Set the temporal scale factor.
void	setStopTime(Time stopTime) Set the media time at which you want the Clock to stop.
void	setTimeBase(TimeBase master) Set the TimeBase for this Clock.
void	stop() Stop the Clock.
void	syncStart(Time at) Synchronize the current media time to the specified time-base time and start the Clock.

Field Detail

RESET

static final Time RESET

Returned by getStopTime if the stop-time is unset.

Method Detail

setTimeBase

void setTimeBase(TimeBase master)
                 throws IncompatibleTimeBaseException

Set the TimeBase for this Clock. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setTimeBase is called on a Started Clock.

A Clock has a default TimeBase that is determined by the implementation. To reset a Clock to its default TimeBase, call setTimeBase(null).

Parameters:

master - The new TimeBase or null to reset the Clock to its default TimeBase.

Throws:

IncompatibleTimeBaseException - Thrown if the Clock can't use the specified TimeBase.

syncStart

void syncStart(Time at)

Synchronize the current media time to the specified time-base time and start the Clock. The syncStart method sets the time-base start-time, and puts the Clock in the Started state. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setTimeBase is called on a Started Clock.

Parameters:

at - The time-base time to equate with the current media time.

stop

void stop()

Stop the Clock. Calling stop releases the Clock from synchronization with the TimeBase. After this request is issued, the Clock is in the Stopped state. If stop is called on a Stopped Clock, the request is ignored.

setStopTime

void setStopTime(Time stopTime)

Set the media time at which you want the Clock to stop. The Clock will stop when its media time passes the stop-time. To clear the stop time, set it to: Clock.RESET.

You can always call setStopTime on a Stopped Clock.

On a Started Clock, the stop-time can only be set once. A StopTimeSetError is thrown if setStopTime is called and the media stop-time has already been set.

Parameters:

stopTime - The time at which you want the Clock to stop, in media time.

getStopTime

Time getStopTime()

Get the last value successfully set by setStopTime. Returns the constant Clock.RESET if no stop time is set. (Clock.RESET is the default stop time.)

Returns:

The current stop time.

setMediaTime

void setMediaTime(Time now)

Set the Clock's media time. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setMediaTime is called on a Started Clock.

Parameters:

now - The new media time.

getMediaTime

Time getMediaTime()

Get this Clock's current media time. A Started Clock's media time is based on its TimeBase and rate, as described in Starting a Clock.

Returns:

The current media time.

getMediaNanoseconds

long getMediaNanoseconds()

Get this Clock's current media time in nanoseconds.

Returns:

The current media time in nanoseconds.

getSyncTime

Time getSyncTime()

Get the current media time or the time until this Clock will synchronize to its TimeBase. The getSyncTime method is used by Players and advanced applet writers to synchronize Clocks.

Like getMediaTime, this method returns the Clock's current media time, which is based on its TimeBase and rate. However, when syncStart is used to start the Clock, getSyncTime performs a countdown to the time-base start-time, returning the time remaining until the time-base start-time. Once the TimeBase reaches the time-base start-time, getSyncTime and getMediaTime will return the same value.

getTimeBase

TimeBase getTimeBase()

Get the TimeBase that this Clock is using.

mapToTimeBase

Time mapToTimeBase(Time t)
                   throws ClockStoppedException

Get the TimeBase time corresponding to the specified media time.

If this method is called when the clock rate is 0.0, no exception will be thrown, and the getSeconds() method of the returned Time object will yield an undefined value.

Parameters:

t - The media time to map from.

Returns:

The time-base time in media-time coordinates.

Throws:

ClockStoppedException - Thrown if mapToTimeBase is called on a Stopped Clock.

getRate

float getRate()

Get the current temporal scale factor. The scale factor defines the relationship between the Clock's media time and its TimeBase.

For example, a rate of 2.0 indicates that media time will pass twice as fast as the TimeBase time once the Clock starts. Similarly, a negative rate indicates that the Clock runs in the opposite direction of its TimeBase. All Clocks are guaranteed to support a rate of 1.0, the default rate. Clocks are not required to support any other rate.

setRate

float setRate(float factor)

Set the temporal scale factor. The argument suggests the scale factor to use.

The setRate method returns the actual rate set by the Clock. Clocks should set their rate as close to the requested value as possible, but are not required to set the rate to the exact value of any argument other than 1.0. A Clock is only guaranteed to set its rate exactly to 1.0.

You can only call this method on a Stopped Clock. A ClockStartedError is thrown if setRate is called on a Started Clock.

Parameters:

factor - The temporal scale factor (rate) to set.

Returns:

The actual rate set.