javax.media.control
Interface FramePositioningControl

public interface FramePositioningControl

extends Control

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

Frame numbers for a bounded movie should generally begin with 0, corresponding to media time 0. Each video frame of a movie should 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. A MediaTimeSetEvent will be sent.

Since:

JMF 2.0

Field Summary

static int	FRAME_UNKNOWN
static Time	TIME_UNKNOWN

Method Summary

Time	mapFrameToTime(int frameNumber) Converts the given frame number to the corresponding media time.
int	mapTimeToFrame(Time 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.

Methods inherited from interface javax.media.Control

getControlComponent

Field Detail

TIME_UNKNOWN

public static final Time TIME_UNKNOWN

FRAME_UNKNOWN

public static final int FRAME_UNKNOWN

Method Detail

seek

public int seek(int frameNumber)

Seek to a given video frame.

The Player (or Processor) will attempt to jump to the given frame. The frame that the Player actually jumped to will be returned.

The media time of the Player will be updated to reflect the new position set. A MediaTimeSetEvent will be sent.

This method can be called on a stopped or started Player. Like setMediaTime, if the Player is in the Started state, this method may cause the Player to change states. If that happens, the appropriate TransitionEvents will be posted by the Player when its state changes.

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 Player (or Processor) will attempt to skip the given number of frames relative to the current position. The actual number of frames skipped will be returned.

The media time of the Player will be updated to reflect the new position set. A MediaTimeSetEvent will be sent.

This method can be called on a stopped or started Player. If the Player is in the Started state, the current position is not exact/well-defined. Hence, the frame actually skipped to will not be exact.

Like setMediaTime, if the Player is in the Started state, this method may cause the Player to change states. If that happens, the appropriate TransitionEvents will be posted by the Player when its state changes.

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 step backward one frame.

Returns:

the actual number of frames skipped.

mapFrameToTime

public Time mapFrameToTime(int frameNumber)

Converts the given frame number to the corresponding media time.

Parameters:

frameNumber - the input frame number for the conversion.

Returns:

the converted media time for the given frame. If the conversion fails, TIME_UNKNOWN is returned.

mapTimeToFrame

public int mapTimeToFrame(Time mediaTime)

Converts the given media time to the corresponding frame number.

The frame returned is the nearest frame that has a media time less than or equal to the given media time.

Parameters:

mediaTime - the input media time for the conversion.

Returns:

the converted frame number the given media time. If the conversion fails, FRAME_UNKNOWN is returned.