org.havi.ui
Class HScreen

java.lang.Object
  extended by org.havi.ui.HScreen

public class HScreen
extends java.lang.Object

This class describes the final output composition of a device. It ties together all the (MPEG) video decoders, all the graphics sub-systems and backgrounds which are all combined together before finally being displayed. A platform with two independent displays would support two instances of this class. Where a device outputs audio closely bound with video, that audio output can also be represented through this class.

Since an HScreen represents a single video output signal from a device, all the devices which contribute to that signal must have certain properties in common. It is not possible to select conflicting configurations for different devices on the same HScreen - for example having a video device whose logical output has a 4:3 picture aspect ratio and a graphics device whose logical output has a 16:9 picture aspect ratio. This specification intentionally does not define configurations, or which configurations would be conflicting, since these are essentially region or market dependent.


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.


Method Summary
 HBackgroundConfiguration getBestConfiguration(HBackgroundConfigTemplate[] hbcta)
          Returns an HBackgroundConfiguration from an HBackgroundDevice which is present on this HScreen that best matches at least one of the specified HBackgroundConfigTemplates, or null if this is not possible.
 HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate[] hgcta)
          Returns an HGraphicsConfiguration from an HGraphicsDevice which is present on this HScreen that best matches at least one of the specified HGraphicsConfigTemplates.
 HVideoConfiguration getBestConfiguration(HVideoConfigTemplate[] hvcta)
          Returns an HVideoConfiguration from an HVideoDevice which is present on this HScreen that best matches at least one of the specified HVideoConfigTemplates.
 HScreenConfiguration[] getCoherentScreenConfigurations(HScreenConfigTemplate[] hscta)
          Return a coherent set of HScreenConfigurations matching a set of templates.
 HBackgroundDevice getDefaultHBackgroundDevice()
          Return the default background device for this screen.
 HGraphicsDevice getDefaultHGraphicsDevice()
          Return the default graphics device for this screen.
static HScreen getDefaultHScreen()
          Returns the default HScreen for this application.
 HVideoDevice getDefaultHVideoDevice()
          Return the default video device for this screen.
 java.awt.Dimension getDisplayAspectRatio()
          Return the aspect ratio of the the physical display that is connected to this HScreen as far as that is known.
 HBackgroundDevice[] getHBackgroundDevices()
          Returns a list of background devices for this screen.
 HGraphicsDevice[] getHGraphicsDevices()
          Returns a list of graphics devices for this screen.
static HScreen[] getHScreens()
          Returns all HScreens in this system.
 HVideoDevice[] getHVideoDevices()
          Returns a list of video device for this screen.
 java.awt.Dimension getScreenAspectRatio()
          Return the aspect ratio of the video output signal represented by this HScreen.
 boolean setCoherentScreenConfigurations(HScreenConfiguration[] hsca)
          Modify the settings for a set of HScreenDevices, based on their HScreenConfigurations supplied.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getHScreens

public static HScreen[] getHScreens()
Returns all HScreens in this system.

Returns:
an array of HScreens representing all HScreens in this system.

getDefaultHScreen

public static HScreen getDefaultHScreen()
Returns the default HScreen for this application. For systems where an application is associated with audio or video which is started before the application starts, this method will return the HScreen where that associated audio / video is being output.

Returns:
the default HScreen for this application.

getHVideoDevices

public HVideoDevice[] getHVideoDevices()
Returns a list of video device for this screen. For systems where an application is associated with video started before the application starts, the first entry in the array returned will be the video device where that video is being output. The devices returned shall be in z-order with each device being in front of those devices with a higher index in the array of results.

Returns:
an array of HVideoDevice objects or null if none exist.

getDefaultHVideoDevice

public HVideoDevice getDefaultHVideoDevice()
Return the default video device for this screen. Note that the HVideoDevice is the default device for rendering video, but it may not be capable of displaying graphics / mixing it with graphics concurrently.

Returns:
an HVideoDevice object or null if none exist.

getBestConfiguration

public HVideoConfiguration getBestConfiguration(HVideoConfigTemplate[] hvcta)
Returns an HVideoConfiguration from an HVideoDevice which is present on this HScreen that best matches at least one of the specified HVideoConfigTemplates. If this is not possible, null is returned.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

  1. satisfy ALL the preferences whose priority was REQUIRED
  2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
  3. satisfy as many as possible of the preferences whose priority was PREFERRED.
  4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:
hvcta - - the array of HVideoConfigTemplate objects to choose from.
Returns:
an HVideoConfiguration object that is the best matching configuration possible, or null if no HVideoConfiguration object passes the criteria.

getHGraphicsDevices

public HGraphicsDevice[] getHGraphicsDevices()
Returns a list of graphics devices for this screen.

Returns:
an array of HGraphicsDevices or null if none exist.
Since:
MHP 1.1.3 The devices returned shall be in z-order with each device being in front of those devices with a higher index in the array of results.

getDefaultHGraphicsDevice

public HGraphicsDevice getDefaultHGraphicsDevice()
Return the default graphics device for this screen. Note that the HGraphicsDevice is the default device for rendering graphics, but it may not be capable of displaying video / mixing it with graphics concurrently.

Returns:
the default graphics device for this screen or null if none exist.

getBestConfiguration

public HGraphicsConfiguration getBestConfiguration(HGraphicsConfigTemplate[] hgcta)
Returns an HGraphicsConfiguration from an HGraphicsDevice which is present on this HScreen that best matches at least one of the specified HGraphicsConfigTemplates. If this is not possible this method will attempt to construct an HEmulatedGraphicsConfiguration where the emulated configuration best matches one of the specified HGraphicsConfigTemplates. If this is not possible, null is returned.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

  1. satisfy ALL the preferences whose priority was REQUIRED
  2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
  3. satisfy as many as possible of the preferences whose priority was PREFERRED.
  4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:
