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: * The <code>FramePositioningControl</code> is the interface to control
030: * precise positioning to a video frame for <code>Players</code>.
031: * <p>
032: * Frame numbers for a bounded movie must be non-negative
033: * and should generally begin with 0,
034: * corresponding to media time 0. Each video frame of a movie
035: * must have a unique frame number that is one bigger than the
036: * previous frame.
037: * <p>
038: * There is a direct mapping between the frame number and the media
039: * time of a video frame; although not all <code>Players</code> can
040: * compute that relationship. For <code>Players</code> that can
041: * compute that relationship, the <code>mapFrameToTime</code> and
042: * <code>mapTimeToFrame</code> methods can be used.
043: * <p>
044: * When a <code>Player</code> is seeked or skipped to a new video frame,
045: * the media time of the <code>Player</code> will be changed to the
046: * media time of the corresponding video frame.
047: * <p>
048: * As much as possible, the methods in this interface should
049: * provide frame-level accuracy with a plus-or-minus-one-frame
050: * margin of error to accommodate for round-off errors.
051: * However, if the content has inaccurate frame positioning
052: * information, implementations may not be able to provide
053: * the necessary frame-level accuracy. For instance, some
054: * media content may contain wrong time-stamps or have missing
055: * frames. In any case, the results of each
056: * operation should represent the best effort. For the
057: * <code>seek</code> and <code>skip</code> methods, the returned
058: * value should indicate the actual new location or the number
059: * of frames skipped.
060: *
061: */
062: public interface FramePositioningControl extends
063: javax.microedition.media.Control {
064:
065: /**
066: * Seek to a given video frame.
067: * The media time of the <code>Player</code> will be updated
068: * to reflect the new position set.
069: * <p>
070: * This method can be called on a stopped or started
071: * <code>Player</code>.
072: * If the <code>Player</code> is
073: * in the <i>Started</i> state, this method may cause the
074: * <code>Player</code> to change states. If that happens, the
075: * appropriate transition events will be posted by
076: * the <code>Player</code> when its state changes.
077: * <p>
078: * If the given frame number is less than the first or larger
079: * than the last frame number in the media, <code>seek</code>
080: * will jump to either the first or the last frame respectively.
081: *
082: * @param frameNumber the frame to seek to.
083: * @return the actual frame that the Player has seeked to.
084: */
085: int seek(int frameNumber);
086:
087: /**
088: * Skip a given number of frames from the current position.
089: * The media time of the <code>Player</code> will be updated to
090: * reflect the new position set.
091: * <p>
092: * This method can be called on a stopped or started <code>Player</code>.
093: * If the <code>Player</code> is in the <i>Started</i> state,
094: * the current position is changing. Hence,
095: * the frame actually skipped to will not be exact.
096: * <p>
097: * If the <code>Player</code> is
098: * in the <i>Started</i> state, this method may cause the
099: * <code>Player</code> to change states. If that happens, the
100: * appropriate transition events will be posted.
101: * <p>
102: * If the given <code>framesToSkip</code> will cause the position to
103: * extend beyond the first or last frame, <code>skip</code> will
104: * jump to the first or last frame respectively.
105: *
106: * @param framesToSkip the number of frames to skip from the current
107: * position. If framesToSkip is positive, it will seek forward
108: * by framesToSkip number of frames. If framesToSkip is negative,
109: * it will seek backward by framesToSkip number of frames.
110: * e.g. skip(-1) will seek backward one frame.
111: * @return the actual number of frames skipped.
112: */
113: int skip(int framesToSkip);
114:
115: /**
116: * Converts the given frame number to the corresponding media time.
117: * The method only performs the calculations. It does not
118: * position the media to the given frame.
119: *
120: * @param frameNumber the input frame number for the conversion.
121: * @return the converted media time in microseconds for the given frame.
122: * If the conversion fails, -1 is returned.
123: */
124: long mapFrameToTime(int frameNumber);
125:
126: /**
127: * Converts the given media time to the corresponding frame number.
128: * The method only performs the calculations. It does not
129: * position the media to the given media time.
130: * <p>
131: * The frame returned is the nearest frame that has a media time
132: * less than or equal to the given media time.
133: * <p>
134: * <code>mapTimeToFrame(0)</code> must not fail and must
135: * return the frame number of the first frame.
136: *
137: * @param mediaTime the input media time for the
138: * conversion in microseconds.
139: * @return the converted frame number for the given media time.
140: * If the conversion fails, -1 is returned.
141: */
142: int mapTimeToFrame(long mediaTime);
143: }
|