Render Stage Interfaces

MWsObjectProvider

MWsObjectProvider is a Window Server plug-in framework interface, which provides a mechanism through which classes can offer extension interfaces. Render stages and most of the related classes implement this interface.

CWsRenderStage

CWsRenderStage is an abstract class that all render stages must derive from. It has two pure virtual functions: Begin() and End(), which must be implemented in the concrete class.

The Window Server's output to the render stage pipeline is not a continuous stream, but instead consists of batches of drawing operations. When client drawing or server-side animations require a screen update, the Window Server rendering loop schedules a redraw. When this redraw occurs, a batch of drawing operations is produced to perform the updates.

The Window Server calls CWsRenderStage::Begin() at the beginning of a batch of draw operations. This gives the render stages an opportunity to perform any preparation. Similarly the Window Server calls CWsRenderStage::End() at the end of the batch, which provides the render stages with the opportunity to perform any tidying up.

For example, a flicker buffer render stage might use the Begin() call as a signal to clear its off-screen buffer, and the End() call as a signal to perform the blit of the accumulated updates to the next render stage. The final render stage might use the End() call as the signal to submit a surface update to the composition engine.

Render stages perform all rendering operations between the Begin() and End() calls. The Window Server calls the MWsGraphicsContext functions only between the Begin() and End() calls. The render stage could ASSERT that these functions are not called at other times and ignore them if they are or take some other action as appropriate. However, render stages can safely call composition context functions outside the Begin() and End() calls. In addition, the MWsScreenDevice functions may be called at any time.

MWsGraphicsContext

MWsGraphicsContext is the interface for GDI-like drawing. The Window Server requests this interface from the first render stage in the chain using the object provider mechanism. This is a mandatory interface, which means that a render stage must not return null when it receives an object provider request for this interface. However, providing an implementation is not mandatory. For example, a logging render stage might simply delegate to the next render stage instead of returning its own implementation of this interface.

The member functions correspond to functions in CFbsBitGc (such as DrawText() and BitBlt()) but without functions that are not suitable for hardware acceleration (such as read-modify-write functions like SetFaded()).

The final render stage in the chain typically provides an implementation of MWsGraphicsContext in terms of a concrete rendering context—for example, by translating into BitGDI or OpenVG calls.

If extended bitmaps are supported on the device, the implementation of the functions that receive a CFbsBitmap as an argument can check whether it is the handle to an extended bitmap. If it is, the render stage can process the proprietary data within the bitmap. You can get access to the proprietary data by using CFbsBitmap::DataAddress(). Here is a simple example:

// bmp points to a bitmap to be drawn.
TUid type = bmp->ExtendedBitmapType();
    
if (type==KUidMyProprietaryFormat)
    {    
    bmp->BeginDataAccess();
    const TUint32* data = bmp->DataAddress();
    TInt dataSize = bmp->DataSize();
    ProcessMyData(data, dataSize);
    bmp->EndDataAccess(ETrue);
    }

For some data formats, particularly those that contain vector data, such as SVG, this approach has advantages compared to letting the extended bitmap rasterizer DLL process the proprietary data. For example, the extended bitmap rasterizer DLL rasterizes the proprietary data into a pixel buffer, which is then blitted to the screen. In contrast the render stage can insert the drawing commands directly into the drawing command stream without the use of intermediate pixel buffers. In addition, unlike the extended bitmap rasterizer DLL, the render stage does not need to rasterize the image to a higher resolution in order to scale it down. The use of the render stage to process the proprietary data can therefore potentially save memory and improve performance, depending on the data format.

Although the Symbian Foundation does not currently provide extended bitmap functionality in the main render stages, it does provide a test extended bitmap render stage. You can use this as an example when you implement your own extended bitmap functionality.

For more information, see Extended Bitmaps.

MWsScene

MWsScene is the composition context interface for use with OpenWF composition. It is a mandatory interface. However, like MWsGraphicsContext, some render stages might simply delegate to the next render stage rather than providing their own implementations. The final render stage in the chain typically provides an implementation of MWsScene in terms of OpenWF-C.

