com.sun.dtv.ui
Class PlaneSetup

java.lang.Object
  com.sun.dtv.ui.PlaneSetup

public class PlaneSetup
extends Object

The PlaneSetup class is capable to describe the characteristics of a Plane. A Plane may have many PlaneSetup objects associated with it, but there always only one valid for a certain point of time.

See Also:

Plane

Constructor Summary

PlaneSetup()

Method Summary

Image	adaptImage(Image input, boolean dither) Adapts a given image if necessary in order to gain compatibility with the currently valid PlaneSetup.
Point	convertPoint(PlaneSetup destination, Point source) This method has been created to avoid rounding errors appearing during conversion of pixel positions from one coordinate system towards another one when passing through normalized coordinates.
void	displayImage(Image image) Display a (background) image on the associated Plane.
void	displayImage(Image image, Rectangle rectangle) Display an (background) image to cover a particular area of the associated Plane.
Color	getColor() Provide the currently valid background color of this plane if any.
Dimension	getOffset(PlaneSetup setup) Returns the offset between the origin of the pixel coordinate space of the specified PlaneSetup, and the origin of the current pixel coordinate space of this PlaneSetup.
PlaneSetupPattern	getPattern() Returns the PlaneSetupPattern object that describes and identifies this PlaneSetup.
Dimension	getPixelAspectRatio() Return the pixel aspect ratio of this setup.
Dimension	getPixelResolution() Return the resolution of this setup in pixels.
Plane	getPlane() Returns the Plane associated with this PlaneSetup.
Dimension	getPlaneAspectRatio() Return the aspect ratio of this setup as far as is known.
Rectangle	getScreenArea() Return the position and size of the plane associated with this setup on the Screen in screen coordinates.
Dimension	getScreenResolution() Return the current screen resolution of this setup i.e. 960 x 540, 1920 x 1080, etc.
Object	getVideoController() Deliver the presentation control object for the video currently shown by the plane associated with this setup.
Object	getVideoSource() Deliver the source of the video being presented by the plane associated with this PlaneSetup at this moment.
boolean	isDirectColorModelSupported() Indicate whether Direct Color model is supported by this setup.
boolean	isFlickeringFilterAvailable() Return whether this setup includes filtering to reduce interlace flicker.
boolean	isGraphicsMixingSupported() Indicates whether the plane setup supports the display of graphics in addition to video streams.
boolean	isImageScalingSupported() Indicate whether rapid image scaling is supported by this setup.
boolean	isIndexedColorModelSupported() Indicate whether a Color Lookup Table is supported by this setup.
boolean	isInterlaced() Return whether this setup is interlaced.
boolean	isMatteSupported() Indicate whether the mattes feature is supported by this setup.
boolean	isVideoMixingSupported() Indicate whether the setup supports transparency in the graphics system such that the output of an underlying video decoder is visible.
void	setColor(Color color) Set the valid color for the background of the plane associated with this setup to a new value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PlaneSetup

public PlaneSetup()

Method Detail

convertPoint

public Point convertPoint(PlaneSetup destination,
                          Point source)

This method has been created to avoid rounding errors appearing during conversion of pixel positions from one coordinate system towards another one when passing through normalized coordinates. As a direct conversion is not always possible, the return value may be null. Reasons for a failing conversion could be:

• at least one of the two PlaneSetups is not pixel based
• one coordinate system is transformed into the other one using a non-linear function
• the transformation function is unknown for some reason
• the transformation function is not constant over the time

The source position is interpreted in the coordinate system of the PlaneSetup object on which this method is called.

Parameters:

destination - the destination PlaneSetup.

source - the pixel position in this PlaneSetup.

Returns:

the position of the specified pixel position measured in the destination coordinate system, or null if the conversion fails.

isFlickeringFilterAvailable

public boolean isFlickeringFilterAvailable()

Return whether this setup includes filtering to reduce interlace flicker.

Returns:

true if filtering is included, false otherwise.

isInterlaced

public boolean isInterlaced()

Return whether this setup is interlaced.

Returns:

true if this setup is interlaced, false otherwise.

getOffset

public Dimension getOffset(PlaneSetup setup)

Returns the offset between the origin of the pixel coordinate space of the specified PlaneSetup, and the origin of the current pixel coordinate space of this PlaneSetup. The offset is returned in the pixel coordinate space of the PlaneSetup this method is called for.

Parameters:

setup - the target PlaneSetup

Returns:

the offset between the pixel coordinate space of the specified PlaneSetup and the current pixel coordinate space of the origin PlaneSetup. If the offset cannot be determined, null is returned.

getScreenResolution

public Dimension getScreenResolution()

Return the current screen resolution of this setup i.e. 960 x 540, 1920 x 1080, etc.

Returns:

a Dimension object specifying the screen resolution of the setup

getPlaneAspectRatio

public Dimension getPlaneAspectRatio()

Return the aspect ratio of this setup as far as is known. i.e. 4:3, 16:9, etc.

