HGraphicsConfiguration

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Method Summary
`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
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD