/*
 * @(#)Clock.java	1.3 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media;

/**
 *
 * The <code>Clock</code> 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.
 *
 * <p>
 *
 * <h2>Clock and TimeBase</h2>
 *
 * <p>
 * A <code>Clock</code> contains a <code>TimeBase</code> that provides a source of time, 
 * much like a crystal oscillator. The only information that a <code>TimeBase</code> provides is 
 * its current time; it does not provide any methods for influencing how time is kept.  
 * 
 * A <code>Clock</code> defines a transformation on the time that its <code>TimeBase</code> keeps, typically marking
 * time for a particular media stream. The time that a <code>Clock</code> keeps is referred to as the <i>media time</i>.
 *
 * <p>
 * <h3>Clock Transform</h3>
 * 
 * The transformation that a <code>Clock</code> defines on a <code>TimeBase</code>
 * is defined by three parameters: rate, <i>media start-time</i> (mst), and 
 * <i>time-base start-time</i> (tbst). 
 * Given a <i>time-base time</i> (tbt),
 * the <i>media time</i> (mt) can be calculated
 * using the following transformation:
 * <p>
 * 
 * <CENTER><CODE>mt =  mst + (tbt - tbst)*rate </CODE></CENTER>
 * <p>
 * 
 * The rate is simply a scale factor that is applied 
 * to the <code>TimeBase</code>.
 * For example, a rate of 2.0 indicates that the <code>Clock</code>
 * will run at twice the rate
 * of its <code>TimeBase</code>.  Similarly, a negative rate indicates that
 * the <code>Clock</code> runs in the opposite direction of its <code>TimeBase</code>.
 * <p>
 * 
 * The <i>time-base start-time</i> and the
 * <i>media  start-time</i> define a common point in time
 * at which the <code>Clock</code> and the <code>TimeBase</code> are synchronized.
 * <p>
 * 
 * <h3>Default Time Base</h3>
 * 
 * A <code>Clock</code> has a default <code>TimeBase</code>.
 * For many objects that support the <code>Clock</code> interface, the default
 * <code>TimeBase</code> is the system <code>TimeBase</code>. 
 * The system <code>TimeBase</code> can be obtained from <code>Manager</code> through
 * the  <code>getSystemTimeBase</code> method. 
 * <p>
 * 
 * Some <code>Clocks</code> have a <code>TimeBase</code> other than 
 * the system <code>TimeBase</code>. For example, an audio renderer that implements the <code>Clock</code>
 * interface might have a <code>TimeBase</code> that represents a
 * hardware clock.
 * <p>
 * 
 * 
 * <h2>Using a Clock</h2>
 * 
 * You can get the <code>TimeBase</code> associated with a <code>Clock</code> by calling the <code>getTimeBase</code> method. To change the 
 * <CODE>TimeBase</CODE> that a <CODE>Clock</CODE> uses, you call the <code>setTimeBase</code> method.
 * These get and set methods can be used together to synchronize different <code>Clocks</code> to the
 * same <code>TimeBase</code>.
 * <p>
 * For example, an application might want to force a video renderer to sync to the <code>TimeBase</code> of an audio renderer. To do this,
 * the application would call <code>getTimeBase</code> on the audio renderer and then use the value returned to call <code>setTimeBase</code> on the video renderer.
 * This would ensure that the two rendering objects use the same source of time. 
 *
 * You can reset a <CODE>Clock</CODE> to use its default <CODE>TimeBase</CODE> by
 * calling <CODE>setTimeBase(null)</CODE>.
 * <p>
 *
 * Some <code>Clocks</code> are incapable of using another <code>TimeBase</code>.
 * If this is the case, an <code>IncompatibleTimeBaseException</code> is thrown when <code>setTimeBase</code> 
 * is called.
 * <p>
 * 
 * <code>Clock</code> also provides methods for getting and setting a <code>Clock's</code> <i>media time</i> and rate: 
 * <ul>
 * <li><code>getMediaTime</code> and <code>setMediaTime</code>
 * <li><code>getRate</code> and <code>setRate</code>
 * </ul>
 * <a name="start">
 * <h3>Starting a Clock</h3></a>
 *
 * Until a <code>Clock's</code> <code>TimeBase</code> transformation takes effect, the <code>Clock</code> is 
 * in the <i>Stopped</i> state. Once all three transformation parameters (<i>media start-time</i>, 
 * <i>time-base start-time</i>, and rate)  have been provided 
 * to the <code>Clock</code>, it enters the <i>Started</i> state.
 * <p>
 *
 * To start a <code>Clock</code>, <code>syncStart</code> is called with 
 * the <i>time-base start-time</i> as an argument.
 * The new <i>media start-time</i> is taken as the current
 * <i>media time</i>, and the current rate defines the <code>Clock's</code> rate parameter.
 * When <code>syncStart</code> is called, the <code>Clock</code> and its <code>TimeBase</code> are
 * locked in sync and the <code>Clock</code> is considered to be in the <i>Started</i> state.
 * <p>
 *
 * When a <code>Clock</code> is stopped and then restarted (using <code>syncStart</code>), 
 * the <i>media start-time</i>
 * for the restarted <code>Clock</code> is the current <i>media time</i>.
 *
 * The <code>syncStart</code> method is often used to synchronize
 * two <code>Clocks</code> that share the same <code>TimeBase</code>. 
 * When the <i>time-base start-time</i> and rate of each clock are set to the same values and 
 * each <code>Clock</code> is set with the appropriate <i>media start-time</i>,
 * the two <code>Clocks</code> will run in sync.
 * <p>
 *
 * When <code>syncStart</code> is called with a
 * new <i>time-base start-time</i>,
 * the synchronization with the <i>media time</i> doesn't occur
 * until the <code>TimeBase</code>
 * reaches the <i>time-base start-time</i>.
 * The <code>getMediaTime</code> method returns
 * the untransformed <i>media time</i> until the <code>TimeBase</code>
 * reaches the <i>time-base start-time</i>. 
 * <p>
 * The <CODE>getSyncTime</CODE> method behaves slightly differently.
 * Once <CODE>syncStart</CODE> is invoked, <CODE>getSyncTime</CODE>
 * always reports the transformed <i>time-base time</i>, 
 * whether or not the <i>time-base start-time</i> has been reached.
 * You can use <code>getSyncTime</code> to determine how much time remains
 * before the <i>time-base start-time</i> is reached. 
 * When the <i>time-base start-time</i> is reached,
 * both
 * <CODE>getMediaTime</CODE> and <CODE>getSyncTime</CODE>
 * return the same value.
 * <p>
 *
 * Objects that implement
 * the <code>Clock</code> interface can provide more convenient start
 * methods than <CODE>syncStart</CODE>.
 * For example, <code>Player</code> defines <code>start</code>, 
 * which should be used instead of <code>syncStart</code> 
 * to start a <code>Player</code>.
 * 
 * <h3>Stopping a Clock</h3>
 * 
 * A <i>Stopped</i> <code>Clock</code> is no longer synchronized to
 * its <code>TimeBase</code>. When a <code>Clock</code> is <i>Stopped</i>,
 * its <i>media time</i>  no longer moves in rate-adjusted synchronization with
 * the <i>time-base time</i> provided by its <code>TimeBase</code>.
 * <p>
 * 
 * There are two ways to explicitly stop a <code>Clock</code>: you can invoke
 * <code>stop</code> or set a <i>media stop-time</i>.
 * When <code>stop</code> is invoked, synchronization with the
 * <code>TimeBase</code> immediately stops. 
 * When a <i>media stop-time</i> is set,
 * synchronization stops when the <i>media stop-time</i> passes.
 * <p>
 *
 * A <CODE>Clock's</CODE> rate affects how its <i>media stop-time</i>
 * is interpreted.
 * If its rate is positive, the <code>Clock</code>
 * stops when the <i>media time</i> becomes
 * greater than or equal to the stop time. 
 * If its rate is negative, the <code>Clock</code> stops
 * when the <i>media time</i> becomes
 * less than or equal to the stop time.
 * <p>
 *
 * If the stop-time is set to a value that the <code>Clock</code>
 * has already passed, the <code>Clock</code> immediately stops.
 * <p>
 * 
 * Once a stop-time is set, it remains in effect until it is changed
 * or cleared.
 * To clear a stop-time, call <code>setStopTime</code>
 * with <code>Clock.RESET</code>.
 * A <CODE>Clock's</CODE> stop-time is cleared automatically when it stops.
 * <p>
 *
 * If no stop-time is ever set or if the stop-time is cleared,
 * the only way to stop the <code>Clock</code> is
 * to call the <code>stop</code> method.
 * <p>
 *
 * <h2>Clock State</h2>
 * 
 * Conceptually, a <code>Clock</code> is
 * always in one of two states: <i>Started</i> or <i>Stopped</i>.
 * A <code>Clock</code> enters the <i>Started</i> state after 
 * <code>syncStart</code> has been called and the <CODE>Clock</CODE>
 * is mapped to its <code>TimeBase</code>.
 * A <code>Clock</code> returns to the <i>Stopped</i> state immediately
 * when the <code>stop</code> method is called or the
 * <i>media time</i> passes the stop time.
 * <p>
 *
 * Certain methods can only be invoked when the <code>Clock</code> is in a
 * particular state.
 * If the <code>Clock</code> is in the wrong state when one of these methods
 * is called, an error or exception is thrown.
 * 
 * <h3>Methods Restricted to <i>Started</i> Clocks</h3>
 *
 * The <code>mapToTimeBase</code> method can only be called on a 
 * <code>Clock</code> in the <i>Started</i> state. 
 * If it is invoked on a <i>Stopped</i> <code>Clock</code>,
 * a <code>ClockStoppedException</code> is thrown.
 * This is because the <code>Clock</code> is not synchronized to
 * a <code>TimeBase</code> when it is <i>Stopped</i>.
 *
 * <h3>Methods Restricted to <i>Stopped</i> Clocks</h3>
 *
 * The following methods can only be called on a  
 * <code>Clock</code> in the <i>Stopped</i> state.
 * If invoked on a <i>Started</i> 
 * <code>Clock</code>, these methods throw a <code>ClockStartedError</code>.
 * <ul>
 * <li> <code>syncStart</code>
 * <li> <code>setTimeBase</code>
 * <li> <code>setMediaTime</code>
 * <li> <code>setRate</code>
 * </ul>
 * 
 * Resetting the rate, the <i>media time</i>, the time base, or the 
 * <i>time-base start-time</i> implies a complete remapping 
 * between the <code>Clock</code> and its
 * <code>TimeBase</code> and is not allowed on
 * a <i>Started</i> <code>Clock</code>. 
 *
 * <h3>Methods with Additional Restrictions</h3>
 * 
 * A race condition occurs if a new <i>media stop-time</i> is set
 * when a <code>Clock</code> is already approaching a previously
 * set <i>media stop-time</i>.
 * In this situation, it impossible to guarantee when the <code>Clock</code>
 * will stop. To prevent this race condition, <code>setStopTime</code> can
 * only be set once on  a <i>Started</i> <code>Clock</code>.
 * A <code>StopTimeSetError</code> is thrown if <code>setStopTime</code>
 * is called and the <i>media stop-time</i> has already been set.
 * <p>
 *
 * There are no restrictions on calling <code>setStopTime</code> on a 
 * <i>Stopped</i> <code>Clock</code>; the stop time can always be
 * reset if  the <code>Clock</code> is <i>Stopped</i>.
 * 
 * @see TimeBase
 * @see Player
 * @version 1.3, 02/08/21
*/
public interface Clock {

