8.10 Integration of Graphics and Video

8.10.1 Configurations

The HAVi specification allows applications to express the relationship between video, graphics, and backgrounds. The method HScreen.getCoherentScreenConfigurations() allows applications to express a common set of constraints for video, graphics, and backgrounds and get back a coherent answer.

In addition to this, there are several means to express constraints between video and graphics. These can be used for applications that already have running video to fit a graphics configuration to that video or that have already running graphics to fit video to these graphics. In HGraphicsConfigTemplate , the constant VIDEO_MIXING allows applications to request configurations where graphics are superimposed above video but without any requirement for pixels to be aligned. In HScreenConfigTemplate , there are constants to allow applications to ask for configurations as follows :

VIDEO_GRAPHICS_REGISTERED : Video and graphics pixels are the same size and aligned.
ZERO_VIDEO_IMPACT : A new graphics configuration does not change the existing video. configuration.
ZERO_GRAPHICS_IMPACT : A new video configuration does not change the existing graphics configuration.

8.10.2 Coordinate Spaces

The HAVi specification includes a normalized screen coordinate system that represents the coordinates on the screen as floating point numbers between zero and one. This coordinate system is not pixel based. Such a non-pixel-based coordinate system enables the following:

Meaningful results, even when the graphics configuration has not been determined.
Meaningful results when presented video does not have a java.awt component.
Meaningful results when the video display and the graphics display are not necessarily aligned nor share the same origin nor share the same resolution, and so on.

This screen-based coordinate system is encapsulated in the HScreenRectangle and HScreenPoint classes. HAVi L2 GUI is silent about conversion between normalized and video coordinates. This should be addressed as part of the API providing support for control of video.

For graphics, these conversion mechanisms are found on the HGraphicsConfiguration class, since the conversion from screen to graphics coordinates is dependent on the current graphics device settings (Configuration), especially if the graphics resolution can be varied independently of the video resolution, etc.

The HScreenRectangle mechanisms can be used to enable the alignment of (portions of) video and (portions of) graphics. The HScreenLocationModifiedListener and HScreenLocationModifiedEvent allow mechanisms to determine if the on-screen location of an HVideoComponent is modified (rather than its relative location within its enclosing container).

8.10.3 Transparency

The HAVi specification includes support for applications to request transparency between graphics and video. This is provided by the getPunchThroughToBackgroundColor() method on the HGraphicsConfiguration class. These methods provide a factory that enables applications to provide an opaque RGB java.awt. Color or an RGBA JavaTV color supporting some form of transparency between graphics and video.

8.10.4 The Scene

The HAVi L2 GUI is deliberately agnostic concerning the implementation of a "coordinating" environment that provides the mechanism for a user to choose and run one or more applications. In HAVi, this coordinating environment is known as a home navigation shell . Application writers cannot make any assumptions that their application GUI is always immediately visible. For example, valid implementations of a coordinating environment might include the following:

A simple full-screen view on a single application at any one time (with some undefined mechanism to switch between them).
A multi-window system, where windows may obscure each other.
A paned system where each application occupies an area on-screen, (i.e., each) application is always visible, but it may be resized if other applications are installed.

Therefore, mechanisms are required to initiate an on-screen display and to indicate user-interest, or other modifications to the rendering area. These mechanisms should:

Enable an application to request an area on-screen. Given the possibility of differing styles of coordinating environment, an application cannot reasonably expect that its request is always honored perfectly , and thus, a mechanism is required to indicate preferences for the application location on-screen.
Indicate whether the current application is the one which the user is specifically interested in. For example, a well-behaved application which the user is not currently using might release, or reduce, its consumption of any limited resources.
Indicate to an application that its extent and position on-screen have been modified somehow by the home navigation shell.
Allow an application to indicate to the system that it requires the user's attention. For example, the system may either indicate to the user that he or she should choose the indicating application, or it might simply automatically switch to that application.

8.10.5 Requesting Screen Areas

The HSceneFactory is a factory class that is used to generate HScene objects. The application should call HSceneFactory.resizeScene() in order to re-size the HScene . This should be done by indicating the location and dimensions of the HScene in the associated HSceneTemplate , although it is not guaranteed that the resulting HScene matches all of these preferences, because such a matching is dependent on the implementation of the controlling shell and its associated policies, etc.

An HScene is an HContainer representing the displayable area on-screen within which the application can display itself and thus interact with the user. However, HScene does not paint itself onscreen, only its added child components and hence there is no requirement to allocate pixels to the HScene directly, because its only effect is to clip its child components. Hence, HScene may be regarded as a simple connection to the window management policy within the device, acting as a screen resource reservation mechanism denoting the area within which an application may wish to present a component, at some point in the future.

