javax.microedition.media.control
Interface FramePositioningControl

All Superinterfaces:

Control

public interface FramePositioningControl

extends 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.

Method Summary

long	mapFrameToTime(int frameNumber) Converts the given frame number to the corresponding media time.
int	mapTimeToFrame(long mediaTime) Converts the given media time to the corresponding frame number.
int	seek(int frameNumber) Seek to a given video frame.
int	skip(int framesToSkip) Skip a given number of frames from the current position.

Method Detail

seek

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.

Parameters:

frameNumber - the frame to seek to.

Returns:

the actual frame that the Player has seeked to.

skip

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.

Parameters:

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.

Returns:

the actual number of frames skipped.

mapFrameToTime

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.

Parameters:

frameNumber - the input frame number for the conversion.

Returns:

the converted media time in microseconds for the given frame. If the conversion fails, -1 is returned.

mapTimeToFrame

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.

Parameters:

mediaTime - the input media time for the conversion in microseconds.

Returns:

the converted frame number for the given media time. If the conversion fails, -1 is returned.