javax.media.Clock Maven / Gradle / Ivy
/**
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example,
this file and any files generated from it may be used to generate other documentation,
such as a unified set of documents of API signatures for a platform
that includes technologies expressed as Java APIs.
This file may also be used to produce "compilation stubs,"
which allow applications to be compiled and validated for such platforms.
By contrast, no permission is given for you to incorporate this file,
in whole or in part, in an implementation of a Java specification.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.
In the event of a discrepency between this work and the JSR 927 specification,
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/
package javax.media;
/**
* 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.
*
* @see TimeBase
* @see Player
* @version 1.43, 07/10/09
*/
public interface Clock
{
/**
* Returned by getStopTime if the stop-time is unset.
*/
public static final Time RESET = null;
/**
* 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).
* @param master The new TimeBase or null to reset the Clock
* to its default TimeBase.
* @exception IncompatibleTimeBaseException Thrown if
* the Clock can't use the specified TimeBase.
*/
public void setTimeBase(TimeBase master)
throws IncompatibleTimeBaseException;
/**
* 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.
*
* @param at The time-base time to equate with the
* current media time.
*/
public void syncStart(Time at);
/**
* 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.
*
*/
public void stop();
/**
* 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.
*
* @param stopTime The time at which you want the
* Clock to stop, in media time.
*/
public void setStopTime(Time stopTime);
/**
* 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.)
*
* @return The current stop time.
*/
public Time getStopTime();
/**
* 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.
*
* @param now The new media time.
*/
public void setMediaTime(Time now);
/**
* 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.
*
* @return The current media time.
*/
public Time getMediaTime();
/**
* Get this Clock's current media time
* in nanoseconds.
*
* @return The current media time in nanoseconds.
*/
public long getMediaNanoseconds();
/**
* 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.
*
*/
public Time getSyncTime();
/**
* Get the TimeBase that this Clock is using.
*/
public TimeBase getTimeBase();
/**
* 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 {@link Time#getSeconds() getSeconds()}
* method of the returned {@link Time} object will yield an undefined
* value.
*
* @exception ClockStoppedException Thrown if mapToTimeBase
* is called on a Stopped Clock.
*
* @param t The media time to map from.
*
* @return The time-base time in media-time coordinates.
*/
public Time mapToTimeBase(Time t) throws ClockStoppedException;
/**
* 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.
*/
public float getRate();
/**
* 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.
*
* @param factor The temporal scale factor (rate) to set.
* @return The actual rate set.
*/
public float setRate(float factor);
}