This Dimension may be used to determine the pixel aspect ratio for given PlaneSetups.

Returns:

a Dimension object specifying the aspect ratio of the setup

getPixelAspectRatio

public Dimension getPixelAspectRatio()

Return the pixel aspect ratio of this setup. Some examples are {16:15}, {64:45}, {1:1}.

Returns:

the aspect ratio of the pixels in this setup.

getPixelResolution

public Dimension getPixelResolution()

Return the resolution of this setup in pixels. The pixel coordinate system used is that of the plane associated with this setup.

Returns:

the resolution of this setup in pixels.

getScreenArea

public Rectangle getScreenArea()

Return the position and size of the plane associated with this setup on the Screen in screen coordinates.

Returns:

the area on the Screen of this setup in screen coordinates.

isVideoMixingSupported

public boolean isVideoMixingSupported()

Indicate whether the setup supports transparency in the graphics system such that the output of an underlying video decoder is visible. (This includes also video stills.) The return value can only be true if the return value of Capabilities.isImageRenderingSupported(), called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true. The following setups fulfill this requirement:

• Setups with a well defined transformation between video / still video pixels and graphics pixels (e.g. pixels are the same size).
• Setups where an application displays graphics over video / still video, while the video / still video is used as a background. Therefore there is no transformation required between the two sets of pixels in such kind of setups.

Applications may specify a particular video / still video setup with which mixing must be supported. In this case, the video / still video setup is specified as a video setup or still video setup, respectively. In cases where no specific video setup is required then it is not required to specify such a setup and null can be used instead.

Returns:

true if video mixing is supported, false otherwise

isGraphicsMixingSupported

public boolean isGraphicsMixingSupported()

Indicates whether the plane setup supports the display of graphics in addition to video streams. This is true where the screen includes planes associated to both kinds of setups where the video pixels and graphics pixels are fully aligned (same size) as well as setups where they are displayed together but where a more complex relationship exists between the two pixel coordinate spaces. The return value can only be true if the return value of Capabilities.isVideoRenderingSupported(), called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true.

Returns:

true if graphics mixing is supported, false otherwise

isMatteSupported

public boolean isMatteSupported()

Indicate whether the mattes feature is supported by this setup. The return value can only be true if the return value of Capabilities.isImageRenderingSupported(), called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true.

Returns:

true if mattes are supported, false otherwise

isImageScalingSupported

public boolean isImageScalingSupported()

Indicate whether rapid image scaling is supported by this setup. The return value can only be true if the return value of Capabilities.isImageRenderingSupported(), called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true.

Returns:

true if rapid image scaling is supported, false otherwise

isIndexedColorModelSupported

public boolean isIndexedColorModelSupported()

Indicate whether a Color Lookup Table is supported by this setup. The return value can only be true if the return value of at least one of the following methods, called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true:

• Capabilities.isImageRenderingSupported()
• Capabilities.isWidgetRenderingSupported()
• Capabilities.isGraphicsRenderingSupported()

.

Returns:

true if the indexed color model is supported, false otherwise

isDirectColorModelSupported

public boolean isDirectColorModelSupported()

Indicate whether Direct Color model is supported by this setup. The return value can only be true if the return value of at least one of the following methods, called for the instance of Capabilities associated with the plane, which is also currently associated with this setup, is also true:

• Capabilities.isImageRenderingSupported()
• Capabilities.isWidgetRenderingSupported()
• Capabilities.isGraphicsRenderingSupported()

.

Returns:

true if the direct color model is supported, false otherwise

getVideoSource

public Object getVideoSource()
                      throws SecurityException,
                             SetupException

Deliver the source of the video being presented by the plane associated with this PlaneSetup at this moment. The specification of the class to be returned is out of scope of this API. If no video is being presented, null is returned. The call to this method makes only sense if video rendering is supported by the plane associated with this setup, i.e. if the return value of Capabilities.isVideoRenderingSupported() is true. Otherwise an exception is thrown.

Returns:

a reference to the source of the video

Throws:

SecurityException - if the application currently does not have sufficient rights to get the VideoSource object

SetupException - if the associated plane does not support video rendering

getVideoController

public Object getVideoController()
                          throws SecurityException,
                                 SetupException

Deliver the presentation control object for the video currently shown by the plane associated with this setup. Null is returned if no video is being presented. A possible return object is e.g. a reference on a javax.media.Player instance which owns the resource. The call to this method makes only sense if video rendering is supported by the plane associated with this setup, i.e. if the return value of Capabilities.isVideoRenderingSupported() is true. Otherwise an exception is thrown.

Returns:

the object which controls the presentation of the video

Throws:

SecurityException - if the application does not have sufficient rights to get the VideoPlayer object.

SetupException - if the associated plane does not support video rendering

getPattern

public PlaneSetupPattern getPattern()

Returns the PlaneSetupPattern object that describes and identifies this PlaneSetup. As a consequence, by programming

 Plane.getBestSetup(PlaneSetup.getPattern())
 

