org.ocap.ui
Interface MultiScreenContext

All Known Subinterfaces:
MultiScreenConfigurableContext

public interface MultiScreenContext

This interface provides a set of tools for accomplishing the following:

  1. distinguishing between HScreen instances that are directly associated with a VideoOutputPort and those that are indirectly associated with a VideoOutputPort through a logical mapping process; i.e., discovering whether an HScreen is a display screen or a logical screen;
  2. discovering the unique platform identifier of an HScreen instance's underlying resource;
  3. discovering the category assigned to an HScreen within its containing MultiScreenConfiguration;
  4. discovering the mapping of logical HScreens to display HScreens including the area (extent) on the display HScreen where the logical HScreen appears, its visibility, and its z-order;
  5. discovering the z-order of HScreenDevices within an HScreen;
  6. discovering the set of ServiceContexts associated with an HScreen;
  7. discovering the association of display HScreens and corresponding VideoOutputPort instances;
  8. discovering the set of HScreenDevices whose generated audio constitute the set of audio sources of an HScreen;
  9. discovering the current audio focus assignment of a display HScreen;
  10. obtaining notification of changes in state of this MultiScreenContext or certain changes in the the HScreen instance that implements this interface;
  11. obtaining notification of changes to the per-display multiscreen configuration of a display screen;
  12. discovering the set of per-display multiscreen configurations that may be used with a display screen;
  13. obtaining the currently active per-display multiscreen configuration of a display screen;

If an OCAP implementation does not support the OCAP Multiscreen Manager (MSM) Extension and does not otherwise support this interface, then an OCAP application MAY assume that the behavior of an HScreen is equivalent to an HScreen instance that does implement this interface, MultiScreenContext, whose methods would behave as follows:

An MSM implementation SHALL support the MultiScreenContext interface on every HScreen instance.

Since:
MSM I01
Author:
Glenn Adams

Field Summary
static int SCREEN_TYPE_DISPLAY
          If an HScreen is directly associated with a VideoOutputPort and the extent of the HScreen is mapped to the extent of the video raster produced from the VideoOutputPort, then the type of the HScreen is SCREEN_TYPE_DISPLAY, and is referred to as a display HScreen.
static int SCREEN_TYPE_LOGICAL
          If an HScreen is not directly associated with a VideoOutputPort or the extent of the HScreen is mapped to a sub-region of the video raster produced from some VideoOutputPort, then the type of the HScreen is SCREEN_TYPE_LOGICAL, and is referred to as a logical HScreen.
 
Method Summary
 void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
          Add a listener to be notified upon the occurence of multiscreen configuration events that apply to this screen in the case it is a display screen.
 void addScreenContextListener(MultiScreenContextListener listener)
          Add screen context listener.
 HScreen getAudioFocus()
          Obtain the audio focus screen.
 HScreenDevice[] getAudioSources()
          Obtain audio sources of this screen.
 HScreenRectangle getDisplayArea()
          Obtain area of the display screen to which this screen is mapped.
 HScreen getDisplayScreen()
          Obtain display screen with which this screen is associated.
 String getID()
          Obtain a platform dependent unique identifier for the underlying collection of screen resources denoted by this screen, where the scope for uniqueness is no smaller than the set of screens associated with the currently active per-platform multiscreen configuration and all active per-display multiscreen configurations.
 MultiScreenConfiguration getMultiScreenConfiguration()
          Obtain the currently active per-display multiscreen configuration for this display screen.
 MultiScreenConfiguration[] getMultiScreenConfigurations()
          Obtain set of all per-display multiscreen configurations currently associated with this display screen where the configuration type of any such multiscreen configuration SHALL NOT be SCREEN_CONFIGURATION_DISPLAY).
 MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType)
          Obtain per-display multiscreen configurations of a specific type associated with this display screen.
 VideoOutputPort[] getOutputPorts()
          Obtain video ports to which screen is mapped.
 String getScreenCategory()
          Obtain the screen category of this HScreen instance.
 int getScreenType()
          Obtain the type of this HScreen.
 ServiceContext[] getServiceContexts()
          Obtain service contexts associated with this screen.
 boolean getVisible()
          Obtain screen visibility.
 int getZOrder()
          Obtain screen z-order.
 int getZOrder(HScreenDevice device)
          Obtain screen device z-order within this screen.
 void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
          Remove a listener previously added to be notified upon the occurence of multiscreen configuration events.
 void removeScreenContextListener(MultiScreenContextListener listener)
          Remove screen context listener.
 

