001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.control;
027:
028: /**
029: * <code>RateControl</code> controls the playback rate of a
030: * <code>Player</code>.<p>
031: *
032: * The rate defines the relationship between the
033: * <code>Player's</code> <i>media time</i> and its
034: * <code>TimeBase</code>. Rates are specified in "milli-
035: * percentage".<p>
036: *
037: * For example, a rate of 200'000 indicates that <i>media
038: * time</i> will pass twice as fast as the
039: * <code>TimeBase</code> time once the <code>Player</code>
040: * starts. Similarly, a negative rate indicates that the
041: * <code>Player</code> runs in the opposite direction of its
042: * <code>TimeBase</code>, i.e. playing in reverse.<p>
043: *
044: * All <code>Player</code> must support the default rate
045: * 100'000. <code>Player</code>s that support only the default
046: * rate must not implement this interface.
047: * <code>Player</code>s that support other rates besides
048: * 100'000, should implement this interface and specify the
049: * appropriate minimum and maximum playback rates.<p>
050: *
051: * For audio, specific implementations may change the playback
052: * pitch when changing the playback rate. This may be viewed as an
053: * undesirable side-effect. See <code>PitchControl</code> for
054: * changing pitch without changing playback rate.
055: *
056: * @see javax.microedition.media.Player
057: * @see javax.microedition.media.control.TempoControl
058: * @see javax.microedition.media.control.PitchControl
059: */
060: public interface RateControl extends javax.microedition.media.Control {
061:
062: /**
063: * Sets the playback rate.
064: *
065: * The specified rate is 1000 times the percentage of the
066: * actual rate. For example, to play back at twice the speed, specify
067: * a rate of 200'000.<p>
068: *
069: * The <code>setRate</code> method returns the actual rate set by the
070: * <code>Player</code>. <code>Player</code> should set their rate
071: * as close to the requested
072: * value as possible, but are not required to set the rate to the exact
073: * value of any argument other than 100'000. A <code>Player</code>
074: * is only guaranteed to set
075: * its rate exactly to 100'000.
076: * If the given rate is less than <code>getMinRate</code>
077: * or greater than <code>getMaxRate</code>,
078: * the rate will be adjusted to the minimum or maximum
079: * supported rate respectively.
080: * <p>
081: * If the <code>Player</code> is already
082: * started, <code>setRate</code> will immediately take effect.
083: *
084: * @param millirate The playback rate to set. The rate is given in
085: * a "milli-percentage" value.
086: * @return The actual rate set in "milli-percentage".
087: * @see #getRate
088: */
089: int setRate(int millirate);
090:
091: /**
092: * Gets the current playback rate.
093: *
094: * @return the current playback rate in "milli-percentage".
095: * @see #setRate
096: */
097: int getRate();
098:
099: /**
100: * Gets the maximum playback rate supported by the <code>Player</code>.
101: *
102: * @return the maximum rate in "milli-percentage".
103: */
104: int getMaxRate();
105:
106: /**
107: * Gets the minimum playback rate supported by the <code>Player</code>.
108: *
109: * @return the minimum rate in "milli-percentage".
110: */
111: int getMinRate();
112: }
|