|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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
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.
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.
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
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
.
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
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.
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.
Clock
in the Stopped state.
If invoked on a Started
Clock
, these methods throw a ClockStartedError
.
syncStart
setTimeBase
setMediaTime
setRate
Clock
and its
TimeBase
and is not allowed on
a Started Clock
.
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.
TimeBase
,
Player
Field Summary | |
static Time |
RESET
Returned by getStopTime if the stop-time is unset. |
Method Summary | |
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 |
public static final Time RESET
getStopTime
if the stop-time is unset.
Method Detail |
public void setTimeBase(TimeBase master) throws IncompatibleTimeBaseException
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)
.
master
- The new TimeBase
or null
to reset the Clock
to its default TimeBase
.
IncompatibleTimeBaseException
- Thrown if
the Clock
can't use the specified TimeBase
.public void syncStart(Time at)
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
.
at
- The time-base time to equate with the
current media time.public void stop()
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 setStopTime(Time stopTime)
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.
stopTime
- The time at which you want the
Clock
to stop, in media time.public Time getStopTime()
setStopTime
.
Returns the constant Clock.RESET
if no stop time is set.
(Clock.RESET
is the default stop time.)
public void setMediaTime(Time now)
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
.
now
- The new media time.public Time getMediaTime()
Clock's
current media time.
A Started Clock's
media time
is based on its TimeBase
and rate, as described in Starting a Clock.
public long getMediaNanoseconds()
Clock's
current media time
in nanoseconds.
public Time getSyncTime()
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 TimeBase getTimeBase()
TimeBase
that this Clock
is using.
public Time mapToTimeBase(Time t) throws ClockStoppedException
TimeBase
time corresponding to the specified media time.
t
- The media time to map from.
ClockStoppedException
- Thrown if mapToTimeBase
is called on a Stopped
Clock
.public float getRate()
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 setRate(float factor)
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
.
factor
- The temporal scale factor (rate) to set.
|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |