<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87" xml:lang="en"><title>Render

Stages Overview</title><shortdesc>Render stages are ROM-based plug-ins to the Window Server render

stage framework. They can be chained to form a rendering pipeline, which takes

the draw operations that are produced by the Window Server and ultimately

passes them to the UI surface. Render stages can selectively filter, modify,

or redirect the draw operation stream, as required—for example, to perform

transition effects (TFX). </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target

audience</b>: Device creators. </p>

<p>Render stages therefore provide a mechanism for device creators to customize

the Window Server rendering pipeline without modifying the Window Server code.

In addition, in ScreenPlay the render stages are able to monitor and modify

display control attributes, and scale and position the application extent

within the full UI area. </p>

<p>Instead of using a concrete rendering API, the Window Server uses abstract

APIs, for which the render stage plug-ins provide the concrete implementations. </p>

<section id="GUID-B431C15F-B567-5A6F-8E3F-1A45CE2FACDE"><title>Architecture</title> <p>The

following diagram shows where render stages fit into the Window Server architecture. </p> <fig id="GUID-B1321BD9-2EF4-5BB3-8226-880C460526C1">

<title>              Window Server architecture showing render stages    

       </title>

<image href="GUID-25A63716-D637-589D-BAB7-B962455F2DC6_d0e218778_href.png" placement="inline"/>

</fig> <p>Symbian provides default render stage plug-ins, which are of production

quality and reproduce the rendering behavior in Symbian OS v9.4. In ScreenPlay,

device creators can replace the render stage plug-ins with their own bespoke

plug-ins. In the non-ScreenPlay variant, the interfaces are prototypes and

the render stage plug-ins should not be replaced in a real device. Note that

different APIs are used in ScreenPlay from the non-ScreenPlay variant. This

section documents the ScreenPlay APIs. </p> </section>

<section id="GUID-E225354D-1EFC-513E-843E-42528C3FCCCF"><title>Typical use

case</title> <p>The primary use case is that a device creator adds a render

stage plug-in into the render stage chain in order to create transition effects

(TFX). For example, the device creator could add a TFX engine render stage

as shown in the following diagram. This could be used to slide in menus and

other elements of the user interface. </p> <p>The TFX render stage might redirect

relevant draw operations onto a TFX surface. Then later the TFX render stage

could inject those captured drawing operations into the displayed scene over

a sequence of frames, in order to create the desired effect. </p> <fig id="GUID-75F4A91E-D764-5BF4-8B21-74689EB43E7A">

<title>              A typical render stage configuration, showing some of

the key              interfaces            </title>

<image href="GUID-0F2AE495-F6D8-5351-BD83-76D579564C2E_d0e218800_href.png" placement="inline"/>

</fig> <p>The render stages are stacked on top of each other—effectively they

are chained into a pipeline, in which the Window Server "talks" only to the

first render stage. This render stage in turn talks only to the second render

stage. Notice that the second render stage uses a concrete rendering API to

control the UI surface. This is in contrast to the first render stage, which

uses the abstract <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> API, which acts as

a proxy for the concrete API. </p> <p>Let us look at how it works in sequence.

Redraw stores hold GDI draw operations and then play them back. The abstract

interface for GDI draw operations is <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> and

the redraw stores pass the draw operations on to the first render stage in

the chain using <xref href="GUID-44844998-D8BF-3F2F-9BA2-FB9BB497F8C0.dita"><apiname>MWsGraphicsContext</apiname></xref> calls. The first render

stage in the chain processes these and passes a possibly modified stream of

GDI operations on to the second render stage (which is the final render stage

in this example). This final render stage converts the GDI operations into

concrete rendering calls (such as BitGDI or OpenVG) for rendering into the

UI surface. However, alternatives are possible. For example, redraw stores

can also include <codeph>DrawWsGraphic()</codeph> calls, which when played

back result in the execution of Content Rendering Plug-ins (CRPs). </p> <p>Window

Server clients can introduce <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">external

surfaces</xref> into the scene using <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-4EBFFA14-418A-3A2A-B147-39BFC96CE45F"><apiname>RWindowBase::SetBackgroundSurface()</apiname></xref>.

These are tracked through the window tree using the abstract interface for

the composition context. The final render stage converts these abstract interface

calls into calls to the <xref href="GUID-63CB6C7E-44EC-5D0B-A37D-FE78F7D76592.dita">composition

interface</xref>. </p> <p>Note that render stage chains are on a per-screen

basis. If there are multiple screens, there are multiple render stage chains.

The chains can use the same render stage classes, but they use different object

instances of those classes. </p> </section>

<section><title>Implementing the interfaces</title> <p>After it constructs

the render stage chain, the Window Server requests various interfaces from

the top render stage using the Window Server's object provider mechanism.

Some of the interfaces are mandatory, some are optional. </p> <p>Usually each

render stage in the chain implements the interfaces and passes the calls through

to the next render stage. For example, a TFX render stage might redirect some

GDI draw operations and play them back later, so that what passes in at the

top is not the same as what passes out at the bottom. In this case, the render

stage provides its own implementation of the interface, although that implementation

generally calls the implementation provided by the next stage. </p> <p>However,

sometimes a render stage does not need to make any modification to what passes

through the interface. Then the render stage does not provide an implementation—it

simply passes the draw operations through to the next render stage. For example,

generally only the final render stage needs to implement the <xref href="GUID-B1E048A2-D5E8-3E7F-A6AC-6B8F3ED3067C.dita"><apiname>MWsScreenDevice</apiname></xref> interface,

which provides information about the screen size and orientation. </p> <p>The

following diagram shows a concrete render stage implementing three of the

main <xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita">render stage interfaces</xref>.

Although this is the usual practice, it is not mandatory. The concrete render

stage could instead delegate the implementation of some of the interfaces

to helper classes. </p> <fig id="GUID-84104CD3-C78C-50C7-9155-50596B3EE3EF">

<title>              A concrete render stage class implementing key render

stage              interfaces            </title>

<image href="GUID-973CF8E7-18C8-5E24-BC7A-97148FAEF3E4_d0e218869_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-5D81D1A7-26A0-5461-9AC5-3EF359D283CB"><title>Advanced use

case</title> <p>Render stages can optionally create their own <b>visuals tree</b> to

mirror the structure of the Window Server's window tree. The render stage

can then temporarily change the attributes of nodes in the tree and introduce

new nodes that the Window Server does not know about. This enables the render

stage chain to introduce sophisticated transition effects. </p> <p>To create

a visuals tree, the render stage must implement the <xref href="GUID-028CC583-AC32-3D60-943A-A80F84E05DD2.dita"><apiname>MWsWindowTreeObserver</apiname></xref> interface.

The Window Server uses this to communicate the structure of the window tree

to the render stage, so that the render stage can build up its replica tree. </p> <p>Similarly

render stages can optionally capture the drawing for each window from the

Window Server redraw stores and build up their own <b>visuals stores</b> to

store the drawing for the nodes in the visuals tree. To do this, the render

stage must implement the <xref href="GUID-21240143-D578-3114-9836-F765F70A987C.dita"><apiname>MWsDrawAnnotationObserver</apiname></xref>. The

Window Server uses this to communicate which node in the tree each batch of

drawing operations relates to. </p> <fig id="GUID-97D46D41-589A-504D-B7C0-9092E6E5DF17">

<title>              Render stage that has a visuals tree and visual stores

           </title>

<image href="GUID-3248A2B1-54D0-56E3-B770-DC595B01EA04_d0e218905_href.png" placement="inline"/>

</fig> <p>Render stages that implement their own visuals stores typically

use the Window Server's <b>change-tracking</b> rendering mode. This is an

optimization of the <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window

Server rendering loop</xref> for render stages that build visuals stores.

The render stage is then responsible for playing back the drawing operations

in the visuals store whenever the screen is to be updated. Typically this

is done using a painter's-style algorithm. </p> <p>By implementing a visuals

tree and visuals stores, render stages can perform more complex TFX than is

possible otherwise. However, implementing a visuals tree and visuals stores

is not necessary for some TFX, such as sliding windows onto the screen. </p> <p> <i>Note</i>:

The painter's algorithm (sometimes called priority fill) is a common solution

in 3D computer graphics. The algorithm mimics the painting technique of painting

the distant parts of a scene before parts that are in the foreground, even

though this may result in covering up some of the distant areas. The algorithm

sorts the polygons in a scene by their depth and then draws them in order

from the back to the front. </p> </section>

<section><title>Configuring the render stage chain</title> <p>Parameters in

the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> control

the configuration of the render stages as follows: </p> <ul>

<li id="GUID-D7209CD8-A745-557E-B472-ECB188EF4A09"><p>The <codeph>PLUGINS</codeph> parameter

controls which render stages are loaded when the Window Server starts up.

In addition, a separate section specifies details (such as ID and type) for

each plug-in. </p> </li>

<li id="GUID-3F59881C-911B-5CD0-9704-78773F7B639B"><p>The <codeph>RENDERSTAGES</codeph> parameter

configures the render stage chain and the <codeph>CHANGETRACKING</codeph> parameter

selects change-tracking rendering mode (instead of the default dirty-rectangle

tracking mode). You can specify these separately for each screen, so that

different effects can be used for each screen. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext>

</link>

<link href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita"><linktext>Creating

a Render Stage Plug-in</linktext></link>

<link href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita"><linktext>Window Server

Rendering Loop</linktext></link>

</related-links></concept>