1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-E5CDDA05-CD86-5C44-B9DA-3249D9C14396" xml:lang="en"><title>Client-Side

    13 Buffer</title><shortdesc>The Window Server client-side buffer enables drawing functions

    14 to be buffered and executed in sequence. This saves many client-server context

    15 switches and makes the system fast and responsive. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    16 <p>The Window Server handles many application function calls

    17 as follows: </p>

    18 <ol id="GUID-F51202BB-1519-5B86-BAAA-6B07D7D33DD2">

    19 <li id="GUID-6A0CC5DF-EB2B-5EF0-BA71-269A5472C0E7"><p>The client packages

    20 the information to send to the server. </p> </li>

    21 <li id="GUID-D3D22D1E-4C7D-5B9A-8F73-1730F9CD6979"><p>A context switch to

    22 the server. </p> </li>

    23 <li id="GUID-13D28353-8E11-5445-91B6-5D31550C0C9D"><p>Processing in the Window

    24 Server—with possible inter-thread communication to and from the client. </p> </li>

    25 <li id="GUID-7B29EB4D-80D6-53DB-AC13-9D3618FB3AE2"><p>A context switch back

    26 to the client. </p> </li>

    27 </ol>

    28 <p>This guarantees that operations are performed in the right sequence and

    29 that operations have been performed when control returns to the application

    30 program. </p>

    31 <p>However, for drawing and many other function calls, this approach is too

    32 slow, and is not strictly necessary. </p>

    33 <ul>

    34 <li id="GUID-CDEC7D13-E43B-529B-88DD-C7542BE16AA0"><p>The overheads of the

    35 client/server communication swamp the time needed for drawing and cause severe

    36 system degradation. </p> </li>

    37 <li id="GUID-55A4C852-B5B0-55FE-9E62-38C21613BFFC"><p>It is unnecessary because

    38 the client program does not need a result from drawing functions. This is

    39 also true for some non-drawing functions. </p> </li>

    40 </ul>

    41 <p>Because of this, drawing functions, and other functions that do not need

    42 a synchronous response, are buffered by the client interface in a command

    43 buffer. When necessary, this buffer is flushed by a call to the Window Server,

    44 which executes all the drawing functions in sequence. Thus, two context switches

    45 are sufficient for an entire buffer full of drawing requests. </p>

    46 <p>The Window Server buffer is flushed when: </p>

    47 <ul>

    48 <li id="GUID-54B10BF7-7007-56A6-9C88-CF9C22549FF1"><p>It is full. </p> </li>

    49 <li id="GUID-7EE4C889-BEBB-54FA-8FA2-3A5DE1F2B24C"><p>A function requiring

    50 a result is called. </p> </li>

    51 <li id="GUID-0F9FA1C9-23AD-5C90-B670-A3D2D1653C47"><p>One of the event-request

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

    53 <li id="GUID-927412D4-1700-59BE-B0BB-B75366D28A36"><p>Certain high-level functions

    54 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>,

    55 which involve mass data transfer which would overflow the buffer, and which

    56 may fail. </p> </li>

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

    58 is made. </p> </li>

    59 <li id="GUID-0B9C1E0F-F6D5-5999-A170-263738C39C7D"><p>After any function call

    60 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

    61 is set on. </p> </li>

    62 </ul>

    63 <p>It is desirable that the buffer is flushed when the application has finished

    64 a unit of drawing. This is usually done as a natural consequence of calling

    65 the function to wait for the next event from the Window Server. This covers

    66 all cases where drawing is initiated in response to a Window Server event.

    67 There are a few cases where drawing is initiated in response to other events.

    68 In these cases, an explicit <codeph>Flush()</codeph> call must be made. </p>

    69 <p>The use of a buffer has two main impacts on drawing logic: </p>

    70 <ul>

    71 <li id="GUID-29455CA7-A061-5279-8FD0-DCCBB7E4CB76"><p>While debugging, client

    72 requests do not immediately result in screen updates. This can make debugging

    73 confusing at times. </p> </li>

    74 <li id="GUID-59002F65-4334-5C7B-A071-DB9D8A723B66"><p>If this is a problem,

    75 the application program can turn on auto-flushing, which causes flushing after

    76 each function call. The Uikon UI provides a hot-key, CTRL+ALT+SHIFT+F, to

    77 turn on auto-flushing. (The resulting degradation in performance is a convincing

    78 demonstration of the need for the buffer). </p> </li>

    79 <li id="GUID-7927A766-7C23-514D-97EA-CE420FCCD489"><p>The GDI is so fast that

    80 most drawing activity that takes place within the context of a single flush

    81 appears as an almost instantaneous update. If, however, a drawing sequence

    82 is interrupted by a flush, there may be a perceptible delay. In some circumstances,

    83 this may result in flicker. </p> </li>

    84 <li id="GUID-148AF35C-3B8A-5DC0-BC7E-0D6503877CE3"><p>The aesthetics of a

    85 program can be badly affected by flicker during drawing. Applications should

    86 use flicker-free functions (such as <codeph>DrawText()</codeph> with a rectangle),

    87 and try to minimize flushing during critical redraw sequences. If completely

    88 flicker-free drawing is impossible, short drawing sequences that are flush-free

    89 may sometimes be an acceptable alternative. </p> </li>

    90 </ul>

    91 <p>The Window Server manages the buffer intelligently so as to minimize flushing.

    92 The opcodes stored in the buffer are short, and repeated use of the same graphics

    93 context is indicated by a single bit rather than repeated reference to the

    94 graphics context. </p>

    95 <p>Applications may modify the size, or the maximum size of the buffer to

    96 tune performance or to accommodate long messages. A larger buffer may reduce

    97 flicker by collecting more drawing commands. A smaller buffer uses less memory.

    98 Setting a maximum size allows the Window Server to perform its own optimizations. </p>

    99 <p>If a message is too big for the buffer, a panic (#5 - <codeph>EW32PanicDataExceedsBufferLength</codeph>)

   100 occurs. optimizations </p>

   101 </conbody><related-links>

   102 <link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server

   103 Client-Side Library Concepts</linktext></link>

   104 </related-links></concept>