File Doc Category Size Date Package
FramePositioningControl.java API Doc phoneME MR2 API (J2ME) 6148 Wed May 02 16:47:14 BST 2007 javax.microedition.media.control

FramePositioningControl

public interface FramePositioningControl implements javax.microedition.media.Control

The FramePositioningControl is the interface to control precise positioning to a video frame for Players.

Frame numbers for a bounded movie must be non-negative and should generally begin with 0, corresponding to media time 0. Each video frame of a movie must have a unique frame number that is one bigger than the previous frame.

There is a direct mapping between the frame number and the media time of a video frame; although not all Players can compute that relationship. For Players that can compute that relationship, the mapFrameToTime and mapTimeToFrame methods can be used.

When a Player is seeked or skipped to a new video frame, the media time of the Player will be changed to the media time of the corresponding video frame.

As much as possible, the methods in this interface should provide frame-level accuracy with a plus-or-minus-one-frame margin of error to accommodate for round-off errors. However, if the content has inaccurate frame positioning information, implementations may not be able to provide the necessary frame-level accuracy. For instance, some media content may contain wrong time-stamps or have missing frames. In any case, the results of each operation should represent the best effort. For the seek and skip methods, the returned value should indicate the actual new location or the number of frames skipped.

Fields Summary
Constructors Summary
Methods Summary
public long mapFrameToTime(int frameNumber)
Converts the given frame number to the corresponding media time. The method only performs the calculations. It does not position the media to the given frame.
param
frameNumber the input frame number for the conversion.
return
the converted media time in microseconds for the given frame. If the conversion fails, -1 is returned.
public int mapTimeToFrame(long mediaTime)
Converts the given media time to the corresponding frame number. The method only performs the calculations. It does not position the media to the given media time.
The frame returned is the nearest frame that has a media time less than or equal to the given media time.
mapTimeToFrame(0) must not fail and must return the frame number of the first frame.
param
mediaTime the input media time for the conversion in microseconds.
return
the converted frame number for the given media time. If the conversion fails, -1 is returned.
public int seek(int frameNumber)
Seek to a given video frame. The media time of the Player will be updated to reflect the new position set.
This method can be called on a stopped or started Player. If the Player is in the Started state, this method may cause the Player to change states. If that happens, the appropriate transition events will be posted by the Player when its state changes.
If the given frame number is less than the first or larger than the last frame number in the media, seek will jump to either the first or the last frame respectively.
param
frameNumber the frame to seek to.
return
the actual frame that the Player has seeked to.
public int skip(int framesToSkip)
Skip a given number of frames from the current position. The media time of the Player will be updated to reflect the new position set.
This method can be called on a stopped or started Player. If the Player is in the Started state, the current position is changing. Hence, the frame actually skipped to will not be exact.
If the Player is in the Started state, this method may cause the Player to change states. If that happens, the appropriate transition events will be posted.
If the given framesToSkip will cause the position to extend beyond the first or last frame, skip will jump to the first or last frame respectively.
param
framesToSkip the number of frames to skip from the current position. If framesToSkip is positive, it will seek forward by framesToSkip number of frames. If framesToSkip is negative, it will seek backward by framesToSkip number of frames. e.g. skip(-1) will seek backward one frame.
return
the actual number of frames skipped.