org.havi.ui

Class HGraphicsConfiguration

java.lang.Object

org.havi.ui.HScreenConfiguration

org.havi.ui.HGraphicsConfiguration

Direct Known Subclasses:

HEmulatedGraphicsConfiguration

public class HGraphicsConfiguration
extends HScreenConfiguration

The HGraphicsConfiguration class describes the characteristics (settings) of an HGraphicsDevice. There can be many HGraphicsConfiguration objects associated with a single HGraphicsDevice. The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
None.

See Also:

HGraphicsDevice

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HGraphicsConfiguration() An interoperable application shall not subclass the HGraphicsConfiguration class.

Method Summary

Methods

Modifier and Type	Method and Description
void	dispose(Color c) This method is used by an application when a color returned from those versions of the method getPunchThroughToBackgroundColor with a Color as a parameter is no longer required.
Font[]	getAllFonts() List the fonts that are always available on the device, but does not list fonts that may be (temporarily) available for download from other sources.
Image	getCompatibleImage(Image input, HImageHints ih) Generate a java.awt.Image which may be a modified copy of the image passed as input.
HScreenRectangle	getComponentHScreenRectangle(Component component) Returns the on-screen location of a given visible java.awt.Component as an HScreenRectangle for this HGraphicsDevice.
HGraphicsConfigTemplate	getConfigTemplate() Returns an HGraphicsConfigTemplate object that describes and uniquely identifies this HGraphicsConfiguration.
HGraphicsDevice	getDevice() Returns the HGraphicsDevice associated with this HGraphicsConfiguration.
Rectangle	getPixelCoordinatesHScreenRectangle(HScreenRectangle sr, Container cont) Returns a java.awt.Rectangle which contains the graphics (AWT) pixel area for an HScreenRectangle relative to the supplied java.awt.Container.
Color	getPunchThroughToBackgroundColor(Color color, int percentage) This method returns a Color that may be used in standard graphics drawing operations, which has the effect of "punching though" all Components that are behind the Component in which the drawing operation is performed.
Color	getPunchThroughToBackgroundColor(Color color, int percentage, HVideoDevice v) This method returns a Color that may be used in standard graphics drawing operations, which has the effect of modifying the existing color of a pixel to make it partially (or wholly) transparent to the background.
Color	getPunchThroughToBackgroundColor(int percentage) This method returns a Color that may be used in standard graphics drawing operations, which has the effect of modifying the existing color of a pixel to make it partially (or wholly) transparent to the background.
Color	getPunchThroughToBackgroundColor(int percentage, HVideoDevice hvd) This method returns a Color that may be used in standard graphics drawing operations, which has the effect of "punching though" the HGraphicsDevice in which the drawing operation is performed.

Methods inherited from class org.havi.ui.HScreenConfiguration

convertTo, getFlickerFilter, getInterlaced, getOffset, getPixelAspectRatio, getPixelResolution, getScreenArea

Methods inherited from class java.lang.Object

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

Constructor Detail

HGraphicsConfiguration

protected HGraphicsConfiguration()

An interoperable application shall not subclass the HGraphicsConfiguration class.

Creates an HGraphicsConfiguration object. See the class description for details of constructor parameters and default values.

Method Detail

getDevice

public HGraphicsDevice getDevice()

Returns the HGraphicsDevice associated with this HGraphicsConfiguration.

Returns:

the HGraphicsDevice object that is associated with this HGraphicsConfiguration,

getConfigTemplate

public HGraphicsConfigTemplate getConfigTemplate()

Returns an HGraphicsConfigTemplate object that describes and uniquely identifies this HGraphicsConfiguration.

Hence, the following sequence should return the original HGraphicsConfiguration.

 HGraphicsDevice.getBestMatch(HGraphicsConfiguration.getConfigTemplate())
 