Field Detail

SCREEN_TYPE_DISPLAY

static final int SCREEN_TYPE_DISPLAY
If an HScreen is directly associated with a VideoOutputPort and the extent of the HScreen is mapped to the extent of the video raster produced from the VideoOutputPort, then the type of the HScreen is SCREEN_TYPE_DISPLAY, and is referred to as a display HScreen.

Since:
MSM I01
See Also:
Constant Field Values

SCREEN_TYPE_LOGICAL

static final int SCREEN_TYPE_LOGICAL
If an HScreen is not directly associated with a VideoOutputPort or the extent of the HScreen is mapped to a sub-region of the video raster produced from some VideoOutputPort, then the type of the HScreen is SCREEN_TYPE_LOGICAL, and is referred to as a logical HScreen. A logical HScreen MAY be associated with a display HScreen. If a logical HScreen is not associated with a display HScreen, then a visible or audible manifestation SHALL NOT be produced by any ServiceContext associated with the logical HScreen.

Note: A logical HScreen that is not associated with a display HScreen may be decoding and using content for some purpose other than presentation, e.g., it may be recording the content from a ServiceContext for future presentation

Since:
MSM I01
See Also:
Constant Field Values
Method Detail

getScreenType

int getScreenType()
Obtain the type of this HScreen.

Returns:
An integer value denoted by SCREEN_TYPE_DISPLAY or SCREEN_TYPE_LOGICAL.
Since:
MSM I01

getID

String getID()
Obtain a platform dependent unique identifier for the underlying collection of screen resources denoted by this screen, where the scope for uniqueness is no smaller than the set of screens associated with the currently active per-platform multiscreen configuration and all active per-display multiscreen configurations. It is implementation dependent whether the scope for screen identifier uniqueness includes other, non-active multiscreen configurations or not.

A screen identifier SHALL NOT be equal to any screen category returned by getScreenCategory().

If S1 and S2 are instances of HScreen in the context of the implemented scope of uniqueness and MultiScreenManager.sameResources(S1,S2) returns false, then ((MultiScreenContext)S1).getID() and ((MultiScreenContext)S2).getID() SHALL NOT return the same (equivalent) string; conversely, if MultiScreenManager.sameResources(S1,S2) returns true, then ((MultiScreenContext)S1).getID() and ((MultiScreenContext)S2).getID() SHALL return the same (equivalent) string.

Returns:
A string value denoting the collection of underlying resources this HScreen instance represents in the implemented scope of uniqueness.
Since:
MSM I01
See Also:
HScreen

getScreenCategory

String getScreenCategory()
Obtain the screen category of this HScreen instance.

Returns:
A String that is either (1) an element of the following enumeration of constants defined by MultiScreenConfiguration: { SCREEN_CATEGORY_DISPLAY, SCREEN_CATEGORY_MAIN, SCREEN_CATEGORY_PIP, SCREEN_CATEGORY_POP, SCREEN_CATEGORY_OVERLAY, SCREEN_CATEGORY_GENERAL }, or (2) a string value that denotes a platform-dependent screen category and that starts with the prefix "x-".
Since:
MSM I01

getVisible

boolean getVisible()
Obtain screen visibility.

Determine whether this HScreen is marked as visible for presentation on some display HScreen, where "visible" is defined as producing a raster signal to a VideoOutputPort, whether or not the VideoOutputPort is enabled or disabled. A display HScreen SHALL remain marked as visible. A logical HScreen MAY be visible or hidden (not visible).

Returns:
A boolean value indicating whether this HScreen is marked visible or not on some display HScreen.
Since:
MSM I01

getZOrder

int getZOrder()
Obtain screen z-order.

Determine the z-order of this HScreen. An display HScreen SHALL always return a z-order of zero. A logical HScreen MAY be assigned a z-order of 1 or greater, unless it is not associated with a display HScreen, in which case its z-order is -1.

A greater z-order denotes a more front-most (top-most) order among a set of HScreen instances.

Returns:
A value indicating the z-order of this HScreen or -1. If this HScreen is a logical HScreen that is not associated with a display HScreen, then -1 SHALL be returned.
Since:
MSM I01