An HScene is by definition not painted , namely it is effectively transparent. Therefore, the area behind (all) HScene 's in the z-ordering may be exposed by the platform as an HBackgroundDevice or HVideoDevice . The HAVi specification does not require platforms to provide such device capabilities; this is platform specific. The HScene semantics for transparency need to be specified exactly on a per-platform basis; for example, on some platforms an HScene might be transparent to other HScene s due to other separate applications.

For all interoperable applications, the HScene is considered the main top-level component of the application. No parent component to an HScene should be accessible to applications. Interoperable applications should not use the getParent() method in HScene , because results are implementation dependent and valid implementations may generate a run-time error.

The behavior of HScene is similar to that of a java.awt.Window with a native peer implementation, in that it should not appear to delegate any functionality to any parent object. When created an HScene is not initially visible, and a call to setVisible() is required to display the HScene (and also to hide it). The HScene has a null LayoutManager by default. All widgets are placed using an x,y coordinate, specified by the widget. Components that do not specify default characteristics inherit default values transitively from their parent objects. Therefore, the implementation of HScene has valid defaults defined for all characteristics (e.g., Font, foreground color, background color, ColorModel , Cursor , and Locale) .

The application should call HSceneFactory.dispose() to destroy the HScene and all of its currently added components. This call has the effect of releasing their associated resources for future garbage collection by the platform. After calling this method, any further method calls on the HScene should result in a java.lang.IllegalStateException being thrown.

8.10.6 Scene Modification

The HScene object accepts java.awt.event.WindowEvent s, and interprets them as a java.awt.Window , however the home navigation shell is not required to generate all types of java.awt.event.WindowEvent . Still, the ComponentEvent s, COMPONENT_MOVED and COMPONENT_RESIZE, should be received by the HScene when the controlling shell has modified the position of the HScene or changed its dimensions on screen, respectively.

Applications can use the java.awt.Component.requestFocus() method on the HScene to indicate to the home navigation shell that the HScene should be receiving input focus. This request should be treated as a request to make the entire application visible and ready for user input, e.g., by expanding an icon, or changing the stacking order between competing overlapping applications. The decision whether or whenever the HScene (application) gains the input focus is entirely platform specific in terms of policy, and so on. The java.awt.Component is visible on the screen for this request to be granted. Visibility in this context refers to whether the application has called the HScene.setVisible() method, rather than any possible non- application-defined -behavior, due to the action of the coordinating shell hiding an application.

8.10.7 Scene Life Cycle

The application is acquired by the platform and validated , e.g., using authentication, byte-code verification, etc. If the JVM is not yet running, a JVM process is started. To execute the application, a new thread is created within the JVM process to serve as the execution context of that application and for which a ClassLoader is created. If the application does not require a GUI, then it may continue as per normal. If a user-interface and some screen resource is required, then the application traverses the HScreen , HGraphicsDevice , HGraphicsConfiguration space to determine an appropriate configuration, using HGraphicsConfigTemplate . For example, a template may specify a configuration of video-mixable full-screen graphics, with square pixel aspect ratio and a resolution of 1280 by 1024. Subsequently, the application configures the HGraphicsDevice appropriately, using the setGraphicsConfiguration() method. The application then requests that the HSceneFactory effectively grant it access to part of the screen for that device, using HSceneTemplate (e.g., full-screen display). As a response, the HSceneFactory returns an appropriate HScene container within which the application can display itself.

The application uses the HScene container to add all of its components to make its user-interface. The application may take advantage of java.awt.WindowEvent s, to determine whether it has the user's (input) focus. The application may take advantage of the events, COMPONENT_RESIZED and COMPONENT_MOVED, to determine when its HScene extent or location has been modified and to tailor its presentation accordingly . The application could resize the HScene by using HSceneFactory.resizeScene() , with the caveat that this may not be allowed by the external environment (e.g., due to window-manager policy).

Once the components are laid out, the application receives events and processes them as desired. Its behavior is similar to the behavior of an application running on a PC environment. Components are managed according to the model view controller paradigm. Event listeners are used to intercept user input.

Finally, the application terminates its on-screen presentation by calling the HScene.dispose() method. The application manager then terminates the thread providing the execution context of that application.

8.10.8 Scene Factory

HScenes is created using the HSceneFactory , which provides a generic mechanism for an application to request HScene resources from a (conceptual) window management system. The HSceneFactory class provides an opaque interface between any application (or window) management scheme and the Java application itself. It is the single entry to potentially multiple HGraphicsDevice centric window management policies. Only one HScene per HGraphicsDevice can be acquired at any one time for each application.

