org.havi.ui
Class HScreenConfigTemplate

java.lang.Object
  extended by org.havi.ui.HScreenConfigTemplate
Direct Known Subclasses:
HBackgroundConfigTemplate, HGraphicsConfigTemplate, HVideoConfigTemplate

public abstract class HScreenConfigTemplate
extends java.lang.Object

This class describes a configuration of a screen device in terms of various properties and their importance to the application. It is used to request a valid instance of a configuration conforming to the description provided. Sub-classes of this define additional constants which may be used for additional properties. Those classes can be sub-classed in turn to add further properties by systems using the HAVi UI.

In the event of conflicting preferences between HScreenConfigTemplates (for example where a configuration is requested which conflicts with an existing configuration) the following rules shall be applied in all cases.

Several preferences in this class are required to be not filled in by the platform in templates generated by the platform. This shall mean:


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

ParameterDescriptionDefault value Set methodGet method
None.

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
None.

See Also:
HBackgroundConfigTemplate, HGraphicsConfigTemplate, HVideoConfigTemplate

Field Summary
static HScreenConfigTemplate DISABLED
          A special template indicating that an HScreenDevice is disabled.
static int DONT_CARE
          A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that the presence or absence of this feature in the HScreenConfiguration does not matter.
static int FLICKER_FILTERING
          A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports flicker filtering (if it supports an interlaced screen).
static int INTERLACED_DISPLAY
          A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports an interlaced display.
static int PIXEL_ASPECT_RATIO
          A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the pixel aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio.
static int PIXEL_RESOLUTION
          A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the pixel resolution, as specified in a Dimension object which indicates the pixel resolution of (the area of) the graphics device (as specified using the SCREEN_RECTANGLE preference).
static int PREFERRED
          A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is desired in the HScreenConfiguration.
static int PREFERRED_NOT
          A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is desired not to be present in the HScreenConfiguration.
static int REQUIRED
          A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is required in the HScreenConfiguration.
static int REQUIRED_NOT
          A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is required not to be present in the HScreenConfiguration.
static int SCREEN_ASPECT_RATIO
          A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the screen aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio.
static int SCREEN_RECTANGLE
          A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports presentation on a particular on-screen area, as specified in an HScreenRectangle object
static int VIDEO_GRAPHICS_PIXEL_ALIGNED
          A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the display of video streams and graphics with aligned pixels of the same size.
static int ZERO_BACKGROUND_IMPACT
          A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already displayed backgrounds.
static int ZERO_GRAPHICS_IMPACT
          A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already running graphical applications.
static int ZERO_VIDEO_IMPACT
          A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already running video streams.
 
Constructor Summary
HScreenConfigTemplate()
          Creates an HScreenConfigTemplate object.
 
Method Summary
 java.lang.Object getPreferenceObject(int preference)
          Return the preference object for the specified preference.
 int getPreferencePriority(int preference)
          Return the priority for the specified preference.
 void setPreference(int preference, int priority)
          Set the indicated preference to have the specified priority.
 void setPreference(int preference, java.lang.Object object, int priority)
          Set the indicated preference (and associated value object) to have the specified priority.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REQUIRED

public static final int REQUIRED
A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is required in the HScreenConfiguration. If this feature is not available, do not select the HScreenConfiguration object.

See Also:
Constant Field Values

PREFERRED

public static final int PREFERRED
A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is desired in the HScreenConfiguration. A selection with this feature is preferred over a selection that does not include this feature, although both selections can be considered valid matches.

See Also:
Constant Field Values

DONT_CARE

public static final int DONT_CARE
A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that the presence or absence of this feature in the HScreenConfiguration does not matter. Preferences with this priority play no part in the selection procedure.

See Also:
Constant Field Values

PREFERRED_NOT

public static final int PREFERRED_NOT
A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is desired not to be present in the HScreenConfiguration. A selection without this feature is preferred over a selection that does not include this feature, although both selections can be considered valid matches.

See Also:
Constant Field Values

REQUIRED_NOT

public static final int REQUIRED_NOT
A value for use in the priority field of the setPreference(int, int) and getPreferencePriority(int) methods in the HScreenConfigTemplate that indicates that this feature is required not to be present in the HScreenConfiguration. If this feature is available, do not select the HScreenConfiguration object.

See Also:
Constant Field Values

ZERO_BACKGROUND_IMPACT

