<?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>
<image href="GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e172684_href.png" placement="inline"/>
</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>
<image href="GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e172746_href.png" placement="inline"/>
</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>
<image href="GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e172844_href.png" placement="inline"/>
</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>

</related-links></concept>