Features that are implemented in the HGraphicsConfiguration will return HScreenConfigTemplate.REQUIRED priority. Features that are not implemented in the HGraphicsConfiguration will return HScreenConfigTemplate.REQUIRED_NOT priority. Preferences that are not filled in by the platform will return HScreenConfigTemplate.DONT_CARE priority.

Returns:

an HGraphicsConfigTemplate object which both describes and uniquely identifies this HGraphicsConfiguration.

getComponentHScreenRectangle

public HScreenRectangle getComponentHScreenRectangle(Component component)

Returns the on-screen location of a given visible java.awt.Component as an HScreenRectangle for this HGraphicsDevice.

Parameters:

component - the java.awt.Component whose on-screen area is to be determined.

Returns:

the on-screen location of component as an HScreenRectangle for this HGraphicsDevice, or null if the component is not currently added to the HScene (or one of its "child" containers).

See Also:

HScreenRectangle

getPixelCoordinatesHScreenRectangle

public Rectangle getPixelCoordinatesHScreenRectangle(HScreenRectangle sr,
                                            Container cont)

Returns a java.awt.Rectangle which contains the graphics (AWT) pixel area for an HScreenRectangle relative to the supplied java.awt.Container.

Parameters:

sr - the screen location expressed as an HScreenRectangle.

cont - the java.awt.Container in whose coordinate system the screen location should be expressed.

Returns:

a java.awt.Rectangle which contains the graphics (AWT) pixel area for an HScreenRectangle relative to the supplied java.awt.Container. The returned x, y, width, height values in the java.awt.Rectangle should be such that a

• r = getPixelCoordinatesHScreenRectangle(sr, cont);
• cont.add(component);
• component.setBounds(r.x, r.y, r.width, r.height);

should ensure that the dimensions of the component on-screen should correspond to the given HScreenRectangle, subject to clipping by its parent container, cont.

Note that the HScreenRectangle (HScreenPoint) coordinates are in floats - conversion to pixel coordinate systems necessarily implies a potential loss of precision - however, such conversion should be to the "nearest" integer pixel coordinate.

getCompatibleImage

public Image getCompatibleImage(Image input,
                       HImageHints ih)

Generate a java.awt.Image which may be a modified copy of the image passed as input. Such a copy is modified as necessary such that it is compatible with the current HGraphicsConfiguration. For example this may involve dithering the image to a restricted color palette. In the case where no modification is required a reference to the original image input will be returned instead of a separate new java.awt.Image.

Note: Unmodified Images, or Images modified for other HGraphicsConfiguration should still be able to be rendered within this HGraphicsConfiguration, but may not be as efficient (rapid) in terms of rendering, and may not be presented optimally. For example, an 8 bit per RGB pixel image loaded onto a configuration with a 4 bit per RGB pixel framebuffer may have its pixel values truncated, if this Image is then displayed on an alternate configuration with 16 bits per RGB pixel then it will obviously not be displayed optimally.

The HImageHints provide a mechanism to indicate how any conversion to a constrained graphics environment might best be performed, by describing the general image contents.

It is implementation (and algorithmically) dependent whether this method operates on partial, or complete Image pixel data.

Parameters:

input - the java.awt.Image to be modified

ih - an HImageHints object that indicates the expected type of the input Image, so that its presentation can be optimally adjusted.

Returns:

a java.awt.Image which has been determined to be optimally suited for presentation on the HGraphicsDevice associated with this HGraphicsConfiguration. Note that on some HGraphicsConfiguration a reference to the original Image may be returned, this is especially true for systems with high-end graphics capabilities.

getAllFonts

public Font[] getAllFonts()

List the fonts that are always available on the device, but does not list fonts that may be (temporarily) available for download from other sources.

Returns:

an array of java.awt.Font objects which are always available on the device.

getPunchThroughToBackgroundColor

public Color getPunchThroughToBackgroundColor(int percentage)

