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