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-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC" xml:lang="en"><title>Redraw

    13 Stores</title><shortdesc>Redraw stores store the sequence of drawing commands representing

    14 window contents. Whenever possible, the Window Server performs server-initiated

    15 redraws by repeating the sequence of stored commands, rather than by sending

    16 redraw requests to the client. This minimises the number of client-server

    17 transactions and means that redraws are done as soon as the server detects

    18 that they are needed. This topic explains some of the background to redraw

    19 stores. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    20 <p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target audience</b>:

    21 Device creators. </p>

    22 <p>The classes involved with redraw stores are as follows: </p>

    23 <fig id="GUID-85C23EC3-BADE-5DE1-872D-0D8399209874">

    24 <title>           Redraw stores class diagram          </title>

    25 <image href="GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e201481_href.png" placement="inline"/>

    26 </fig>

    27 <p> <xref href="GUID-FF963788-695A-320F-9E81-76E45B0287D1.dita"><apiname>CWsRedrawMsgWindow</apiname></xref> is the class representing a redraw

    28 store. Draw commands are stored in a number of segments, stored in the nested

    29 class <xref href="GUID-53F68722-1A1D-30D8-960E-226843AB56E1.dita"><apiname>CRedrawSegment</apiname></xref>. </p>

    30 <p>Redraw drawing takes place as follows: </p>

    31 <ol id="GUID-2C26C7D9-1C38-55E1-BF14-A36A9F9F05F3">

    32 <li id="GUID-2FCE8CBF-6BF3-5033-8BB7-935D0B276F7C"><p>A call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref> causes

    33 either the whole window, or a rectangle within it, to be marked as invalid. </p> </li>

    34 <li id="GUID-EB4CAD7F-1B3C-5D2A-85FD-31D0C7F9503D"><p>Next, a call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> is

    35 made, either for the whole window or for a rectangle within it. </p> </li>

    36 <li id="GUID-88AF657A-8C5E-5CE8-BEF9-F8C1E34F6174"><p>Draw operations take

    37 place. </p> </li>

    38 <li id="GUID-58BC4A48-5035-582D-BE17-C15A885F4B5F"><p>Finally there is a call

    39 to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li>

    40 </ol>

    41 <p>In this sequence, the draw operations within the <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets

    42 are interpreted as <i>replacing</i> whatever drawing was previously present

    43 in the affected rectangle. </p>

    44 <p>It is important to bracket all drawing within <codeph>BeginRedraw(TRect)</codeph> and <codeph>EndRedraw(TRect)</codeph> calls.

    45 In ScreenPlay, the Window Server ignores all drawing not within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets

    46 and triggers a full-window redraw. In debug builds, there is an option to

    47 panic clients violating this convention. </p>

    48 <p>For more information, see <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">Redraw

    49 Drawing</xref>. </p>

    50 <section id="GUID-27FE041D-3DE3-4290-AF6D-38DDB8970008"><title>Redraw segments and non-redraw handling</title> <p>When the

    51 Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw

    52 bracket is stored in a single <b>redraw segment</b>. The segment is marked

    53 as <codeph>ESegmentTypePendingRedraw</codeph> while it is being received,

    54 and <codeph>ESegmentTypeRedraw</codeph> once it is complete. </p> <p>Redraw

    55 segments have a region to which they apply. For <codeph>ESegmentTypeRedraw</codeph>,

    56 the region is initially set to be the rectangle passed into the <codeph>BeginRedraw()</codeph> call.

    57 When a new<codeph>ESegmentTypeRedraw</codeph> is created, its region is subtracted

    58 from the regions of all existing segments. This reflects the fact that redraw

    59 drawing <i>replaces</i> existing drawing. If, as a consequence of new redraw

    60 drawing, the region of an existing segment becomes empty, that segment is

    61 discarded. Its drawing has been replaced everywhere, so it is no longer needed. </p> <p>What

    62 happens to drawing that is received between an <codeph>EndRedraw</codeph> and

    63 the next <codeph>BeginRedraw</codeph> —and which is therefore <b>non-redraw

    64 drawing</b> —depends on which variant is in use: </p> <ul>

    65 <li id="GUID-0B29AC2F-AD48-5EAB-B3BE-B8FC296B092A"><p>In ScreenPlay, non-redraw

    66 drawing is not stored in a segment but instead triggers the Window Server

    67 to invalidate the entire window. This means that the client application must

    68 then perform a full window redraw. </p> </li>

    69 <li id="GUID-B592A6D0-68B7-5A16-B179-9F78C5FCDBB3"><p>In the non-ScreenPlay

    70 variant, non-redraw drawing is stored in a segment marked as <codeph>ESegmentTypeNonRedraw</codeph>.

    71 For these segments the region is initially set to be the whole window and

    72 does not affect the regions of existing segments, because non-redraw drawing

    73 is drawn over existing drawing. </p> </li>

    74 </ul> </section>

    75 <section id="GUID-DB24B91E-6628-4B6E-AE9A-ACAB30AA02C3"><title> Redraw store playback</title> <p>When playback is required,

    76 the redraw store goes through the redraw segments and replays them if the

    77 region for the segment intersects the region that is to be redrawn. It follows

    78 from the way that they are managed that the regions of redraw segments are

    79 mutually disjoint. This means that in ScreenPlay they can be replayed in any

    80 order. This is also true in the non-ScreenPlay when there are only redraw

    81 segments present. </p> <p>In the non-ScreenPlay variant, any non-redraw segments

    82 are replayed in earliest-first order, because they draw on top of earlier

    83 drawing. </p> </section>

    84 <section id="GUID-74EC09C2-BB39-42B2-B765-191A7E17A4D6"><title> Aging of non-redraw segments</title> <p> <b>Variant</b>:

    85 Non-ScreenPlay only. </p> <p>Non-redraw segments can cause inefficient operation

    86 of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw

    87 segments are still used, the Window Server "ages" them. That is, non-redraw

    88 segments are considered to have a finite lifetime, after which they are discarded.

    89 When a non-redraw segment is discarded, the Window Server makes a redraw request

    90 to the client asking it to provide new draw operations for the invalid region. </p> <p>The

    91 lifetime for non-redraw segments is set in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI

    92 file</xref> using the parameter <codeph>NONREDRAWAGELIMIT</codeph>, followed

    93 by a duration in microseconds. If this line is not present in the <codeph>WSINI.INI</codeph>,

    94 a default of one second is used. </p> </section>

    95 <section id="GUID-8CE71B67-21F3-4D16-9A1A-70A70A24EFD3"><title>Atomic Redraws</title> <p> <b>Variant</b>: Both (ScreenPlay

    96 and non-ScreenPlay). </p> <p>Another <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI

    97 file</xref> setting that affects redraw storing is <codeph>ATOMICREDRAWS</codeph>.

    98 If this parameter is present, new draw operations received after a <codeph>BeginRedraw()</codeph> are

    99 not considered valid until the corresponding <codeph>EndRedraw()</codeph> is

   100 received. In particular, a new segment does not replace existing segments

   101 until it is complete. This has the consequence that if redraw store playback

   102 is required before the <codeph>EndRedraw()</codeph> for a new segment is received,

   103 draw operations from old segments for that region are used instead. Thus drawing

   104 within <codeph>Begin/EndRedraw</codeph> brackets can be considered as an atomic

   105 operation. This eliminates one potential source of flicker. </p> </section>

   106 </conbody><related-links>

   107 <link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics

   108 and Drawing </linktext></link>

   109 <link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini

   110 File Reference</linktext></link>

   111 </related-links></concept>