org.havi.ui
Class HVideoDevice

java.lang.Object
  extended byorg.havi.ui.HScreenDevice
      extended byorg.havi.ui.HVideoDevice
All Implemented Interfaces:
ResourceProxy, ResourceServer

public class HVideoDevice
extends HScreenDevice

The HVideoDevice class describes the logical video devices which can contribute to the appearance of a particular screen. Each HVideoDevice has one or more HVideoConfiguration objects associated with it. These objects specify the different configurations (settings) in which the HVideoDevice can be used. This class represents the presentation only of video and does not provide for the selection of which video is to be presented.


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:
HVideoConfiguration, HScreenDevice, HScreen

Field Summary
static HVideoConfiguration NOT_CONTRIBUTING
          Constant indicating that a video device is not contributing to the output of its HScreen.
 
Constructor Summary
protected HVideoDevice()
          It is not intended that applications should directly construct HVideoDevice objects.
 
Method Summary
 HVideoConfiguration getBestConfiguration(HVideoConfigTemplate hvct)
          Returns the "best" configuration possible that passes the criteria defined in the HVideoConfigTemplate or null.
 HVideoConfiguration getBestConfiguration(HVideoConfigTemplate[] hvcta)
          Returns the "best" configuration possible that passes the criteria defined in one of the HVideoConfigTemplate objects within the specified array or null.
 HVideoConfiguration[] getConfigurations()
          Returns all of the HVideoConfiguration objects associated with this HVideoDevice.
 HVideoConfiguration getCurrentConfiguration()
          Returns the current HVideoConfiguration for this HVideoDevice.
 HVideoConfiguration getDefaultConfiguration()
          Returns the default HVideoConfiguration associated with this HVideoDevice.
 java.lang.Object getVideoController()
          Obtain a reference to the object which controls the presentation of the video.
 java.lang.Object getVideoSource()
          Obtain a reference to the source of the video being presented by this device at this moment.
 boolean setVideoConfiguration(HVideoConfiguration hvc)
          Set the video configuration for the device.
 
Methods inherited from class org.havi.ui.HScreenDevice
addResourceStatusEventListener, addScreenConfigurationListener, addScreenConfigurationListener, getClient, getIDstring, getScreenAspectRatio, releaseDevice, removeResourceStatusEventListener, removeScreenConfigurationListener, reserveDevice
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOT_CONTRIBUTING

public static final HVideoConfiguration NOT_CONTRIBUTING
Constant indicating that a video device is not contributing to the output of its HScreen. This shall only be used in implementations where an HVideoDevice shares an underlying MPEG decoder with an HBackgroundDevice when the HBackgroundDevice is in an HStillImageBackgroundConfiguration. In such implementations, this configuration shall be returned from the getCurrentConfiguration() method when the underlying video decoder is being used for displaying HBackgroundImage. It shall not be returned from any other method. The setVideoConfiguration(org.havi.ui.HVideoConfiguration) method shall consider this to be an invalid configuration for this device and fail as specified.

On implementations where getCurrentConfiguration() never returns this value, NOT_CONTRIBUTING shall be null.

Constructor Detail

HVideoDevice

protected HVideoDevice()
It is not intended that applications should directly construct HVideoDevice objects.

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

Method Detail

getConfigurations

public HVideoConfiguration[] getConfigurations()
Returns all of the HVideoConfiguration objects associated with this HVideoDevice. The set of configurations returned may include ones which are only valid for the device at particular times or when the device is in a particular mode.

Returns:
an array of HVideoConfiguration objects
See Also:
HVideoConfiguration

getDefaultConfiguration

public HVideoConfiguration getDefaultConfiguration()
Returns the default HVideoConfiguration associated with this HVideoDevice. This (single) default configuration should correspond to some well-behaved settings for the device, such as, a minimal configuration or factory preset settings.

Returns:
the default HVideoConfiguration of this HVideoDevice.
See Also:
HVideoConfiguration

getBestConfiguration

public HVideoConfiguration getBestConfiguration(HVideoConfigTemplate hvct)
Returns the "best" configuration possible that passes the criteria defined in the HVideoConfigTemplate or null.

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:
hvct - an HVideoConfigTemplate object used to obtain a valid HVideoConfiguration. If this parameter is null the default configuration for the platform shall be returned.
Returns:
an HVideoConfiguration that passes the criteria defined in the specified HVideoConfigTemplate or null if no HVideoConfiguration passes the criteria.

