<?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-22093E74-EFE7-5642-93DE-1573E18F7C08" xml:lang="en"><title>The

Window Server Rendering Loop</title><shortdesc>This topic provides a brief introduction to the Window Server's

rendering loop, which takes place in two stages, known as the upper loop and

the lower loop. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> and <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref>. <b>Target

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

<p>The following diagram provides a simplified representation of the upper

and lower loops. </p>

<fig id="GUID-9CC782B3-568B-56A4-9AF7-0E2D4EABD7A7">

<title>The Window Server's upper and lower rendering loops</title>

</fig>

<p> </p>

<p>The <b>upper loop</b> is the process by which the Window Server’s scene

state information is updated based on commands from the client. There are

two types of scene state updates: window tree updates (such as when a window

is moved) and redraw store updates (such as when new drawing operations are

sent for a particular window). </p>

<p>The <b>lower loop</b> is the process by which updates are made to what

the user sees on the screen. The lower loop runs after the upper loop. </p>

<p>The two most important APIs on the client side are: </p>

<ul>

<li id="GUID-441D76AB-340A-52E4-ABDE-8093C511694D"><p> <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>,

which is the class through which a client controls a window. Its main functions

enable a client to create and destroy windows, move and resize them, make

them visible or invisible, and send them to the foreground or background. </p> </li>

<li id="GUID-F0F159ED-73A2-57A3-9077-8B56E756A53B"><p> <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>,

which is the class through which a client issues draw operations. At any given

time, a <codeph>CWindowGc</codeph> is activated on a particular window. The <codeph>CWindowGc</codeph> functions

that are used most frequently are <codeph>DrawBitmap()</codeph> and <codeph>BitBlt()</codeph>,

for drawing a skin bitmap as a background, and <codeph>DrawText()</codeph>. </p> </li>

</ul>

<fig id="GUID-7103B894-51DE-5051-899F-F1FF2BD0749E">

<title>The main participants in the ScreenPlay Window Server rendering loop</title>

</fig>

<p>On the client side, <codeph>RWindow</codeph> and <codeph>CWindowGc</codeph> commands

are converted to opcodes that are stored in a command buffer. When the command

buffer is full, it is automatically <b>flushed</b>, which means that it is

transferred across to a corresponding server-side command buffer. The client

can also explicitly request a flush using <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B83C6F44-1A3E-3959-910C-CBBF66C4A3D4"><apiname>RWsSession::Flush()</apiname></xref>. </p>

<p>On the server side: </p>

<ul>

<li id="GUID-8553F184-A167-5285-91F5-203A8B0D707A"><p>The upper loop processes

the server-side command buffers. <codeph>RWindow</codeph> commands are processed

as updates to the <b>window tree</b>. <codeph>CWindowGc</codeph> commands

are processed as updates to the <b>redraw stores</b>. </p> </li>

<li id="GUID-894B970D-E8F4-52D4-996C-D72378C48EEF"><p>The lower loop ultimately

causes the updates to be drawn to the UI surface. However, the updates do

not go straight to the UI surface. Instead they go through an additional level

of indirection called <b>render stages</b>. These are replaceable plug-ins

to the Window Server, which enable the customization of the final stages of

the rendering pipeline. </p> </li>

</ul>

<p>The details of the upper and lower loops vary depending on whether dirty-rectangle

tracking or change tracking is in use. </p>

<p><b>Dirty-rectangle tracking mode </b> </p>

<p>Dirty-rectangle tracking mode is always used in the non-ScreenPlay variant

and is the default mode in ScreenPlay. </p>

<p>Updates to both the window tree and the redraw stores typically mean that

the current contents of the screen become invalid. Therefore, when processing <codeph>RWindow</codeph> or <codeph>CWindowGc</codeph> commands,

the upper loop adds the affected regions to a list of dirty rectangles that

need to be redrawn. The list includes transparent windows that are on top

of other windows and excludes windows that are obscured. The upper loop then

starts a scheduler, which eventually causes the dirty rectangles to be redrawn. </p>

<p>Some time later the scheduler runs the lower loop. The task of the lower

loop is to clean any dirty rectangles by playing (or replaying) the drawing

operations from the redraw stores into the first render stage. This is done

for all of the visible windows, starting at the back and working forwards. </p>

<p><b>Change tracking mode </b> </p>

<p>Change tracking mode is only available in ScreenPlay. To enable change

tracking mode, add the <codeph>CHANGETRACKING</codeph> parameter to the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. This

parameter is set on a per-screen basis. </p>

<p>In change tracking mode, the upper loop keeps a list of all of the windows

for which there are new or changed drawing operations, regardless whether

the window is obscured or not. The list does not include transparent windows

that have not changed and which are on top of other windows. As in dirty-rectangle

tracking mode, changes cause the upper loop to start the scheduler which eventually

causes the lower loop to run. This plays the drawing operations for all of

the windows in the list of changed windows into the first render stage. </p>

<p>Typically you enable change tracking mode only if you are creating a transition

effects (TFX) render stage that is building up its own visuals stores. Visual

stores are replicas of the redraw stores and are often used with a visuals

tree. A visuals tree is a replica of the Window Server's window tree, into

which the render stage may add nodes that the Window Server does not "know"

about. In addition, these render stages typically introduce transition effects

which may change the visibility of windows that the Window Server does know

about. For example, the following diagram shows a transition effect in which

a window slides onto the screen from the top and temporarily obscures an existing

window on the screen. </p>

<fig id="GUID-761A5E99-D289-5F58-9747-BBECF0BFB2F2">

<title> A transition effect temporarily obscures a window on the screen</title>

</fig>

<p>In this and similar scenarios, the Window Server does not know whether

a window is obscured or visible. Therefore dirty-rectangle tracking is not

effective. </p>

<p>Each screen on the device has a separate render stage chain.

Because you set the <codeph>CHANGETRACKING</codeph> parameter on a per-screen

basis, it is possible to have a sophisticated TFX on one screen and a simple

display render stage on another screen. </p>

</conbody><related-links>

<link href="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita"><linktext>Redraw Stores</linktext>

</link>

<link href="GUID-E29CAFA8-523D-57D2-AC1B-D6D01741550B.dita"><linktext>Window Server

Internals: Concepts</linktext></link>

<link href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">

<linktext>Render Stages Overview </linktext></link>

</related-links></concept>