--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,119 @@
+<?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_d0e201270_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_d0e201332_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_d0e201430_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>
\ No newline at end of file