Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD