1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-599C9890-3AC8-46D3-A8C3-34CAAB5A61CF" xml:lang="en"><title>Implementing

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

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

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

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

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

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

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

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

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

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

    23 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

    24 SetBackgroundSurface(const TSurfaceConfiguration& aConfiguration, TBool

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

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

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

    28 </ol>

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

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

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

    32 <thead>

    33 <row>

    34 

    35 <entry>API</entry>

    36 <entry>Description</entry>

    37 </row>

    38 </thead>

    39 <tbody>

    40 <row>

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

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

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

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

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

    46 </row>

    47 <row>

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

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

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

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

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

    53 composition. </p> </li>

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

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

    56 </ul> </entry>

    57 </row>

    58 <row>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    80 surface. </p> </li>

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

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

    83 </row>

    84 </tbody>

    85 </tgroup>

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

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

    88 Implementation Overview</linktext></link>

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

    90 eglSwapBuffers</linktext></link>

    91 </related-links></concept>