<?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-E5CDDA05-CD86-5C44-B9DA-3249D9C14396" xml:lang="en"><title>Client-Side
Buffer</title><shortdesc>The Window Server client-side buffer enables drawing functions
to be buffered and executed in sequence. This saves many client-server context
switches and makes the system fast and responsive. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The Window Server handles many application function calls
as follows: </p>
<ol id="GUID-F51202BB-1519-5B86-BAAA-6B07D7D33DD2">
<li id="GUID-6A0CC5DF-EB2B-5EF0-BA71-269A5472C0E7"><p>The client packages
the information to send to the server. </p> </li>
<li id="GUID-D3D22D1E-4C7D-5B9A-8F73-1730F9CD6979"><p>A context switch to
the server. </p> </li>
<li id="GUID-13D28353-8E11-5445-91B6-5D31550C0C9D"><p>Processing in the Window
Server—with possible inter-thread communication to and from the client. </p> </li>
<li id="GUID-7B29EB4D-80D6-53DB-AC13-9D3618FB3AE2"><p>A context switch back
to the client. </p> </li>
</ol>
<p>This guarantees that operations are performed in the right sequence and
that operations have been performed when control returns to the application
program. </p>
<p>However, for drawing and many other function calls, this approach is too
slow, and is not strictly necessary. </p>
<ul>
<li id="GUID-CDEC7D13-E43B-529B-88DD-C7542BE16AA0"><p>The overheads of the
client/server communication swamp the time needed for drawing and cause severe
system degradation. </p> </li>
<li id="GUID-55A4C852-B5B0-55FE-9E62-38C21613BFFC"><p>It is unnecessary because
the client program does not need a result from drawing functions. This is
also true for some non-drawing functions. </p> </li>
</ul>
<p>Because of this, drawing functions, and other functions that do not need
a synchronous response, are buffered by the client interface in a command
buffer. When necessary, this buffer is flushed by a call to the Window Server,
which executes all the drawing functions in sequence. Thus, two context switches
are sufficient for an entire buffer full of drawing requests. </p>
<p>The Window Server buffer is flushed when: </p>
<ul>
<li id="GUID-54B10BF7-7007-56A6-9C88-CF9C22549FF1"><p>It is full. </p> </li>
<li id="GUID-7EE4C889-BEBB-54FA-8FA2-3A5DE1F2B24C"><p>A function requiring
a result is called. </p> </li>
<li id="GUID-0F9FA1C9-23AD-5C90-B670-A3D2D1653C47"><p>One of the event-request
functions is called (<xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-0F961C4D-A731-3AE0-8425-BB304CCF2736"><apiname>RWsSession::EventReady()</apiname></xref>, <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-DADAFFD6-4B63-35EE-8F50-F397C119CC27"><apiname>RWsSession::RedrawReady()</apiname></xref>, <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-97E7096D-930B-3CA5-9645-7BD60D0FADDD"><apiname>RWsSession::PriorityKeyReady()</apiname></xref>). </p> </li>
<li id="GUID-927412D4-1700-59BE-B0BB-B75366D28A36"><p>Certain high-level functions
are called by the client, such as <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-76018E73-B3D8-33B7-970F-0B6300F7EFB2"><apiname>CWindowGc::DrawPolyLine()</apiname></xref>,
which involve mass data transfer which would overflow the buffer, and which
may fail. </p> </li>
<li id="GUID-35BFA73D-CE16-5B49-9C89-840F7A7222A3"><p>An explicit <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> call
is made. </p> </li>
<li id="GUID-0B9C1E0F-F6D5-5999-A170-263738C39C7D"><p>After any function call
if the <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-0F337487-1104-3F97-800A-3393C9EDD116"><apiname>RWsSession::SetAutoFlush()</apiname></xref> auto flushing function
is set on. </p> </li>
</ul>
<p>It is desirable that the buffer is flushed when the application has finished
a unit of drawing. This is usually done as a natural consequence of calling
the function to wait for the next event from the Window Server. This covers
all cases where drawing is initiated in response to a Window Server event.
There are a few cases where drawing is initiated in response to other events.
In these cases, an explicit <codeph>Flush()</codeph> call must be made. </p>
<p>The use of a buffer has two main impacts on drawing logic: </p>
<ul>
<li id="GUID-29455CA7-A061-5279-8FD0-DCCBB7E4CB76"><p>While debugging, client
requests do not immediately result in screen updates. This can make debugging
confusing at times. </p> </li>
<li id="GUID-59002F65-4334-5C7B-A071-DB9D8A723B66"><p>If this is a problem,
the application program can turn on auto-flushing, which causes flushing after
each function call. The Uikon UI provides a hot-key, CTRL+ALT+SHIFT+F, to
turn on auto-flushing. (The resulting degradation in performance is a convincing
demonstration of the need for the buffer). </p> </li>
<li id="GUID-7927A766-7C23-514D-97EA-CE420FCCD489"><p>The GDI is so fast that
most drawing activity that takes place within the context of a single flush
appears as an almost instantaneous update. If, however, a drawing sequence
is interrupted by a flush, there may be a perceptible delay. In some circumstances,
this may result in flicker. </p> </li>
<li id="GUID-148AF35C-3B8A-5DC0-BC7E-0D6503877CE3"><p>The aesthetics of a
program can be badly affected by flicker during drawing. Applications should
use flicker-free functions (such as <codeph>DrawText()</codeph> with a rectangle),
and try to minimize flushing during critical redraw sequences. If completely
flicker-free drawing is impossible, short drawing sequences that are flush-free
may sometimes be an acceptable alternative. </p> </li>
</ul>
<p>The Window Server manages the buffer intelligently so as to minimize flushing.
The opcodes stored in the buffer are short, and repeated use of the same graphics
context is indicated by a single bit rather than repeated reference to the
graphics context. </p>
<p>Applications may modify the size, or the maximum size of the buffer to
tune performance or to accommodate long messages. A larger buffer may reduce
flicker by collecting more drawing commands. A smaller buffer uses less memory.
Setting a maximum size allows the Window Server to perform its own optimizations. </p>
<p>If a message is too big for the buffer, a panic (#5 - <codeph>EW32PanicDataExceedsBufferLength</codeph>)
occurs. optimizations </p>
</conbody><related-links>
<link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server
Client-Side Library Concepts</linktext></link>
</related-links></concept>