Clock (mhp-1.1.2 1.1 API)

All Known Subinterfaces:

Controller, Player, ServiceMediaHandler

All Known Implementing Classes:

AMController, Handler, Handler, MediaClock, MediaController, MediaPlayer
```
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.45, 98/03/28

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.

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

Interface Clock

Clock and TimeBase

Clock Transform

Default Time Base

Using a Clock

Starting a Clock

Stopping a Clock

Clock State

Methods Restricted to Started Clocks

Methods Restricted to Stopped Clocks

Methods with Additional Restrictions

Field Summary

Method Summary

Field Detail

RESET

Method Detail

setTimeBase

syncStart

stop

setStopTime

getStopTime

setMediaTime

getMediaTime

getMediaNanoseconds

getSyncTime

getTimeBase

mapToTimeBase

getRate

setRate