<?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 xml:lang="en" id="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC"><title>Redraw Stores</title><shortdesc>Redraw stores store the sequence of drawing commands representing window contents. Whenever possible, the Window Server performs server-initiated redraws by repeating the sequence of stored commands, rather than by sending redraw requests to the client. This minimises the number of client-server transactions and means that redraws are done as soon as the server detects that they are needed. This topic explains some of the background to redraw stores. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target audience</b>: Device creators. </p> <p>The classes involved with redraw stores are as follows: </p> <fig id="GUID-85C23EC3-BADE-5DE1-872D-0D8399209874"><title>

          Redraw stores class diagram 

        </title> <image href="GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e172894_href.png" placement="inline"/></fig> <p> <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>CWsRedrawMsgWindow</apiname></xref> is the class representing a redraw store. Draw commands are stored in a number of segments, stored in the nested class <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>CRedrawSegment</apiname></xref>. </p> <p>Redraw drawing takes place as follows: </p> <ol id="GUID-2C26C7D9-1C38-55E1-BF14-A36A9F9F05F3"><li id="GUID-2FCE8CBF-6BF3-5033-8BB7-935D0B276F7C"><p>A call to <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>RWindow::Invalidate()</apiname></xref> causes either the whole window, or a rectangle within it, to be marked as invalid. </p> </li> <li id="GUID-EB4CAD7F-1B3C-5D2A-85FD-31D0C7F9503D"><p>Next, a call to <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>RWindow::BeginRedraw()</apiname></xref> is made, either for the whole window or for a rectangle within it. </p> </li> <li id="GUID-88AF657A-8C5E-5CE8-BEF9-F8C1E34F6174"><p>Draw operations take place. </p> </li> <li id="GUID-58BC4A48-5035-582D-BE17-C15A885F4B5F"><p>Finally there is a call to <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> </li> </ol> <p>In this sequence, the draw operations within the <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets are interpreted as <i>replacing</i> whatever drawing was previously present in the affected rectangle. </p> <p>It is important to bracket all drawing within <codeph>BeginRedraw(TRect)</codeph> and <codeph>EndRedraw(TRect)</codeph> calls. In ScreenPlay, the Window Server ignores all drawing not within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> brackets and triggers a full-window redraw. In debug builds, there is an option to panic clients violating this convention. </p> <p>For more information, see <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">Redraw Drawing</xref>. </p> <section><title>Redraw segments and non-redraw handling</title> <p>When the Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw bracket is stored in a single <b>redraw segment</b>. The segment is marked as <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>ESegmentTypePendingRedraw</apiname></xref> while it is being received, and <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>ESegmentTypeRedraw</apiname></xref> once it is complete. </p> <p>Redraw segments have a region to which they apply. For <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>ESegmentTypeRedraw</apiname></xref>, the region is initially set to be the rectangle passed into the <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>BeginRedraw()</apiname></xref> call. When a new <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>ESegmentTypeRedraw</apiname></xref> is created, its region is subtracted from the regions of all existing segments. This reflects the fact that redraw drawing <i>replaces</i> existing drawing. If, as a consequence of new redraw drawing, the region of an existing segment becomes empty, that segment is discarded. Its drawing has been replaced everywhere, so it is no longer needed. </p> <p>What happens to drawing that is received between an <codeph>EndRedraw</codeph> and the next <codeph>BeginRedraw</codeph> —and which is therefore <b>non-redraw drawing</b> —depends on which variant is in use: </p> <ul><li id="GUID-0B29AC2F-AD48-5EAB-B3BE-B8FC296B092A"><p>In ScreenPlay, non-redraw drawing is not stored in a segment but instead triggers the Window Server to invalidate the entire window. This means that the client application must then perform a full window redraw. </p> </li> <li id="GUID-B592A6D0-68B7-5A16-B179-9F78C5FCDBB3"><p>In the non-ScreenPlay variant, non-redraw drawing is stored in a segment marked as <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>ESegmentTypeNonRedraw</apiname></xref>. For these segments the region is initially set to be the whole window and does not affect the regions of existing segments, because non-redraw drawing is drawn over existing drawing. </p> </li> </ul> </section> <section><title> Redraw store playback</title> <p>When playback is required, the redraw store goes through the redraw segments and replays them if the region for the segment intersects the region that is to be redrawn. It follows from the way that they are managed that the regions of redraw segments are mutually disjoint. This means that in ScreenPlay they can be replayed in any order. This is also true in the non-ScreenPlay when there are only redraw segments present. </p> <p>In the non-ScreenPlay variant, any non-redraw segments are replayed in earliest-first order, because they draw on top of earlier drawing. </p> </section> <section><title> Aging of non-redraw segments</title> <p> <b>Variant</b>: Non-ScreenPlay only. </p> <p>Non-redraw segments can cause inefficient operation of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw segments are still used, the Window Server "ages" them. That is, non-redraw segments are considered to have a finite lifetime, after which they are discarded. When a non-redraw segment is discarded, the Window Server makes a redraw request to the client asking it to provide new draw operations for the invalid region. </p> <p>The lifetime for non-redraw segments is set in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI file</xref> using the parameter <codeph>NONREDRAWAGELIMIT</codeph>, followed by a duration in microseconds. If this line is not present in the <codeph>WSINI.INI</codeph>, a default of one second is used. </p> </section> <section><title>Atomic Redraws</title> <p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). </p> <p>Another <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">WSINI.INI file</xref> setting that affects redraw storing is <codeph>ATOMICREDRAWS</codeph>. If this parameter is present, new draw operations received after a <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>BeginRedraw()</apiname></xref> are not considered valid until the corresponding <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>EndRedraw()</apiname></xref> is received. In particular, a new segment does not replace existing segments until it is complete. This has the consequence that if redraw store playback is required before the <xref href="GUID-29A3C74B-1599-3F6A-8B47-DADD2A220D6F.dita"><apiname>EndRedraw()</apiname></xref> for a new segment is received, draw operations from old segments for that region are used instead. Thus drawing within <codeph>Begin/EndRedraw</codeph> brackets can be considered as an atomic operation. This eliminates one potential source of flicker. </p> </section> </conbody><related-links><link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics and Drawing </linktext> </link> <link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini File

                Reference</linktext> </link> </related-links></concept>