public static final int ZERO_BACKGROUND_IMPACT
A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already displayed backgrounds. If used with the REQUIRED priority, this means no changes shall be made. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities may be ignored in the selection of an HScreenConfiguration for this preference type.

This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a getConfigTemplate method) shall not have this preference filled in by the platform.

See Also:
Constant Field Values

ZERO_GRAPHICS_IMPACT

public static final int ZERO_GRAPHICS_IMPACT
A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already running graphical applications. If used with the REQUIRED priority, this means no changes shall be made. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities may be ignored in the selection of an HScreenConfiguration for this preference type.

This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a getConfigTemplate method) shall not have this preference filled in by the platform.

See Also:
Constant Field Values

ZERO_VIDEO_IMPACT

public static final int ZERO_VIDEO_IMPACT
A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration should have zero impact on already running video streams. If used with the REQUIRED priority, this means no changes shall be made. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT. priorities may be ignored in the selection of an HScreenConfiguration for this preference type.

This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a getConfigTemplate method) shall not have this preference filled in by the platform.

See Also:
Constant Field Values

INTERLACED_DISPLAY

public static final int INTERLACED_DISPLAY
A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports an interlaced display.

See Also:
Constant Field Values

FLICKER_FILTERING

public static final int FLICKER_FILTERING
A value for use in the preference field of the setPreference and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports flicker filtering (if it supports an interlaced screen).

See Also:
Constant Field Values

VIDEO_GRAPHICS_PIXEL_ALIGNED

public static final int VIDEO_GRAPHICS_PIXEL_ALIGNED
A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the display of video streams and graphics with aligned pixels of the same size. Alignment of the origins of the two pixel coordinate spaces is explicitly not required. Where a video device is moving the video relative to the screen in real time (e.g. implementing pan and scan), graphics configurations shall only support this feature where the implementation of the graphics device can track the position changes in the video device automatically.

If this preference is set and used to request an HVideoConfiguration then an HGraphicsConfiguration shall be used as the preference object. If it is set and used to request an HGraphicsConfiguration then an HVideoConfiguration shall be used as the preference object. Requesting an HVideoConfiguration which is VIDEO_GRAPHICS_PIXEL_ALIGNED with another HVideoConfiguration shall fail unless the system concerned supports two HVideoDevice objects which can support this exact feature.

This preference is used by the platform as a constraint in selecting configurations. Templates generated by the platform and then returned to applications (e.g. from a getConfigTemplate method) shall not have this preference filled in by the platform.

See Also:
Constant Field Values

PIXEL_ASPECT_RATIO

public static final int PIXEL_ASPECT_RATIO
A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the pixel aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio.

