javax.microedition.media.control
Interface VideoControl

All Superinterfaces:

Control, GUIControl

All Known Subinterfaces:

AdvancedVideoControl

public interface VideoControl
extends GUIControl

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

Since:

BlackBerry API 4.0.0

Field Summary
static int	USE_DIRECT_VIDEO This defines a mode on how the video is displayed.

Fields inherited from interface javax.microedition.media.control.GUIControl

USE_GUI_PRIMITIVE

Method Summary
int	getDisplayHeight() Return the actual height of the current render video.
int	getDisplayWidth() Return the actual width of the current render video.
int	getDisplayX() Return the X-coordinate of the video with respect to the GUI object where the video is displayed.
int	getDisplayY() Return the Y-coordinate of the video with respect to the GUI object where the video is displayed.
byte[]	getSnapshot(String imageType) Get a snapshot of the displayed content.
int	getSourceHeight() Return the height of the source video.
int	getSourceWidth() Return the width of the source video.
Object	initDisplayMode(int mode, Object arg) Initialize the mode on how the video is displayed.
void	setDisplayFullScreen(boolean fullScreenMode) Set the size of the render region for the video clip to be fullscreen.
void	setDisplayLocation(int x, int y) Set the location of the video with respect to the canvas where the video is displayed.
void	setDisplaySize(int width, int height) Resize the video image.
void	setVisible(boolean visible) Show or hide the video.

Field Detail

USE_DIRECT_VIDEO

static final int USE_DIRECT_VIDEO

This defines a mode on how the video is displayed. It is used in conjunction with VideoControl.initDisplayMode(int, java.lang.Object).

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.

initDisplayMode returns null in this mode.

Here is one sample usage scenario:

    javax.microedition.lcdui.Canvas canvas;
    // canvas must be created before being used in the following code.

    try {
        Player p = Manager.createPlayer("http://mymachine/abc.mpg");
        p.realize();
        VideoControl vc;
        if ((vc = (VideoControl)p.getControl("VideoControl")) != null) {
            vc.initDisplayMode(VideoControl.USE_DIRECT_VIDEO, canvas);
            vc.setVisible(true);
        }
        p.start();
    } catch (MediaException pe) {
    } catch (IOException ioe) {
    }
 

Value 1 is assigned to USE_DIRECT_VIDEO.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

initDisplayMode

Object initDisplayMode(int mode,
                       Object arg)

Initialize the mode on how the video is displayed. This method must be called before the video can be displayed.

Two modes are defined:

• USE_GUI_PRIMITIVE (inherited from GUIControl)
• VideoControl.USE_DIRECT_VIDEO

On platforms with LCDUI support, both modes must be supported. For RIM specific Video Mode implementations see @see net.rim.device.api.media.control.AdvancedVideoControl#GUI_ADVANCED

Specified by:

initDisplayMode in interface GUIControl

Parameters:

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.

Parameters:

x - The x coordinate (in pixels) of the video location.

y - The y coordinate (in pixels) of the video location.

Throws:

IllegalStateException - Thrown if initDisplayMode has not been called.

Since:

BlackBerry API 4.0.0

getDisplayX

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

Parameters:

visible - Show the video if true, hide it otherwise.

Throws:

IllegalStateException - Thrown if initDisplayMode has not been called.

Since:

BlackBerry API 4.0.0

setDisplaySize

void setDisplaySize(int width,
                    int height)
                    throws MediaException

Resize the video image.

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.

Parameters:

width - Desired width (in pixels) of the display window.

height - Desired height (in pixels) of the display window.

Throws:

IllegalArgumentException - Thrown if the given width and height are non-positive values.

IllegalStateException - Thrown if initDisplayMode has not been called.

MediaException - Thrown if resizing is not supported or the operation failed due to hardware or software limitations.

Since:

BlackBerry API 4.0.0

setDisplayFullScreen

void setDisplayFullScreen(boolean fullScreenMode)
                          throws MediaException

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.

IllegalStateException - Thrown if initDisplayMode has not been called.

Since:

BlackBerry API 4.0.0

getSourceWidth

int getSourceWidth()

Return the width of the source video. The width must be a positive number.

Returns:

the width of the source video

Since:

BlackBerry API 4.0.0

getSourceHeight

int getSourceHeight()

Return the height of the source video. The height must be a positive number.

Returns:

the height of the source video

Since:

BlackBerry API 4.0.0

getDisplayWidth

int getDisplayWidth()

Return the actual width of the current render video.

Returns:

width of the display video

Throws:

IllegalStateException - Thrown if initDisplayMode has not been called.

Since:

BlackBerry API 4.0.0

getDisplayHeight

int getDisplayHeight()

Return the actual height of the current render video.

Returns:

height of the display video

Throws:

IllegalStateException - Thrown if initDisplayMode has not been called.

Since:

BlackBerry API 4.0.0

getSnapshot

byte[] getSnapshot(String imageType)
                   throws MediaException

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.

Returns:

image as a byte array in required format.

Throws:

IllegalStateException - Thrown if initDisplayMode has not been called.

MediaException - Thrown if the requested format is not supported or the Player does not support snapshots.

SecurityException - Thrown if the caller does not have the security permission to take the snapshot.

Since:

BlackBerry API 4.0.0