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