getBestConfiguration

public HVideoConfiguration getBestConfiguration(HVideoConfigTemplate[] hvcta)
Returns the "best" configuration possible that passes the criteria defined in one of the HVideoConfigTemplate objects within the specified array or null. The HVideoTemplate objects should be considered for matching in priority order from 0 to (hvcta.length - 1).

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 HVideoConfigTemplate array used to obtain a valid HVideoConfiguration.
Returns:
an HVideoConfiguration that passes the criteria defined in one of the HVideoConfigTemplate objects within the specified array

getCurrentConfiguration

public HVideoConfiguration getCurrentConfiguration()
Returns the current HVideoConfiguration for this HVideoDevice.

Returns:
the current HVideoConfiguration for this HVideoDevice.
See Also:
HVideoConfiguration

setVideoConfiguration

public boolean setVideoConfiguration(HVideoConfiguration hvc)
                              throws java.lang.SecurityException,
                                     HPermissionDeniedException,
                                     HConfigurationException
Set the video configuration for the device.

An application is only allowed to call this method after it reserved the device explicitly and subject to the security policy of the platform. Subject to this, the following rules determine whether this method can succeed.

Applications can prevent or limit changes to configurations of other, not intended, devices by using constants HScreenConfigTemplate.ZERO_GRAPHICS_IMPACT, HScreenConfigTemplate.ZERO_VIDEO_IMPACT and HScreenConfigTemplate.ZERO_BACKGROUND_IMPACT in their configuration templates. The first one will cause no changes to already running graphical applications. This means that no changes may be applied to the graphics device. Similarly the second constant will result in no changes to the video device.

NOTE: If a configuration is selected which includes ZERO_GRAPHICS_IMPACT or ZERO_BACKGROUND_IMPACT and this would require changes to already running devices, then this will not be possible to apply successfully and hence this method will return false.

Any modifications made to the configurations of other devices shall be reflected by the API for the devices concerned. The HGraphicsDevice.getCurrentConfiguration() method for those devices shall return the new configuration.

On successful change to the specified configuration, the device shall fire one or more HScreenConfigurationEvent for all listeners that are currently registered (if the criteria for receiving such an event has been satisfied). If the new configuration differs by more than one characteristic from the previous configuration then the device may fire one or more HScreenConfigurationEvents. This behavior is implementation specific.

If an attempt is made to set the identical configuration to that which is current, then no such event(s) shall be fired.

Parameters:
hvc - the HVideoConfiguration to which this device should be set.
Returns:
A boolean indicating whether the configuration could be applied successfully. If the configuration could not be applied successfully, the configuration after this method may not match the configuration of the device prior to this method being called --- applications should take steps to determine whether a partial change of settings has been made.
Throws:
java.lang.SecurityException - if the application does not have sufficient rights to set the configuration for this device.
HPermissionDeniedException - if the application does not currently have the right to set the configuration for this device.
HConfigurationException - if the specified configuration is not valid for this device, or if it conflicts with other devices whose configuration(s) cannot be changed by this application.

getVideoSource

public java.lang.Object getVideoSource()
                                throws java.lang.SecurityException,
                                       HPermissionDeniedException
Obtain a reference to the source of the video being presented by this device at this moment. The precise class to be be returned must be specified outside the HAVi user- interface specification. Null is returned if no video is being presented.

Returns:
a reference to the source of the video
Throws:
java.lang.SecurityException - if the application does not have sufficient rights to get the VideoSource object.
HPermissionDeniedException - if the application does not currently have the right to get the VideoSource object.

getVideoController

public java.lang.Object getVideoController()
                                    throws java.lang.SecurityException,
                                           HPermissionDeniedException
Obtain a reference to the object which controls the presentation of the video. Null is returned if no video is being presented. In systems based on JMF, this would be the javax.media.Player instance which owns the resource.

Returns:
the object which controls the presentation of the video
Throws:
java.lang.SecurityException - if the application does not have sufficient rights to get the VideoPlayer object.
HPermissionDeniedException - this exception shall never be thrown