<?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-599C9890-3AC8-46D3-A8C3-34CAAB5A61CF" xml:lang="en"><title>Implementing

eglCreateWindowSurface</title><shortdesc>This topic explains how to implement <codeph>eglCreateWindowSurface()</codeph> on

the Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The steps are as follows: </p>

<ol id="GUID-1D81FCB9-DE07-56FD-84A1-CAC09B3C753C">

<li id="GUID-3A8FC68D-BD07-5DEF-AD4D-9C2D0D0844C5"><p>Use <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref> and

typically <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> to create a composition surface. The details

vary depending on the type of memory that is to be used for the composition

surface's buffers. For example, the details are different when specialized

graphics memory is used rather than standard CPU memory. </p> </li>

<li id="GUID-628EE035-0045-51D6-8C1D-AE867CA37FA3"><p>Assign the composition

surface to an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> by calling: </p> <p> <xref href="GUID-57C48AD3-2EC4-3812-BA97-CB6597937615.dita"><apiname>TInt

SetBackgroundSurface(const TSurfaceConfiguration& aConfiguration, TBool

aTriggerRedraw); </apiname></xref>  </p> <p>Ensure that both the extent

and viewport of the <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref> are set to the

full extent of the surface. </p> </li>

</ol>

<p>The following table provides a summary of the key APIs. </p>

<table id="GUID-52137B22-D71F-51DC-BEF4-B5476E8ECC0E">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref>  </p> </entry>

<entry><p>The client-side API of the <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface

Manager</xref>. This provides methods to create, open and close composition

surfaces and to map a composition surface to an actual memory address. </p> <p>Use

this API to create the composition surface. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref>  </p> </entry>

<entry><p>The client-side API of the <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface

Update Server</xref>. This provides a channel for a surface's stakeholders

to inform each other of changes. </p> <p>Use this as follows: </p> <ul>

<li id="GUID-64DC6FF3-B48B-5079-A8EE-ED69BD92E813"><p>To post a buffer for

composition. </p> </li>

<li id="GUID-59AFDD28-64E4-58CF-8F65-5FDB459A12B9"><p>To wait for the composition

of a buffer to complete. </p> </li>

</ul> </entry>

</row>

<row>

<entry><p> <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-4EBFFA14-418A-3A2A-B147-39BFC96CE45F"><apiname>RWindowBase::SetBackgroundSurface()</apiname></xref>  </p> </entry>

<entry><p>Part of the Window Server client-side API, this function sets the

background of a window to be a given composition surface (called an <b>external

surface</b> in the <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">Window

Server documentation</xref>). This means that when an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> is

moved, Window Server automatically moves its associated background surface. </p> <p>This

function does the following: </p> <ul>

<li id="GUID-203657E0-994E-52B9-A5D7-F1112897B5C5"><p>Positions the composition

surface in a layer below the UI layer, positioned directly below the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> </li>

<li id="GUID-E3711F2C-9159-54FE-B4FC-840584172FA0"><p>Sets the background

color of the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> to transparent. This allows the composition

surface to show through. Any existing <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing

to the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> is retained in the foreground. </p> </li>

</ul> <p>There are two forms of this function: </p> <ul>

<li id="GUID-08D9FB05-D43D-5E1B-B95E-C8E5945EE851"><p>One simply takes the

surface ID as an argument. This auto-stretches the background surface to fit

the window and causes temporary distortion of the EGL window surface between

a resize occurring and the next call to <codeph>eglSwapBuffers()</codeph>. </p> </li>

<li id="GUID-FB1AFE20-42F1-5229-A4AA-9AD551ABA264"><p>The other has two arguments—a <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref> and

a <codeph>TBool</codeph>. You can set the extent and viewport in the <codeph>TSurfaceConfiguration</codeph> to

match the full extent of the surface. This avoids the auto-stretching of the

surface. </p> </li>

</ul> <p>See <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External

Surfaces Overview</xref> for an introduction to some of the key concepts. </p> </entry>

</row>

</tbody>

</tgroup>

</table></conbody><related-links>

<link href="GUID-0B2421FD-8431-5DDA-9FE3-046734AE495E.dita"><linktext>Window Surface

Implementation Overview</linktext></link>

<link href="GUID-42984078-3DEB-41C7-AC76-C769F7CDB4D0.dita"><linktext>Implementing

eglSwapBuffers</linktext></link>