HScene s follow the design pattern of the java.awt.Window class. They are not a scarce resource on the platform. On platforms that only support one HScene being visible at one time the current HScene both loses the input focus and is hidden (e.g., iconified ) when another application successfully requests the input focus. Two java.awt.event.WindowEvent events, with IDs, WINDOW_DEACTIVATED and WINDOW_ICONIFIED, are generated and sent to the HScene that has lost the focus and the isShowing() method for that HScene returns false. The constraints on the sizing and positioning of the HScene returned by the methods are dependent on the platform-specific HScene support.

8.10.8.1 Platforms Supporting a Full Multiwindow System

Platforms where windows may obscure each other allow applications to create HScene objects that are fully within the area of the supporting HGraphicsDevice without any restriction on size or location. Whether successful creation of HScene s that are wholly or partially outside the area of the HGraphicsDevice is supported is implementation dependent.

8.10.8.2 Platforms Supporting a Single Window System

Platforms supporting a simple "full-screen" view on a single application at any one time are required to allow applications to create HScene s that cover the full area of the supporting HGraphicsDevice . HScene s matching this description are returned as the default HScene for the supporting HGraphicsDevice . It is implementation dependent whether requests to create HScene objects that cover less than the full area of the supporting HGraphicsDevice succeed, and if they succeed, what the consequences are of their being displayed.

8.10.8.3 Platforms Supporting a Restricted Multi-Window System

Platforms supporting a paned system where each application occupies an area on-screen that is always visible make fewer guarantees to applications. When an HScene is created on such a system, the platform returns an HScene that, if visible at that time, would cover as much as possible of the requested area of the supporting HGraphicsDevice considering all other visible HScene s at that time. HScene s that are not visible at this time is not considered when fixing the location and size of the new HScene . HScene s that are visible at this time is not effected by the creation of the new HScene .

When setVisible(true) is called on such an HScene , the platform attempts to make the HScene visible using its currently set position and size. If this would conflict with HScene that are already visible then the call to setVisible() fails silently. Applications are responsible for testing for failure using the isVisible() method. The HScene s of already visible applications are not impacted by this method call.

8.10.8.4 Scenes Embedded Within Markup Pages

Typically, a Web browser controls the bounds of all areas it renders . Therefore, HScene s embedded within markup pages are not expected to be able to control their location nor their size. Otherwise, such HScene comply with the above descriptions for the other cases.

8.10.9 Scene Hierarchy

The scene hierarchy is similar to traditional GUI hierarchy. The top of this hierarchy is a root container. That container is associated with a layout manager. The addition of a component is done in concert with the options that the selected layout manager supports.

As an example, consider the dialog box presented in Figures 8.8 and 8.9. The top level, or root container, (the component labeled as 1), is organized using a border layout. It contains two components, the tabs container 2, placed at the center of the border layout, and the buttons container 3, placed at the south of the border layout. The buttons container, 3, is organized using a grid layout with a single row and two columns . At location 0,0 an Ok button 4 is placed, and at location 0,1 a Cancel button is placed. The tabs container 2 is organized using a tabs layout, not supported in standard HAVi, whose implementation requires some proprietary extensions. The tabs are the containers labeled 6 and 7. The Card-Info tab 6 is organized using a grid layout, in three rows and a single column. The top row, 8, contains two components: A label 11 and a single line entry field 12. The second row contains a single label 9. The third row contains the date editor container, organized using a grid layout with two rows and three columns. At location 0,0 is the label month and at location 1,0 is the list box that enables selection. At location 0,1 is the day label and at location 1,1 is the list box that enables selection. Finally, at location 0,2 is the label year , and at location 1,2 is the list box that enables selection.

Figure 8.8. An example HScene component hierarchy.

Figure 8.9. An example HScene component hierarchy.

Figure 8.10 further illustrates the relationship between a container (e.g., the HScene ), its layout, and the components it contains. At first, the HScene is constructed and its layout is set using the HScene.setLayout() method. Next, the components are added; in this example, HComponent 1, HComponent 2 are added. Next, if one of these component needs to contain other components, its layout manager needs to be set using the setLayout() method. Next, child components are added; in this example, HComponent 3, HComponent 4 are added. Once all components are added, the layout managers are invoked. This results in them invoking the setBounds() method for each component within a container; in this example, for HScene the bounds of HComponent 1 and HComponent 2 are set, and subsequently, for HComponent1 the bounds of HComponent 3 and HComponent 4 are set.