<?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_d0e196473_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>