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-667E7F90-D6C2-55CE-AE60-6C938072FB9C" xml:lang="en"><title>Graphics

    13 and Drawing Overview</title><shortdesc>This topic provides an introduction to drawing graphics to the

    14 screen. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p> <b>Variant</b>: Both (ScreenPlay and non-ScreenPlay). <b>Target

    16 audience</b>: Application developers. </p>

    17 <p>Applications can draw to any <codeph>RDrawableWindow</codeph> —such as

    18 an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> —via a graphics device, of type <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>,

    19 and a graphics context, of type <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>. These classes

    20 are derived from the <xref href="GUID-B6D4AEE9-5C17-51D9-BBDE-7CCB5218279D.dita">GDI

    21 component</xref> classes <xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref> and <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref>,

    22 respectively. This means that general drawing functions can be used for drawing

    23 to windows, as well as to other graphics devices. The Window Server itself

    24 does not provide the facilities to draw graphics to a physical device. <codeph>CWindowGc</codeph> functions

    25 are not passed to the Window Server directly. Rather, they are stored in a

    26 buffer maintained by the Window Server Client API. This buffer is flushed

    27 to the Window Server only rarely. By this means the context switching involved

    28 in drawing is minimised, and system performance significantly enhanced. </p>

    29 <p> <codeph>CWsScreenDeviceminimized</codeph> encapsulates the device-dependent

    30 aspects of graphics operations. Graphics functions are not carried out directly

    31 via a <codeph>CWsScreenDevice</codeph>, however, but via a graphics context

    32 with which it is associated. The graphics context class, <codeph>CWindowGc</codeph>,

    33 provides a rich set of drawing functions, including functions to draw lines,

    34 arcs, polygons, text and bitmaps. </p>

    35 <p>A graphics context contains a collection of configurable parameters concerned

    36 with graphics, such as pen width, pen color, brush color. It is stored in

    37 the server, thus reducing the amount of information that has to be sent with

    38 each graphics call. The graphics call simply specifies the graphics context

    39 it wishes to use, and a single graphics context can be shared between multiple

    40 windows. </p>

    41 <p>To draw to a graphics context it must be associated with a window. Typically

    42 a graphics context is created when a session is constructed, and that graphics

    43 context is shared between several windows in the application. When the window

    44 needs to use the graphics context it calls <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-1C0F9DF6-23C2-3707-8F2B-0A738467FF0A"><apiname>CWindowGc::Activate()</apiname></xref>.

    45 If necessary it can change the graphics context's settings. <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-E977DBB2-8547-3AB7-99E3-9D246DA6CF58"><apiname>CWindowGc::Deactivate()</apiname></xref> should

    46 be called first if the graphics context is currently active upon another window. </p>

    47 <p>Several optimizations are used by the Window Server to obtain high-performance

    48 graphics: </p>

    49 <ul>

    50 <li id="GUID-C8AC84D6-AF17-5975-88B8-CC93C499DFA0"><p>Each window is associated

    51 with an <codeph>RWsSession</codeph> which is in turn associated with a client-side

    52 buffer. Instead of implementing graphics operations by a direct client-server

    53 call, which involves expensive context switching, all graphics operations

    54 are stored as opcodes in the buffer, and the buffer is only flushed in certain

    55 circumstances. </p> </li>

    56 <li id="GUID-00B3FC8E-25DE-542F-BF67-0F71CF22526A"><p>The <codeph>CFbsBitmap</codeph> class

    57 allows a bitmap to be shared between all threads in the system, including

    58 the client and the Window Server. This sharing is mediated by the <xref href="GUID-A03FB1BF-F67B-519D-A904-74CA3F8375D9.dita">Font

    59 and Bitmap server</xref>. The <xref href="GUID-17150D76-BB82-3A4B-8B1A-8BA93CB1A9EF.dita"><apiname>CWsBitmap</apiname></xref> class eliminates

    60 further context switches by taking ownership of the handle of the bitmap.

    61 Applications can use this class to more efficiently open, blit-to-screen,

    62 and close a series of bitmaps. Use functions that take a <codeph>CWsBitmap</codeph> in

    63 preference to those that take a <codeph>CFbsBitmap</codeph>, because they

    64 are faster. </p> </li>

    65 <li id="GUID-550D1374-C166-54C6-A055-0CA040691654"><p>A single graphics context

    66 may be used for drawing to many windows—it is not necessary to have one per

    67 window. The <codeph>Activate()</codeph> function associates a <codeph>CWindowGc</codeph> with

    68 a particular window. </p> </li>

    69 <li id="GUID-91AFC884-0BB2-5A73-B757-94EF1B2328A7"><p>Provided drawing operations

    70 to an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> are performed as <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">redraw

    71 drawing</xref>, the Window Server stores the sequence of drawing commands

    72 that represent the window contents in redraw stores. Then when the Window

    73 Server needs to repaint the window (because, for example, a dialog box popped

    74 up over it and has now closed) it simply replays the sequence of stored commands,

    75 rather than sending a redraw request to the client. This minimizes the number

    76 of client-server transactions and means that windows are repainted as soon

    77 as the Window Server detects that they are needed. </p> <p>This means that

    78 all <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing should now be redraw drawing, which

    79 means that it takes place between <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> and <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> calls.

    80 If you use the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-D5458F8C-E199-37DD-B821-050B749122C6"><apiname>CCoeControl::DrawNow()</apiname></xref> and <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-9FB682AC-0209-302A-83F3-7BCB1162B998"><apiname>CCoeControl::DrawDeferred()</apiname></xref> methods,

    81 the UI Control Framework (CONE) takes care of this for you. See <xref href="GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita">Redraw

    82 Drawing</xref> for more information. </p> </li>

    83 </ul>

    84 </conbody><related-links>

    85 <link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics

    86 and Drawing </linktext></link>

    87 <link href="GUID-6C16417B-5B37-5310-B59A-750D971AA6D4-GENID-1-8-1-3-1-1-7-1.dita"><linktext>The UI Control

    88 Framework (CONE)</linktext></link>

    89 </related-links></concept>