one should get the original PlaneSetup

Features implemented in the PlaneSetup will then be represented in the resulting pattern with PlaneSetupPattern.REQUIRED priority. Features not implemented there are represented with PlaneSetupPattern.REQUIRED_NOT priority. Preferences unset by the platform will appear with PlaneSetupPattern.DONT_CARE priority.

Returns:

an PlaneSetupPattern object which both describes and identifies this PlaneSetup.

getPlane

public Plane getPlane()

Returns the Plane associated with this PlaneSetup.

Returns:

the Plane object that is associated with this PlaneSetup.

getColor

public Color getColor()

Provide the currently valid background color of this plane if any. Calling this method does not require the Plane to be reserved beforehand. The value returned is not guaranteed to be the one set by the last call to setColor since platforms may offer a different color space for backgrounds and the value actually used will be returned. If no background color is set for this setup, null is returned.

Returns:

the current Color of this setup

See Also:

setColor(java.awt.Color)

setColor

public void setColor(Color color)
              throws SecurityException,
                     SetupException

Set the valid color for the background of the plane associated with this setup to a new value. Passing a non-opaque color is illegal. If the available color resolution for backgrounds is not sufficient for the given value, the platform may approximate it to the nearest available. The getColor method will then return the value actually in use.

Parameters:

color - the color to be used for the background

Throws:

SecurityException - if the application has not currently reserved the Plane currently associated with this PlaneSetup or this PlaneSetup is not the currently valid one of the reserved Plane.

SetupException - if the specified color is illegal for this platform.

See Also:

getColor()

displayImage

public void displayImage(Image image)
                  throws IOException,
                         IllegalArgumentException,
                         SecurityException,
                         NullPointerException,
                         SetupException

Display a (background) image on the associated Plane. This method will block while the image data is loaded, if this hasn't been done already. Depending on the platform, the image

• is scaled to fit or
• it is cropped (where too large) or
• it is repeated (where too small).

The position of the image is also platform-dependent. If the image is not scaled to fit, the previous color set using setColor may be visible in the remaining area of the Plane.

The image will be removed if the setColor method is called afterwards.

If a call to the Capabilities.isImageRenderingSupported() returns false for the plane associated with this setup, a call to this method causes a SetupException to be thrown.

Parameters:

image - the image to be displayed.

Throws:

IOException - if the data for the com.sun.dtv.lwuit.Image cannot be not loaded.

IllegalArgumentException - if the com.sun.dtv.lwuit.Image does not contain an image in a supported image encoding format

SecurityException - if the Plane associated with this PlaneSetup has not been reserved by the calling application

SetupException - if the PlaneSetup is not the current setup for its Plane, or if it is not appropriate for rendering images.

NullPointerException - if the argument image is null

displayImage

public void displayImage(Image image,
                         Rectangle rectangle)
                  throws IOException,
                         IllegalArgumentException,
                         SecurityException,
                         NullPointerException,
                         SetupException

Display an (background) image to cover a particular area of the associated Plane. This method will block while the image data is loaded, if this hasn't been done already. Depending on the platform, the image

• is scaled to fit or
• it is cropped (where too large) or
• it is repeated (where too small).

The position of the image within the rectangle is also platform- dependent. If the image is not scaled to fit into the rectangle, or the rectangle does not cover the entire Plane area, the previous color set using setColor may be visible in the remaining area of the Plane.

The image will be removed if the setColor method is called afterwards.

If a call to the Capabilities.isImageRenderingSupported() returns false for the plane associated with this setup, a call to this method causes a SetupException to be thrown.

Parameters:

image - the image to be displayed

rectangle - the area of the Plane the image should be shown in

Throws:

IOException - if the data for the com.sun.dtv.lwuit.Image cannot be not loaded.

IllegalArgumentException - if the com.sun.dtv.lwuit.Image does not contain an image in a supported image encoding format

SecurityException - if the Plane associated with this PlaneSetup has not been reserved by the calling application

SetupException - if the PlaneSetup is not the current setup for its Plane, or if it is not appropriate for rendering images..

NullPointerException - if either or both of the arguments are null

adaptImage

public Image adaptImage(Image input,
                        boolean dither)
                 throws SetupException

Adapts a given image if necessary in order to gain compatibility with the currently valid PlaneSetup. If the type of the input image allows it, this may involve dithering to a restricted color palette. If no adaptation is necessary, the original image will be returned If a call to the Capabilities.isImageRenderingSupported() returns false for the plane associated with this setup, a call to this method causes a SetupException to be thrown.

Parameters:

input - the image to be modified if necessary

dither - a boolean that indicates whether or not the type of the input image allows dithering

Returns:

an image adapted in a way enabling optimal presentation on the Plane associated with this PlaneSetup, or the original image if no adaptation has been necessary.

Throws:

SetupException - if the PlaneSetup is not appropriate for rendering images..