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 VideoControl

All Superinterfaces:
  Control, GUIControl

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.

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 respective to the GUI object where the video is displayed.
`byte[]` | `getSnapshot(java.lang.String imageType)` Gets a snapshot of the displayed content.
`int` | `getSourceHeight()` Return the height of the source video.
`int` | `getSourceWidth()` Return the width of the source video.
`java.lang.Object` | `initDisplayMode(int mode, java.lang.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

    public static final int USE_DIRECT_VIDEO

  This defines a mode on how the video is displayed. It is used in conjunction with `initDisplayMode`.

  `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 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;
            :
         try {
             Player p = Manager.createPlayer("http://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`.

Method Detail

### initDisplayMode

    public java.lang.Object initDisplayMode(int mode,
                                            java.lang.Object arg)

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

  Two modes are defined:

  - `USE_GUI_PRIMITIVE` (inherited from GUIControl)
  - `USE_DIRECT_VIDEO`
  On platforms with LCDUI support, both modes must be supported.
  Specified by:
    `initDisplayMode` in interface `GUIControl`
  Parameters:
    `mode` - The video mode that determines how video is displayed. It can be `USE_GUI_PRIMITIVE`, `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.

### setDisplayLocation

    public 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 location (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.

### getDisplayX

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

### getDisplayY

    public int getDisplayY()

  Return the Y-coordinate of the video with respective 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.

### setVisible

    public void setVisible(boolean visible)

  Show or hide the video.

  If `USE_GUI_PRIMITIVE` is set, the video by default is shown when 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.

### setDisplaySize

    public void setDisplaySize(int width,
                               int height)
                        throws MediaException

  Resize the video image.

  If the video mode is set to `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 scaled 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).

  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.

### setDisplayFullScreen

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

### getSourceWidth

    public int getSourceWidth()

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

### getSourceHeight

    public int getSourceHeight()

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

### getDisplayWidth

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

### getDisplayHeight

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

### getSnapshot

    public byte[] getSnapshot(java.lang.String imageType)
                       throws MediaException

  Gets a snapshot of the displayed content. Features and format of the captured image are specified by the `imageType`. All implementations support at least PNG format. Available formats can be queried from `System.getProperty` with `video.snapshot.encodings` as the key.
  Parameters:
    `imageType` - Format and resolution of the returned image. If `null` is given, it will default to using the PNG format.
  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.
    `SecurityException` - Thrown if the caller does not have the security permission to take the snapshot.

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