MWsScene is a CWsRenderStage interface extension. An understanding of the Render Stage Plug-in architecture, and the CWsRenderStage API is required in order to use and understand this interface.

A MWsScene manages a collection of MWsElements that define what is shown to a User on a particular target display, or off-screen buffer.

A MWsScene constitute of MWsElements. Each MWsElement represents a rectangular region of the screen. MWsElements have meta-data which describe the region, such as the image orientation, extent, and alpha-blending characteristics. MWsElements also have surface-data, which provides the pixel data to be shown in the given area of the screen.

The purpose of an MWsScene is to manage the relative ordinal positions of scene elements. Typically elements representing the camera view- finder, or video frames, is placed at the bottom, and the user interface element is placed above. Semi-transparency is often used to blend such elements into a visually appealing scene, and transparent holes in the user interface element allow elements below to poke through.

The goal of this interface is to allow suitable platforms to implement this API using composition hardware. This is to reduce power and CPU load, so a long movie might be played, for example.

A secondary goal of this interface is to enable transition effects to be efficiently implemented. This is because MWsScenes can be chained together in a Render Stage pipeline. Element meta-data can be manipulated by transition effects render stages before actual rendering.

Examples of Elements

Indirect rendering is the normal case. Here the client provides CWindowGc commands, which Window Server passes as MWsGraphicsContext API calls to the Render Stage.

Direct rendering is where Window Server does not see the graphics commands, as is the case for Direct Screen Access clients.

Use Cases

Instantiation

During system-startup Window Server needs to obtain an instance of the MWsScene interface in order to place MWsElements in the scene for rendering.

 CWsRenderStage::ResolveObjectInterface(KMWsScene);

Rendering

When the Scene changes, Window Server needs to communicate the changes and then render the new Scene. This can happen when a video player application is launched, whereby a new User Interface control is placed on the screen, and a new Element representing the Video Surface is added.

 CWsRenderStage::Begin(regionOfScreenWithVideoPlayer);
 drawing ops sent to MWsGraphicsContext for UI
 drawing ops to setup a transparent hole for video surface to poke
 through
 .
 .
 
 sceneElement = CreateSceneElementL();
 sceneElement->ConnectSurface(videoSurfaceAlreadySetup);
 InsertSceneElement(sceneElement, NULL);
 CWsRenderStage::End(asyncCallbackNotification);

When Scene updates, such as in the example above, are done there is a concept of the "Committed Scene". All Scene updates are considered to be "Pending" until a CWsRenderStage::End() has been called. Then the pending changes are applied atomically. Either the previously Committed Scene is re-instated or all the Pending changes are accepted to form the newly Committed Scene. This depends on platform-specific limitations, and system-wide resource availability.

Orientation Changes to Elements

Suppose we have an MWsElement representing people as seen through a video camera view finder in landscape orientation, with the handset also in landscape orientation. The handset is rotated into portrait mode.

We desire the view finder to be rotated in the opposite sense to the rest of the User Interface. This is to allow people previously vertical in the view finder to remain vertical.

For this use case, a MWsElement::SetSourceRotation() must be called.

The changes are visible after the next CWsRenderStage::End() call.

Orientation Changes to Scenes

Suppose the entire Scene comprises a single User Interface element. The handset is then rotated from landscape to portrait mode. The whole scene must be rotated to compensate. Here MWsScene::SetSceneRotation() must be called.

The changes are visible after the next CWsRenderStage::End() call.

Leveraging external APIs for Transition Effects

Suppose we want to manipulate the Scene to achieve a transition effect. The Scene as presented by Window Server comprises one UI Element, and one External Surface Element. We have an external APIs, such as OpenGL or OpenWF, available to deliver a transition effect into a different External Surface.

This task is accomplished by using the output Surface of OpenGL as the connected Image Source for the one Element which comprises the Scene presented on the Screen. The Elements inserted into the Scene by Window Server are instead given to OpenGL as textures. When the Screen needs to be rendered, OpenGL is first used to render to its output Surface, and this is taken as-is for the Scene Element that appears on the Screen.

A combination of Rendering APIs may be employed if they are available to the Transition Effects Render Stage -- to combine the power of OpenVG, OpenGL, and OpenWF, as an example.

Managing the life-cycle of Surfaces from Window Server

Suppose we want to maintain the life-cycle of a given Surface outside that needed by the Scene. For example, suppose we have a video player application whose picture is frozen to a particular frame. Then the application switches to some other view, no longer showing the video frame. Finally, the application switches back to the original video frame so that the video clip can be resumed.

In such a scenario, we would want the contents of the Surface to remain constant event though at one point the Surface is not part of the Scene. This is so that the user does not see anything inconsistent appear with the video frame between switching from and to the video frame.

Another scenario where the Surface needs to have a life-cycle beyond that of the Scene is when there is a large start-up cost to populating the Surface with initial data. For example, a computer game application might take some seconds to construct the textures for an initial game position. The game would want to construct the Surface, and populate its contents before supplying the Surface as a Background Surface for a given window. This is so that the user does not see the game building up the Surface contents during game start-up.

To facilitate the above use case, a call to RegisterSurface and a corresponding call to UnregisterSurface must be made. Note, Window Server should provide an UnregisterSurface call if the client program dies or exits abruptly before it could call UnregisterSurface.