    /**
     * Returned by <CODE>getStopTime</CODE> if the stop-time is unset.
     */
    static public final Time RESET = new Time(Long.MAX_VALUE);
    
    /**
     * Sets the <code>TimeBase</code> for this <code>Clock</code>.
     * This method can only be called on a 
     * <i>Stopped</i> <code>Clock</code>.
     * A <code>ClockStartedError</code> is thrown if
     * <code>setTimeBase</code> is called on a <i>Started</i> 
     * <code>Clock</code>.    
     * 
     * <p>
     * A <code>Clock</code> has a default <code>TimeBase</code> that
     * is determined by the implementation. 
     * To reset a <code>Clock</code> to its default 
     * <code>TimeBase</code>, call <code>setTimeBase(null)</code>.
     * @param master The new <CODE>TimeBase</CODE> or <CODE>null</CODE> to reset the <code>Clock</code>
     * to its default <code>TimeBase</code>.
     * @exception IncompatibleTimeBaseException Thrown if
     * the <code>Clock</code> can't use the specified <code>TimeBase</code>.
     */
public void setTimeBase(TimeBase master) throws IncompatibleTimeBaseException;
    
    /**
     * Synchronizes the current <i>media time</i> to the specified 
     * <I>time-base time</I> and start the <code>Clock</code>. 
     * The <code>syncStart</code> method sets the <i>time-base start-time</i>,
     * and puts the <code>Clock</code> in the <i>Started</i> state.
     * This method can only be called on a
     * <i>Stopped</i> <code>Clock</code>. 
     * A <code>ClockStartedError</code> is thrown if
     * <code>setTimeBase</code> is called on a <i>Started</i> 
     * <code>Clock</code>.  
     * 
     * @param at The <i>time-base time</i> to equate with the
     * current <i>media time</i>.
     */
    public void syncStart(Time at);
    