getZOrder

int getZOrder(HScreenDevice device)
              throws IllegalArgumentException
Obtain screen device z-order within this screen.

Determine the z-order of a specified HScreenDevice with an HScreen where the following constraints apply:

A greater z-order denotes a more front-most (top-most) order among a set of HScreenDevice instances within an HScreen instance.

Each distinct set of underlying screen devices represented as an HScreen instance constitutes a distinct z-ordering; i.e., given multiple HScreen instances representing distinct underlying screens, the set of z-order values assigned to the underlying screen device resources of these screens may reuse the same z-order indices.

Parameters:
device - an HScreenDevice that is associated with this screen.
Returns:
A non-negative value indicating the z-order of the specified HScreenDevice.
Throws:
IllegalArgumentException - if device is not an HScreenDevice of this screen.
Since:
MSM I01

getAudioSources

HScreenDevice[] getAudioSources()
Obtain audio sources of this screen.

Obtain the set of HScreenDevice from which presented audio is selected (and mixed) for the purpose of audio presentation from this screen.

The default set of audio sources of a screen consists of all HScreenDevice instances association with the screen.

The order of entries in the array returned by this method is not defined by this specification and SHALL be considered implementation dependent.

Returns:
A reference to an (possibly empty) array of HScreenDevice instances, where each such instance contributes to a mixed, audio presentation from this screen, or, if this screen does not support mixed audio, then at most one entry will be present in the returned array.
Since:
MSM I01

getAudioFocus

HScreen getAudioFocus()
Obtain the audio focus screen.

The audio focus screen of this HScreen is determined according to the following ordered rules, where the first rule that applies is used and others are ignored:

  1. If this HScreen is a logical screen, then apply the following ordered sub-rules:
    1. If this logical HScreen is mapped to a display screen, then apply the following sub-rules:
      1. If this logical HScreen is currently assigned audio focus in the context of its display screen, then this logical HScreen is returned.
      2. Otherwise (not currently assigned audio focus in its display screen), null is returned.
    2. Otherwise (not mapped to a display screen), if this logical HScreen is directly mapped to a video output port, then this HScreen is returned.
    3. Otherwise (not mapped to a display screen and not directly mapped to a video output port), null is returned.
  2. Otherwise (this HScreen is a display screen), apply the following sub-rules:
    1. If some logical screen that is mapped to this display screen is assigned audio focus, then that logical HScreen is returned;
    2. Otherwise (no logical screen is mapped to this display screen or no logical screen mapped to this display screen is assigned audio focus), then return this display HScreen.

The audio focus screen of a display screen is the screen whose currently selected audio sources are assigned to be rendered on all (implied) audio presentation devices of all video output ports to which the display screen is mapped.

Returns:
an HScreen instance or null as described above.
Since:
MSM I01
See Also:
MultiScreenConfigurableContext.assignAudioFocus()

getOutputPorts

VideoOutputPort[] getOutputPorts()
Obtain video ports to which screen is mapped.

Obtain the set of VideoOutputPorts associated with this HScreen. If this HScreen's type is SCREEN_TYPE_DISPLAY, then the VideoOutputPort instances associated with this display screen SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is associated with a display HScreen, then the VideoOutputPort instances associated with that display HScreen SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is not associated with a display HScreen, then an empty array SHALL be returned.

Returns:
A reference to an array of VideoOutputPort instances. If the returned array is empty, then this HScreen is not associated with any VideoOutputPort.
Since:
MSM I01

getDisplayScreen

HScreen getDisplayScreen()
Obtain display screen with which this screen is associated.

Obtain the display HScreen associated with this HScreen. If this HScreen's type is SCREEN_TYPE_DISPLAY, then a reference to this HScreen SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is associated with a display HScreen, then that display HScreen SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is not associated with a display HScreen, then the value null SHALL be returned.

Returns:
A reference to a display HScreen instance or null. If null, then this HScreen is not associated with a display HScreen.
Since:
MSM I01

getDisplayArea

HScreenRectangle getDisplayArea()
Obtain area of the display screen to which this screen is mapped.