The MWsScene interface defines the composition context for a particular screen (or an off-screen buffer representing the screen) in terms of a collection of rectangular regions. These are called scene elements or simply elements. Each one is represented by the MWsElement interface. The MWsScene interface manages the relative ordinal positions of the elements and uses the elements to track external surfaces and their place in the composition scene. Render stages can manipulate element metadata in order to perform transition effects and use the hardware-accelerated composition facilities provided by OpenWF-C to perform transition effects (such as slide, zoom and fade).

Some of the key functions are:

• CreateSceneElementL(). Creates a new element for use in the scene. After creation, an element is available to the caller but InsertSceneElement() must be called to actually insert it into the pending scene.

• InsertSceneElement(). Inserts an element into the scene.

• RemoveSceneElement(). Removes an element from the scene.

• DestroySceneElement(). Destroys an element and removes its resources from the scene.

• ComposePendingScene(). Renders the pending scene to an off-screen target.

• RegisterSurface(). Marks a surface as potentially in use beyond its lifetime within the scene. There are two typical use cases—one is where the contents of the surface (for example, a video frame) must be maintained when users switch to another application that hides the surface so that it is no longer part of the scene. This means that users can have a seamless experience when they switch back to the video. The other use case is where the content of a surface needs to be populated before it is attached to a window and therefore added to the scene.

• UnregisterSurface(). Marks the surface as no longer in use beyond its inclusion in the scene.

Any updates to the scene introduced by the render stage (such as adding a new element) are pending until the Window Server calls CWsRenderStage::End() to commit the scene.

MWsElement

MWsElement is a mandatory interface for managing scene elements when OpenWF composition is in use. This interface is obtained by using MWsScene::CreateSceneElementL() rather than the object provider mechanism.

The MWsElement interface provides a way of associating metadata with an image source. From the render stage's point of view, the image source is a surface that is connected to the element—whereas OpenWF-C has the concept of image sources that are created from native streams. Because the OpenWF-C Support component implements native streams in terms of Symbian surfaces, the render stage can ignore this distinction and simply cast the address of the TSurfaceId to the OpenWF-C native stream type (WFCNativeStreamType).

The element metadata includes the following:

• Source rectangle—the region within the surface from which pixels are taken. This enables the surface to be cropped and is equivalent to the surface viewport described in External Surfaces Overview.

• Destination rectangle—the target rectangle in the composition output to which the pixels are rendered. This is equivalent to the extent.

• Global alpha—a global alpha value for use in blending the surface into the composition output.

• Source rotation—the number of quadrant angles by which the contents of the surface are rotated.

• Source flipping—a Boolean value that indicates whether the contents of the surface are flipped.

• Target renderer flags—these provide information to the rendering subsystem (for example, the OpenWF-C engine), such as whether the renderer should blend based on the global alpha value or the alpha channel in the surface itself.

• Render stage flags—these provide information to the render stages, such as whether the UI surface is always on top.

MWsScreenDevice

MWsScreenDevice is the interface for managing the screen. It provides functions for controlling rotation and fetching data from the screen such as a screen snapshot.

MWsTextCursor

MWsTextCursor is an interface that enables render stages to implement a text cursor to represent the flashing bar or rectangle that represents the current position when editing text.

Prior to the introduction of ScreenPlay text cursors were drawn using XOR drawing because it provides high contrast against the background. Render stages can implement this interface using the same approach but it is generally inefficient on hardware-accelerated platforms. Therefore another approach, such as a drop shadow or sprite, might be preferable.

The preferred solution is that clients use RWsSession::SetCustomTextCursor() to replace the text cursor with a sprite. This means that user themes can use a sprite that matches the text—for example, a white sprite with white text and a black sprite with black text. If a client does this, the render stage’s MWsTextCursor API is not used when drawing text cursors for that client. Instead, the text cursor sprite is drawn using GDI draw operations through the MWsGraphicsContext interface.

