<?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&amp; 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>
</related-links></concept>