    /**
     * Stops the <code>Clock</code>. 
     * Calling <code>stop</code> releases the <code>Clock</code> from
     * synchronization with the <code>TimeBase</code>.
     * After this request is issued, the <code>Clock</code> is in the 
     * <i>Stopped</i> state.
     * If <code>stop</code> is called on
     * a <i>Stopped</i> <code>Clock</code>, the request is ignored.
     *
     */
    public void stop();

    /**
     *
     * Sets the <i>media time</i> at which you want the <code>Clock</code>
     * to stop.
     * The <code>Clock</code> will stop when its <i>media time</i>
     * passes the stop-time.
     * To clear the stop time, set it to: <code>Clock.RESET</code>.
     * <p>
     *
     * You can always call <code>setStopTime</code> on a <i>Stopped</i> 
     * <code>Clock</code>.
     * <p>
     *
     * On a <i>Started</i> <code>Clock</code>, the stop-time can only
     * be set <I>once</I>.
     * 
     * A <code>StopTimeSetError</code> is thrown if <code>setStopTime</code>
     * is called and the <i>media stop-time</i> has already been set.
     *
     * @param stopTime The time at which you want the
     * <code>Clock</code> to stop, in <i>media time</i>.
    */
    public void setStopTime(Time stopTime);

    /**
     * Gets the last value successfully set by <CODE>setStopTime</CODE>.
     * 
     * Returns the constant <CODE>Clock.RESET</CODE> if no stop time is set.
     * (<CODE>Clock.RESET</CODE> is the default stop time.)
     *
     * @return The current stop time. 
     */
    public Time getStopTime();
    
