<?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-0B2421FD-8431-5DDA-9FE3-046734AE495E" xml:lang="en"><title>Window Surface Implementation</title><shortdesc>This topic provides an introduction to implementing EGL
window surfaces on the Symbian platform. These are used for onscreen
rendering into windows that are provided by the Symbian platform (rather
than EGL). The details of how to implement window surfaces depend
on whether the ScreenPlay variant is in use. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p> <b>Target audience</b>: Device creators. </p>
<section id="GUID-C4343FE3-9351-4E5D-A398-FDD9292BB507"><title>Symbian windows</title> <p>Window surfaces are created
by the <codeph>eglCreateWindowSurface()</codeph> function, to which
is passed a handle to a window provided by the Symbian <xref href="GUID-2C443E6F-BC3D-5252-8098-9F850AA88A35.dita">Window Server</xref>. Key Window Server classes include the following: </p> <ul>
<li id="GUID-CE332026-A8BC-57D8-B845-F0C41CCBA4C2"> <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>, which is a handle to a standard window. </li>
<li id="GUID-DFC36F32-71B2-5502-B4A9-B95C6548751D"><xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>, which is the Window Server session class. This is required to create
Window Server objects.  </li>
<li id="GUID-B17680DB-00AD-5B8C-8199-5E03B9CB71E8"> <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>, which is a Window Server client-side object representing the screen. </li>
</ul> </section>
<section id="GUID-B7888880-E7AE-427F-9E69-0FD1B9AD5862"><title> Non-ScreenPlay </title> <p>In the non-ScreenPlay
variant there is no composition engine and both Symbian API drawing
(for example, through <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>) and EGL client
API drawing are rendered to a single display. The EGL implementation
can achieve this in a number of ways, including: </p> <ul>
<li id="GUID-332CAE78-9EBD-5DAF-A640-FEE2CBC48B73"><p>Using Direct
Screen Access (DSA) to render the EGL client API drawing directly
to the screen. This is done in cooperation with the Window Server,
which provides clipping instructions. This approach is particularly
suitable when graphics acceleration hardware is available. </p> </li>
<li id="GUID-646EE6E5-6194-5862-8225-9D756EA55ACC"><p>Rendering the
EGL client API drawing to an offscreen <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> and then calling a Window Server API to blit the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> onto the screen, with any necessary clipping. </p> </li>
</ul> </section>
<section id="GUID-02B86EC6-A3C1-4A9D-889F-BDE460F3346A"><title>ScreenPlay</title> <p>ScreenPlay has introduced the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">Graphics Composition
Collection</xref>, which enables a number of <b>surfaces</b> to be
arranged in layers and to be composed together to produce the final
output on the display. In this section, these surfaces are called <b>composition surfaces</b> in order to distinguish them from EGL surfaces.
Each composition surface is mapped to memory, which can be specialized
graphics memory for faster performance. </p> <p>All Window Server
drawing (such as the application UI) is rendered to a composition
surface called the <b>UI surface</b>, which is usually the topmost
layer and can be semi-transparent. </p><p>When the EGL implementation
creates an EGL window surface for a Symbian window (represented by <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>), the EGL implementation must do the following: </p><ul>
<li id="GUID-ECAF9CD5-0770-5D51-827B-9E30A1A14478"><p>Create a new
composition surface with the same width and height as the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> </li>
<li id="GUID-69D40D06-D691-5DC4-8AB8-7C93F74EDAE4"><p>Position the
composition surface in a layer below the UI layer, directly below
the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> </li>
<li id="GUID-19391759-8C65-5D17-96C7-A9155303442E"><p>Make the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> transparent in order for the composition surface
to show through. </p> </li>
</ul><p/><p>All of the EGL client API drawing to the EGL window
surface is then rendered to the composition surface and the application's
UI appears as a semi-transparent layer above it. </p><p>When a window
is resized, a new composition surface needs to be created with the
new width and height, and positioned as a layer below the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> in place of the previous composition surface. </p><p>A composition surface can have more than one pixel buffer associated
with it (each buffer has the same dimensions). For an EGL window surface,
the composition surface should have two (or more) buffers for double-buffered
drawing. This means, for example, that OpenVG commands can draw to
the <b>back buffer</b>, while the <b>front buffer</b> is being composed to the screen. </p> </section>
</conbody><related-links>
<link href="GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita"><linktext>EGL
Porting Guide</linktext></link>
<link href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita"><linktext>Graphics
Composition Collection Overview</linktext></link>
<link href="GUID-599C9890-3AC8-46D3-A8C3-34CAAB5A61CF.dita"><linktext>Implementing
eglCreateWindowSurface</linktext></link>
<link href="GUID-42984078-3DEB-41C7-AC76-C769F7CDB4D0.dita"><linktext>Implementing
eglSwapBuffers</linktext></link>
</related-links></concept>