Obtain the area (extent) of this HScreen. If this HScreen's type is SCREEN_TYPE_DISPLAY, then an HScreenRectangle whose value is equal to HScreenRectangle(0,0,1,1) SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is associated with a display HScreen, then the area (extent) occupied by this logical HScreen on its associated display HScreen SHALL be returned. If this HScreen's type is SCREEN_TYPE_LOGICAL and this HScreen is not associated with a display HScreen, then the value null SHALL be returned.

Returns:
A reference to an HScreenRectangle instance or null. If null, then this HScreen is not associated with a display HScreen.
Since:
MSM I01

getServiceContexts

ServiceContext[] getServiceContexts()
Obtain service contexts associated with this screen.

Obtain the set of ServiceContexts associated with this HScreen to which the calling application is granted access.

Returns:
A reference to an array of ServiceContext instances. If the returned array is empty, then this HScreen is not associated with any accessible ServiceContext.
Since:
MSM I01

addScreenContextListener

void addScreenContextListener(MultiScreenContextListener listener)
Add screen context listener.

Add a listener to be notified upon the occurence of screen context events. If a listener has previously been added and not subsequently removed, then an attempt to add it again SHALL NOT produce a side effect.

Parameters:
listener - a MultiScreenContextListener instance.
Since:
MSM I01

removeScreenContextListener

void removeScreenContextListener(MultiScreenContextListener listener)
Remove screen context listener.

Remove a listener previously addede to be notified upon the occurence of screen context events. If the specified listener is not currently registered as a listener, then an attempt to remove it SHALL NOT produce a side effect.

Parameters:
listener - a MultiScreenContextListener instance.
Since:
MSM I01

addMultiScreenConfigurationListener

void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
                                         throws IllegalStateException
Add a listener to be notified upon the occurence of multiscreen configuration events that apply to this screen in the case it is a display screen. If a listener has previously been added and not subsequently removed, then an attempt to add it again SHALL NOT produce a side effect.

Configuration events that apply to a display screen SHALL be restricted to those that affect the complement of logical screens associated with the display screen.

If an event defined by MultiScreenConfigurationEvent is generated, then the MSM implementation SHALL notify each registered screen configuration listener accordingly.

Parameters:
listener - a MultiScreenConfigurationListener instance.
Throws:
IllegalStateException - if the type of this screen is not SCREEN_TYPE_DISPLAY.
Since:
MSM I01
See Also:
MultiScreenConfigurationEvent, MultiScreenConfigurationListener

removeMultiScreenConfigurationListener

void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
Remove a listener previously added to be notified upon the occurence of multiscreen configuration events. If the specified listener is not currently registered as a listener, then an attempt to remove it SHALL NOT produce a side effect.

Parameters:
listener - a MultiScreenConfigurationListener instance.
Since:
MSM I01
See Also:
MultiScreenConfigurationListener

getMultiScreenConfigurations

MultiScreenConfiguration[] getMultiScreenConfigurations()
                                                        throws SecurityException
Obtain set of all per-display multiscreen configurations currently associated with this display screen where the configuration type of any such multiscreen configuration SHALL NOT be SCREEN_CONFIGURATION_DISPLAY).

Returns:
A non-empty array of MultiScreenConfiguration instances.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

getMultiScreenConfigurations

MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType)
                                                        throws SecurityException,
                                                               IllegalArgumentException
Obtain per-display multiscreen configurations of a specific type associated with this display screen.

Parameters:
screenConfigurationType - (1) an element of the following enumeration of constants defined by MultiScreenConfiguration: { SCREEN_CONFIGURATION_NON_PIP, SCREEN_CONFIGURATION_PIP, SCREEN_CONFIGURATION_POP, SCREEN_CONFIGURATION_GENERAL }, or (2) some other platform-dependent value not pre-defined as a multiscreen configuration type.
Returns:
An array of MultiScreenConfiguration instances or null, depending on whether specified configuration type is supported or not.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
IllegalArgumentException - if screenConfigurationType is SCREEN_CONFIGURATION_DISPLAY, is not defined, or is otherwise unknown to the platform implemention.
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

getMultiScreenConfiguration

MultiScreenConfiguration getMultiScreenConfiguration()
                                                     throws IllegalStateException
Obtain the currently active per-display multiscreen configuration for this display screen.

Returns:
The currently active per-display MultiScreenConfiguration instance that applies to this display screen.
Throws:
IllegalStateException - if this HScreen is not a display screen.
Since:
MSM I01
See Also:
MultiScreenConfiguration