<?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-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC" xml:lang="en"><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_d0e251189_href.png" placement="inline"/>

</fig>

<p> <xref href="GUID-FF963788-695A-320F-9E81-76E45B0287D1.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-53F68722-1A1D-30D8-960E-226843AB56E1.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-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><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-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><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-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>

</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 id="GUID-27FE041D-3DE3-4290-AF6D-38DDB8970008"><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 <codeph>ESegmentTypePendingRedraw</codeph> while it is being received,

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

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

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

When a new<codeph>ESegmentTypeRedraw</codeph> 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 <codeph>ESegmentTypeNonRedraw</codeph>.

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 id="GUID-DB24B91E-6628-4B6E-AE9A-ACAB30AA02C3"><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 id="GUID-74EC09C2-BB39-42B2-B765-191A7E17A4D6"><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 id="GUID-8CE71B67-21F3-4D16-9A1A-70A70A24EFD3"><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 <codeph>BeginRedraw()</codeph> are

not considered valid until the corresponding <codeph>EndRedraw()</codeph> 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 <codeph>EndRedraw()</codeph> 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>