    /**
     * Sets the <code>Clock's</code> <i>media time</i>.
     * This method can only be called on
     * a <i>Stopped</i> <code>Clock</code>.  
     * A <code>ClockStartedError</code> is thrown if
     * <code>setMediaTime</code> is called on a <i>Started</i> 
     * <code>Clock</code>.
     * 
     * @param now The new media time.
     */
    public void setMediaTime(Time now);

    /**
     * Gets this <code>Clock's</code> current <i>media time</i>.
     * A <i>Started</i> <code>Clock's</code> <i>media time</i>
     * is based on  its <code>TimeBase</code>
     * and rate, as described in <a href="#start"><I>Starting a Clock</I></a>.
     *
     * @return The current <i>media time</i>.
     */
    public Time getMediaTime();

    /**
     * Gets this <code>Clock's</code> current <i>media time</i>
     * in nanoseconds.
     * 
     * @return The current <i>media time</i> in nanoseconds.
     */
    public long getMediaNanoseconds();
    
    /**
     * Gets the current <i>media time</i> or the time until this
     * <code>Clock</code> will synchronize to its <code>TimeBase</code>.
     * The <code>getSyncTime</code> method is used by <code>Players</code> and
     * advanced applet writers to  synchronize <code>Clocks</code>.
     * <p>
     *
     * Like <code>getMediaTime</code>, this method returns 
     * the <code>Clock's</code> current <i>media time</i>,
     * which is based on its <code>TimeBase</code> and rate.
     *
     * However, when <code>syncStart</code> is used to start
     * the <code>Clock</code>, <code>getSyncTime</code> performs a countdown
     * to the time-base start-time, returning the time remaining until
     * the <i>time-base start-time</i>.
     * Once the <code>TimeBase</code> reaches the
     * <i>time-base start-time</i>, <code>getSyncTime</code>
     * and <code>getMediaTime</code> will return the same value.<p>
     *
     */
    public Time getSyncTime();

    /**
     * Gets the <code>TimeBase</code> that this <code>Clock</code> is using.
     */
    public TimeBase getTimeBase();

    /**
     * Gets the <code>TimeBase</code> time corresponding to the specified <i>media time</i>.
     *
     * @exception ClockStoppedException Thrown if <CODE>mapToTimeBase</CODE> is called on a <i>Stopped</i> 
     * <code>Clock</code>.
     * 
     * @param t The <i>media time</i> to map from.
     *
     * @return The <I>time-base time</I> in <I>media-time</I> coordinates.
     */
    public Time mapToTimeBase(Time t) throws ClockStoppedException;

    /**
     * Gets the current temporal scale factor.
     * The scale factor defines the relationship
     * between the <code>Clock's</code> <i>media time</i> 
     * and its <code>TimeBase</code>.<p>
     *
     * For example, a rate of 2.0 indicates that <i>media time</i>
     * will pass twice as fast as the <code>TimeBase</code> time once
     * the <code>Clock</code>
     * starts.  Similarly, a negative rate indicates that
     * the <code>Clock</code> runs in the opposite direction of its <code>TimeBase</code>. 
     * All <code>Clocks</code> are
     * guaranteed to support a rate of 1.0, the default rate. <code>Clocks</code>  are not required 
     * to support any other rate.<p>
    */
    public float getRate();
 
    /**
     * Sets the temporal scale factor.
     * The argument <i>suggests</i> the scale factor to use.<p>
     * 
     * The <code>setRate</code> method returns the actual rate set by the
     * <code>Clock</code>.  <code>Clocks</code> 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 <code>Clock</code> is only guaranteed to set
     * its rate exactly to 1.0.
     * <p>
     * 
     * You can only call this method on a <i>Stopped</i> <code>Clock</code>. A
     * <code>ClockStartedError</code> is thrown if <code>setRate</code> is called on a <i>Started</i> <code>Clock</code>.<p>
     * 
     * @param factor The temporal scale factor (rate) to set.
     * @return The actual rate set.
     */
    public float setRate(float factor);

}