hgcta - - the array of HGraphicsConfigTemplate objects to choose from.
Returns:
an HGraphicsConfiguration object that is the best matching configuration possible, or null if no HGraphicsConfiguration or HEmulatedGraphicsConfiguration object passes the criteria.

getHBackgroundDevices

public HBackgroundDevice[] getHBackgroundDevices()
Returns a list of background devices for this screen. The devices returned shall be in z-order with each device being in front of those devices with a higher index in the array of results.

Returns:
an array of HBackgroundDevices or null if none exist.

getDefaultHBackgroundDevice

public HBackgroundDevice getDefaultHBackgroundDevice()
Return the default background device for this screen.

Returns:
the default background device for this screen or null if none exist.

getBestConfiguration

public HBackgroundConfiguration getBestConfiguration(HBackgroundConfigTemplate[] hbcta)
Returns an HBackgroundConfiguration from an HBackgroundDevice which is present on this HScreen that best matches at least one of the specified HBackgroundConfigTemplates, or null if this is not possible.

Equally best in this sense means that the configurations satisfy an equal number of preferences with priorities PREFERRED and PREFERRED_NOT and all preferences with priorities REQUIRED and REQUIRED_NOT. If there are such equally best configurations, the one which is returned by this method is an implementation dependent selection from among those which are equally best.

Configurations are chosen according to the following algorithm, based on the priority as supplied to setPreference. Configurations must:

  1. satisfy ALL the preferences whose priority was REQUIRED
  2. satisfy NONE of the preferences whose priority was REQUIRED_NOT
  3. satisfy as many as possible of the preferences whose priority was PREFERRED.
  4. satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no configuration exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:
hbcta - the array of HBackgroundConfiguration objects to choose from, represented as an array of HBackgroundConfiguration objects.
Returns:
an HBackgroundConfiguration object that is the best matching configuration possible, or null if no HBackgroundConfiguration passes the criteria.

getCoherentScreenConfigurations

public HScreenConfiguration[] getCoherentScreenConfigurations(HScreenConfigTemplate[] hscta)
Return a coherent set of HScreenConfigurations matching a set of templates. One HScreenConfiguration will be returned for each HScreenConfigTemplate provided as input. The class of the returned objects will correspond to the class of the templates provided as input - where an HGraphicsConfigTemplate is provided as input, an HGraphicsConfiguration shall be returned. Where an HVideoConfigTemplate is provided as input, an HVideoConfiguration shall be returned. If more than one template of the same type is provided then the configurations returned must be on different devices but presented on the same screen. If more templates of one type are provided than there are devices of that type in the system, this function will return null.

Coherent means that all the required properties are respected in all of the templates provided and that a configuration can be returned for each template provided.

Conflicts between templates are resolved as discussed in the description of HScreenConfigTemplate.

Both the input to this method and the output from this method shall be sorted in z-order. Where more than one template of the same type is provided, the returned configurations shall be in the same z-order as the templates in the input. e.g. if the template at index 0 in the input requests a resolution of 960x540 and the template at index 1 in the input requests a resolution of 720x576 then the configuration at index 0 in the output shall have a resolution of 960x540 and the configuration at index 1 in the output shall have a resolution of 720x576. If the z-order requirement cannot be met, this function shall return null. The special HScreenConfigTemplate DISABLED should not normally be requested in this method since more capable GEM terminals may be able to support more than what is requested.

Parameters:
hscta - an array of objects describing desired / required configurations. If a zero-length array is passed this function will throw a java.lang.IllegalArgumentException.
Returns:
an array of non-null objects describing a coherent set of screen device configurations or null if no such coherent set is possible.

setCoherentScreenConfigurations

public boolean setCoherentScreenConfigurations(HScreenConfiguration[] hsca)
                                        throws java.lang.SecurityException,
                                               HPermissionDeniedException,
                                               HConfigurationException
Modify the settings for a set of HScreenDevices, based on their HScreenConfigurations supplied. Settings should be modified atomically (where possible) or should not be modified if the HScreenConfigurations can be determined to be conflicting a priori, i.e. are not "coherent", or would cause an exception to be thrown.

Parameters:
hsca - the array of configurations that should be applied atomically (where possible). If the length of this array is zero a java.lang.IllegalArgumentException will be thrown.
Returns:
A boolean indicating whether all HScreenConfigurations could be applied successfully. If all of the HScreenConfigurations could not be applied successfully, the configuration after this method may not match the configuration of the devices prior to this method being called --- applications should take steps to determine whether a partial change of settings has been made on each device.
Throws:
java.lang.SecurityException - if the application does not have sufficient rights to set the HScreenConfiguration for any of the devices.
HPermissionDeniedException - if the application does not currently have the right to set the configuration for any of the devices.
HConfigurationException - if the specified HScreenConfiguration[] array is not valid for any of the devices or if the z-order of the configurations in the array does not match the z-order of the devices.

getScreenAspectRatio

public java.awt.Dimension getScreenAspectRatio()
Return the aspect ratio of the video output signal represented by this HScreen.

Returns:
a Dimension object specifying the aspect ratio of the video output signal
Since:
MHP 1.1.3

getDisplayAspectRatio

public java.awt.Dimension getDisplayAspectRatio()
Return the aspect ratio of the the physical display that is connected to this HScreen as far as that is known. The extent to which this is known depends on the connector and protocol used to connect the display. Some connectors may support a protocol signalling the display aspect ratio. Otherwise the display aspect ratio may be a user setting entered as part of the configuration process of the GEM terminal.

Returns:
a Dimension object specifying the aspect ratio of the display
Since:
MHP 1.1.3
See Also:
VideoFormatControl.getDisplayAspectRatio()