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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08" xml:lang="en"><title>The

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

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

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

    16 <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

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

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

    19 and lower loops. </p>

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

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

    22 <image href="GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e172684_href.png" placement="inline"/>

    23 </fig>

    24 <p> </p>

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

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

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

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

    29 sent for a particular window). </p>

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

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

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

    33 <ul>

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

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

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

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

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

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

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

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

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

    43 </ul>

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

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

    46 <image href="GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e172746_href.png" placement="inline"/>

    47 </fig>

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

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

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

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

    52 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>

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

    54 <ul>

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

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

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

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

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

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

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

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

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

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

    65 </ul>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   101 window on the screen. </p>

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

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

   104 <image href="GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e172844_href.png" placement="inline"/>

   105 </fig>

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

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

   108 effective. </p>

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

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

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

   112 display render stage on another screen. </p>

   113 </conbody><related-links>

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

   115 </link>

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

   117 Internals: Concepts</linktext></link>

   118 

   119 </related-links></concept>