javax.microedition.media.control
Interface VideoControl

VideoControl controls the display of video. A
Player which supports the playback of video must provide a
VideoControl via its getControl and
getControls method.
For RIM specific Video Mode implementations
see @see net.rim.device.api.media.control.AdvancedVideoControl#GUI_ADVANCED

USE_DIRECT_VIDEO

USE_DIRECT_VIDEO mode can only be used on platforms
with LCDUI support.

When USE_DIRECT_VIDEO is specified for
initDisplayMode, the arg argument must not be
null and must be a javax.microedition.lcdui.Canvas or a
subclass of it. In this mode, the video is directly rendered onto the
canvas. The region where the video is rendered can be set by the
setDisplayLocation method. By default, the location is
(0,0). Drawing any graphics or rendering other video at the same region
on the canvas may not be supported.

mode - The video mode that determines how video is displayed. It
can be USE_GUI_PRIMITVE, USE_DIRECT_VIDEO or an implementation-specific
mode.

arg - The exact semantics of this argument is specified in the
respective mode definitions.

Returns:

The exact semantics and type of the object returned are
specified in the respective mode definitions.

Throws:

IllegalStateException - Thrown if initDisplayMode is
called again after it has previously been called successfully.

IllegalArgumentException - Thrown if the mode or
arg argument is invalid. mode must be
USE_GUI_PRIMITIVE, USE_DIRECT_VIDEO, or a
custom mode supported by this implementation. arg must
conform to the conditions defined by the respective mode
definitions. Refer to the mode definitions for the required type of
arg.

Since:

BlackBerry API 4.0.0

setDisplayLocation

void setDisplayLocation(int x,
int y)

Set the location of the video with respect to the canvas where the video
is displayed.

This method only works when the USE_DIRECT_VIDEO mode
is set. In USE_GUI_PRIMITIVE mode, this call will be
ignored.

The location is specified in pixel values relative to the upper left
hand corner of the GUI object.

By default, video appears at locaion (0,0).

The location can be given in negative values or can be greater than
the actual size of the canvas. When that happens, the video should be
clipped to the boundaries of the canvas.

getDisplayX

Return the X-coordinate of the video with respect to the GUI object
where the video is displayed. The coordinate is specified in pixel
values relative to the upper left hand corner of the GUI object.

The return value is undefined if initDisplayMode has
not been called.

Returns:

the X-coordinate of the video.

Since:

BlackBerry API 4.0.0

getDisplayY

int getDisplayY()

Return the Y-coordinate of the video with respect to the GUI object
where the video is displayed. The coordinate is specified in pixel
values relative to the upper left hand corner of the GUI object.

The return value is undefined if initDisplayMode has
not been called.

Returns:

the Y-coordinate of the video.

Since:

BlackBerry API 4.0.0

setVisible

void setVisible(boolean visible)

Show or hide the video.

If USE_GUI_PRIMITIVE is set, the video by default is
shown wwhen the GUI primitive is displayed. If
USE_DIRECT_VIDEO is set, the video by default is not shown
when the canvas is displayed until setVisible(true) is
called. If the canvas is removed from the screen, the video will not be
displayed.

setDisplaySize

If the video mode is USE_DIRECT_VIDEO, setting the size
of the video will not affect the size of the GUI object that the video
is displayed. If the video is called to beyond the size of the GUI
object, the video will be clipped.

If the video mode is set to USE_GUI_PRIMITIVE, Scaling
the video will also scale the GUI object.

The actual scaling algorithm is left up to the underlying
implementation. If the dimensions of the requested display size are
smaller than the dimensions of the video clip, some implementations may
choose to merely clip the video while other implementations may resize
the video.

If the dimensions of the requested display size are bigger than the
dimensions of the video clip, some implementations may resize the video
while others may leave the video clip in the original size and just
enlarge the display region. It is left up to the implementation where
the video clip is placed in the display region in this instance (i.e.,
it can be in the center of the window or in a corner of the window).

RIM Implementation Notes

The Scaling Algorithm Is As Follows:

The video will be scaled vertically until it reaches the top of the GUI object,
and horizontally preserving the original source aspect ratio. Then the left
and right areas of the GUI object will be filled with black vertical bars to
fill in the areas of the GUI object not covered by the new scaled video. If
performing this scaling puts the width of the resulting video frame outside of the
GUI object (widescreen content for example) the video instead will be scaled
horizontally until the width extends the width of the GUI object, and vertically
preserving the original source aspect ratio. Then the top and bottom areas
of the GUI object will be filled with black bars to fill in the areas not
covered by the video.

At all times the original aspect ratio of the video source is preserved, and
no video will be displayed outside of the GUI object. That is, video
cannot be scaled past the boundaries of the GUI object.

setDisplayFullScreen

Set the size of the render region for the video clip to be
fullscreen. It is left up to the underlying implementation how
fullscreen mode is implemented and what actual dimensions constitutes
fullscreen. This is useful when the application does not know the actual
width and height dimensions that are needed to make
setDisplaySize(width, height) go to fullscreen mode. For example, on a
device with a 400 pixel wide by 200 pixel high screen, a video clip that
is 50 pixels wide by 100 pixels high in fullscreen mode may be 100
pixels wide by 200 pixels high if the underlying implementation wants to
preserve the aspect ratio. In this case, an exception is not thrown.

Parameters:

fullScreenMode - Indicates whether or not to render in full screen
mode

Throws:

MediaException - Thrown if resizing to full screen size is not
supported.

getSnapshot

Get a snapshot of the displayed content. Features and format of the
captured image are specified by imageType. Supported
formats can be queried from System.getProperty with
video.snapshot.encodings as the key. The first format in
the supported list is the default capture format.

RIM Implementation Notes

The behaviour of calling this function when Player.start() has not been
called or the player is in CLOSED state is undefined.

Parameters:

imageType - Format and resolution of the returned image. If
null is given, the default capture format is used.

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.Java is a trademark of Oracle America Inc. in the US and other countries.Legal