--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E5CDDA05-CD86-5C44-B9DA-3249D9C14396.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,104 @@
+<?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>
\ No newline at end of file