This method returns a Color that may be used in standard graphics drawing operations, which has the effect of modifying the existing color of a pixel to make it partially (or wholly) transparent to the background. The existing pixel percentage transparency to the background at that point shall be equivalent to the (closest) percentage value as specified in the getPunchThroughToBackgroundColor percentage parameter. A value of 0% is fully transparent and 100% is fully opaque.

The existing RGB values of the pixel are unchanged as far as possible, within the limits of the platform. Platforms with restricted color spaces may make approximations as required to obtain the best possible match.

The precise contents of the background are as defined by the platform including any HBackgroundDevice, etc.

Parameters:

percentage - the new blending value for each pixel drawn with this color with respect to what is outside this HGraphicsConfiguration. The specified value will be clamped to the range 0 to 100.

Returns:

a Color with the desired effect or null for configurations which do not or are currently unable to support this rendering mode.

getPunchThroughToBackgroundColor

public Color getPunchThroughToBackgroundColor(int percentage,
                                     HVideoDevice hvd)

This method returns a Color that may be used in standard graphics drawing operations, which has the effect of "punching though" the HGraphicsDevice in which the drawing operation is performed. The specified HVideoDevice is revealed through the drawn "hole". The value specified replaces the blending value (with respect to this HVideoDevice) of each pixel drawn with this color. The existing RGB values of the pixel are unchanged as far as possible within the limits of the platform. Platforms with restricted color spaces may make approximations as required to obtain the best match possible.

Parameters:

percentage - the new alpha value for each pixel drawn with this color with respect to the the HVideoDevice specified. The specified value will be clamped to the range 0 to 100.

hvd - the HVideoDevice to reveal.

Returns:

a Color with the desired effect or null for configurations which do not or are currently unable to support this rendering mode.

getPunchThroughToBackgroundColor

public Color getPunchThroughToBackgroundColor(Color color,
                                     int percentage)

This method returns a Color that may be used in standard graphics drawing operations, which has the effect of "punching though" all Components that are behind the Component in which the drawing operation is performed. This includes any visual Components acquired from JMF players. What is behind this HGraphicsConfiguration is revealed through the drawn "hole" blended with the graphics color specified as the first parameter to this method. Platforms with restricted color spaces may make approximations as required to obtain the best match possible.

Parameters:

color - the graphics color to blend

percentage - the blending value for this color with respect to what is outside this HGraphicsConfiguration. The specified value will be clamped to the range 0 to 100.

Returns:

a Color with the desired effect or null for configurations which do not or are currently unable to support this rendering mode.

getPunchThroughToBackgroundColor

public Color getPunchThroughToBackgroundColor(Color color,
                                     int percentage,
                                     HVideoDevice v)

This method returns a Color that may be used in standard graphics drawing operations, which has the effect of modifying the existing color of a pixel to make it partially (or wholly) transparent to the background. The existing pixel percentage transparency to the background at that point shall be equivalent to the (closest) percentage value as specified in the getPunchThroughToBackgroundColor percentage parameter.

The existing RGB values of the pixel are unchanged as far as possible, within the limits of the platform. Platforms with restricted color spaces may make approximations as required to obtain the best possible match.

The precise contents of the background are as defined by the platform including any HBackgroundDevice, etc.

Parameters:

color - the graphics color to blend

percentage - the alpha value for this color with respect to what is outside this HGraphicsConfiguration. The specified value will be clamped to the range 0 to 100.

v -

Returns:

a Color with the desired effect or null for configurations which do not or are currently unable to support this rendering mode.

dispose

public void dispose(Color c)

This method is used by an application when a color returned from those versions of the method getPunchThroughToBackgroundColor with a Color as a parameter is no longer required. It is the responsibility of applications to ensure that no pixels which they had drawn using this color are still displayed on the screen before calling this method. The result of using such a Color after calling this method is implementation dependent. Using a color obtained from another source apart from the specified methods will result in this method having no effect.

Parameters:

c - the Color which is no longer required.