Instances of HScreenConfigTemplate generated by the platform and returned to applications (e.g. from getConfigTemplate shall have this preference set to a platform specific value with the REQUIRED priority.

See Also:
Constant Field Values

PIXEL_RESOLUTION

public static final int PIXEL_RESOLUTION
A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the pixel resolution, as specified in a Dimension object which indicates the pixel resolution of (the area of) the graphics device (as specified using the SCREEN_RECTANGLE preference).

Instances of HScreenConfigTemplate generated by the platform and returned to applications (e.g. from getConfigTemplate shall have this preference set to a platform specific value with the REQUIRED priority.

See Also:
Constant Field Values

SCREEN_RECTANGLE

public static final int SCREEN_RECTANGLE
A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports presentation on a particular on-screen area, as specified in an HScreenRectangle object

Use of this value with an HScreenRectangle object other than the identity rectangle [0, 0 -> 1, 1] implies scaling of the presentation to fit within the specified HScreenRectangle.

Platforms not supporting such scaling at all or choosing to expose such scaling through other APIs should only return HScreenConfigTemplates with the HScreenRectangle [0, 0 -> 1, 1] for the SCREEN_RECTANGLE preference.

Instances of HScreenConfigTemplate generated by the platform and returned to applications (e.g. from getConfigTemplate shall have this preference set to a platform specific value with the REQUIRED priority.

See Also:
Constant Field Values

SCREEN_ASPECT_RATIO

public static final int SCREEN_ASPECT_RATIO
A value for use in the preference field of the setPreference, getPreferenceObject and getPreferencePriority methods in the HScreenConfigTemplate that indicates that the device configuration supports the screen aspect ratio, as specified in a Dimension object which indicates the (relative) x, y pixel aspect ratio. Typical values are 4:3 and 16:9.

Instances of HScreenConfigTemplate generated by the platform and returned to applications (e.g. from getConfigTemplate shall have this preference set to a platform specific value with the REQUIRED priority.

Since:
MHP 1.1.3
See Also:
Constant Field Values

DISABLED

public static HScreenConfigTemplate DISABLED
A special template indicating that an HScreenDevice is disabled. Disabled HScreenDevice instances are not being composited as part of the video output signal of the HScreen. The preferences, properties and attributes of this HScreenConfigTemplate are implementation dependent.

Constructor Detail

HScreenConfigTemplate

public HScreenConfigTemplate()
Creates an HScreenConfigTemplate object. See the class description for details of constructor parameters and default values.

Method Detail

setPreference

public void setPreference(int preference,
                          int priority)
Set the indicated preference to have the specified priority. If the preference has been previously set, then the previous priority for the preference shall be overwritten.

Attributes that are not filled in a template (through setPreference(int, int)), shall have the priority DONT_CARE. Any configuration always satisfies these attributes.

Parameters:
preference - the preference to be indicated. Valid values for an HScreenConfigTemplate are: ZERO_GRAPHICS_IMPACT, ZERO_BACKGROUND_IMPACT, ZERO_VIDEO_IMPACT, INTERLACED_DISPLAY and FLICKER_FILTERING.

Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of HScreenConfigTemplate

priority - the priority of the preference. Valid values are: REQUIRED, PREFERRED, DONT_CARE, PREFERRED_NOT and REQUIRED_NOT.

If priority is not a valid priority as defined here a java.lang.IllegalArgumentException will be thrown.


setPreference

public void setPreference(int preference,
                          java.lang.Object object,
                          int priority)
Set the indicated preference (and associated value object) to have the specified priority. If the preference has been previously set, then the previous object and priority shall be overwritten.

Attributes that are not filled in a template (through setPreference(int, int)), shall have the priority DONT_CARE. Any configuration always satisfies these attributes.

An application which wishes to remove a preference from an existing template (e.g. one generated by the platform) may call this method with null for the object parameter.

Parameters:
preference - the preference to be indicated. Valid values for an HScreenConfigTemplate are: VIDEO_GRAPHICS_PIXEL_ALIGNED, PIXEL_ASPECT_RATIO, PIXEL_RESOLUTION and SCREEN_RECTANGLE.

Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of HScreenConfigTemplate

object - the Object associated with the given preference, or null.
priority - the priority of the preference. Valid values include: REQUIRED, PREFERRED, DONT_CARE, PREFERRED_NOT and REQUIRED_NOT.

If priority is not a valid priority as defined here a java.lang.IllegalArgumentException will be thrown.


getPreferencePriority

public int getPreferencePriority(int preference)
Return the priority for the specified preference.

Individual properties in the ConfigTemplate can then be examined using the getPreferencePriority and getPreferenceObject methods -- features that are implemented will return REQUIRED, features that are not implemented will return REQUIRED_NOT.

Parameters:
preference - the preference to be indicated. Valid values for an HScreenConfigTemplate are: ZERO_BACKGROUND_IMPACT, ZERO_GRAPHICS_IMPACT, ZERO_VIDEO_IMPACT, INTERLACED_DISPLAY, FLICKER_FILTERING, VIDEO_GRAPHICS_PIXEL_ALIGNED, PIXEL_ASPECT_RATIO, PIXEL_RESOLUTION and SCREEN_RECTANGLE.

Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of HScreenConfigTemplate

Returns:
the priority for the specified preference.

getPreferenceObject

public java.lang.Object getPreferenceObject(int preference)
Return the preference object for the specified preference.

Instances of HScreenConfigTemplate which have not had this preference set shall return null for this object. Note that instances constructed by the platform and returned to applications are required to have all preferences (except where explicitly identified) set by the platform before it is returned.

Parameters:
preference - the preference to be indicated. Valid values for an HScreenConfigTemplate are: VIDEO_GRAPHICS_PIXEL_ALIGNED, PIXEL_ASPECT_RATIO, PIXEL_RESOLUTION and SCREEN_RECTANGLE.

Subclasses may add further valid values. A IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of HScreenConfigTemplate, or if preference does not have an associated value object.

Returns:
the preference object for the specified preference.