Symbian3/SDK/Source/GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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>