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