MWsFader

MWsFader is the interface for providing fading capabilities.

MWsWindowTreeObserver

MWsWindowTreeObserver is an optional interface that enables a render stage to create a replica of the window tree, known as the visuals tree. The Window Server uses this interface to tell the render stage about the window tree structure and changes to window tree nodes. Note that this interface considers animations and sprites to be nodes in the window tree.

See the Advanced Use Case section of the Render Stages Overview for more information.

MWsDrawAnnotationObserver

MWsDrawAnnotationObserver is an optional interface that enables render stages to associate a batch of drawing operations with a specific window or node in the visuals tree. TFX render stages generally need to implement this interface.

If the render stage implements the MWsWindowTreeObserver interface, implementing the MWsDrawAnnotationObserver interface enables the render stage to know which node in the visuals tree each batch of drawing operations belongs to. This means that the render stage can associate the batch with the correct window, sprite or other element in the visuals tree and manage it efficiently.

If the render stage does not implement the MWsWindowTreeObserver interface, the MWsDrawAnnotationObserver interface still provides the window tree node pointers for each batch of drawing operations. There are two different approaches this type of render stage can take:

• The render stage can treat the window tree node pointers as unique identifiers for the windows. This approach is typically used when the Window Server's default dirty-rectangle rendering mode is in use. In this mode the Window Server sends the batches of drawing operations to the first render stage in back to front z-order. (That is, the drawing operations for the windows in the background come before the drawing operations for the windows at the front.) Using the unique identifier and the z-order, the render stage can identify new windows that are at the top and slide them on or perform some other transition effect.

  This approach is suitable when the render stage always performs the same transition effect. For example, the render stage slides on all new windows that are at the front.

• The other approach is suitable when the render stage applies transition effects to specific windows; for example, windows that belong to a media player application. In this scenario, the client communicates the handles of those windows to the render stage. The render stage uses the MWsDrawAnnotationObserver to retrieve the handles of the windows to which the drawing operations relate. The render stage compares these handles with those communicated by the client and for which the transition effects are required. When a handle matches, the render stage performs the transition effect. When the handle does not match, the render stage passes the drawing operations straight through to the next render stage in the chain.

  The following code snippet shows how to retrieve a window's handle from the MWsWindowTreeNode object returned by the MWsDrawAnnotationObserver functions:

  windowID = aWindowTreeNode.Window->Handle();

  Note: Communication of the window handle from the client to the render stage is beyond the scope of this documentation.

MWsWindowVisibilityNotifier

MWsWindowVisibilityNotifier is an optional interface that enables a render stage to communicate changes in the visibility of windows and other nodes in the window tree to the Window Server. A render stage that works in change-tracking rendering mode must implement this interface.

When the Window Server is in its default dirty-rectangle tracking mode, it tracks which windows are visible and sends visibility-changed events to clients, Content Rendering Plug-ins (CRPs) and animation plug-ins. This enables these clients to know when their windows are visible and therefore need to draw or animate, and when they are obscured and do not need to draw or animate. This means that CPU cycles are not wasted producing animations when they are not visible and ensures that animations run when they are visible.

When the Window Server is in change-tracking mode, it does not track the visible regions and tracking of visible regions is delegated to the render stage. At the minimum, the render stage must set the visible region to be the whole window or none of it.

The Window Server implements the MWsWindowVisibilityObserver interface through which it responds to visibility change notifications sent by the render stage.

MWsDisplayControl

MWsDisplayControl is the interface for controlling the display configuration. See Render Stage Display Control and Mapping for more information.

MWsDisplayMapping

MWsDisplayMapping is the interface for mapping between coordinate spaces. See Render Stage Display Control and Mapping for more information.

MWsDisplayPolicy

MWsDisplayPolicy is an optional interface, which if implemented, determines the UI to composition mapping policy. See Render Stage Display Control and Mapping for more information.