<?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-46813F51-370B-5853-917C-6916925A347D" xml:lang="en"><title>Rendering
to an RWindow Tutorial</title><shortdesc>This tutorial describes the high level steps that you need to take
when writing applications using EGL to create a window surface for on-screen
rendering. The code snippets use C style conventions. To avoid unnecessary
complexity, they do not contain complete error handling. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-2ACDC160-AB4B-42D0-9F05-ED2048D1C3F6"><title>Required background</title> <p>This tutorial assumes a background
knowledge of the following: </p> <ul>
<li id="GUID-134D7EED-0E51-5197-BE4F-2F6EF72C61B4"><xref href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita">EGL
Collection Overview</xref></li>
<li id="GUID-ADC0E050-7602-5B71-AAB4-B26D7C5B1313"> <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL
Interface Overview</xref></li>
<li id="GUID-E7DFA26B-CDA3-545C-B01F-A5BBE383D6CF"> <xref href="GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita">Symbian-Specific
EGL Behavior</xref></li>
<li id="GUID-71D99620-55D7-519D-996D-35A2962D9F84"> <xref href="GUID-04D917A1-E1A0-5149-9660-80A1146D0984.dita">OpenGL
ES</xref></li>
</ul> </section>
<section id="GUID-F95DA0B0-1DC8-4F8C-BF04-66004DA8B2DB"><title>Procedure</title> <ol id="GUID-9678FE93-DB7E-5BB2-A386-4E663F93F87A">
<li id="GUID-4795FDF0-C603-5664-87D9-8BDC987CF424"><p>You must get and initialize
the <codeph>EGLDisplay</codeph> prior to calling most other EGL or client
API functions. You only need to do this once. </p> <codeblock id="GUID-72B8ADB6-2D10-52AE-9E35-C5F1CE6AB024" xml:space="preserve">EGLDisplay display = eglGetDisplay(EGL_DEFAULT_DISPLAY);
eglInitialize(display, NULL, NULL); 
</codeblock> </li>
<li id="GUID-00811F4A-48D9-5A82-A81C-A3DD82C22FCC"><p>EGL has the concept
of <b>current rendering API</b>. To make one of the EGL client APIs the current
rendering API for the thread, call <codeph>eglBindAPI()</codeph> passing <codeph>EGL_OPENVG_API</codeph> or <codeph>EGL_OPENGLES_API</codeph> as
required. For example: </p> <codeblock id="GUID-684E7CFF-9C43-596E-B948-FA4BEED09F41" xml:space="preserve">// Set OpenGL ES as the current rendering API for the thread
eglBindAPI(EGL_OPENGLES_API); 
</codeblock> </li>
<li id="GUID-9947988E-9F8D-5003-8814-4AAC53D83D39"><p>Use the <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-7FC7E115-F659-5EA0-9BD0-AFFA717C2C00">eglChooseConfig()</xref> method to get the <codeph>EGLConfig</codeph> that
matches a list of attributes. In order to render to an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>,
these must include the <codeph>EGL_WINDOW_BIT</codeph>. </p> <codeblock id="GUID-7FD2D6BD-C86A-5F4D-BB4F-A395FB4C5190" xml:space="preserve">// List of attributes to pass to eglChooseConfig.
const EGLint    KColorRGB565AttribList[] =
    {
    EGL_RED_SIZE,         5,
    EGL_GREEN_SIZE,       6,
    EGL_BLUE_SIZE,        5,
    EGL_SURFACE_TYPE,     EGL_WINDOW_BIT,
    EGL_RENDERABLE_TYPE,  EGL_OPENGL_ES_BIT,
    EGL_NONE
    };
    
EGLint numConfigs;
EGLConfig chosenConfig = 0;
    
// Get the config to use.
eglChooseConfig(display, KColorRGB565AttribList, &amp;chosenConfig, 1, &amp;numConfigs);
    
if (numConfigs == 0)
    {
    RDebug::Printf("No matching configs found");
    User::Leave(KErrNotSupported);
    }</codeblock><p><i>Note:</i> By default the <codeph>EGL_SURFACE_TYPE</codeph> has
the <codeph>EGL_SWAP_BEHAVIOR_PRESERVED_BIT</codeph> set for window surfaces
in order to support the preserve buffer option. You can set this explicitly
like this: </p><codeblock xml:space="preserve">EGL_SURFACE_TYPE,     EGL_WINDOW_BIT|EGL_SWAP_BEHAVIOR_PRESERVED_BIT,</codeblock> </li>
<li id="GUID-AC10CA88-95F3-5335-9EA4-E77DC54344B3"><p>To create an on-screen
rendering surface, you first need to create a Symbian Window Server window
(<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>). This window is then passed as the third argument
to <codeph>eglCreateWindowSurface()</codeph> along with an <codeph>EGLConfig</codeph> that
has the <codeph>EGL_WINDOW_BIT</codeph> set. </p> <codeblock id="GUID-3CB64FD0-2D1C-5983-B885-AFE210612220" xml:space="preserve">// Create a window surface to draw to.
winSurface = eglCreateWindowSurface(display, chosenConfig, &amp;iWindow, NULL);</codeblock> </li>
<li id="GUID-3C5CE6E3-753E-4C9C-860E-0F1B8908349E"><p>Set the surface attribute <codeph>EGL_SWAP_BEHAVIOR
to EGL_BUFFER_PRESERVED</codeph>. This step is only required if you want to
enable the preserve buffer option.</p><codeblock xml:space="preserve">EGLBoolean queryResult = eglSurfaceAttrib(display, winSurface, EGL_SWAP_BEHAVIOR, EGL_BUFFER_PRESERVED);</codeblock></li>
<li id="GUID-C4B3E5FA-E0BF-5923-AB10-32BE18BD3B59"><p>To create a rendering
context for the current rendering API, call the <codeph>eglCreateContext()</codeph> with
the <codeph>share_context</codeph> parameter set to <codeph>EGL_NO_CONTEXT</codeph>.
If this method succeeds, it initializes the context to the initial state defined
for the current rendering API, and returns a handle to it. </p> <codeblock id="GUID-9DB529FE-3DFB-5E8F-9B83-89E3EB17C4FF" xml:space="preserve">// Create a context to store the current rendering API settings.
contextGL = eglCreateContext(display, chosenConfig, EGL_NO_CONTEXT, NULL);</codeblock> </li>
<li id="GUID-A5A3E17B-CB73-53E6-AFA3-3098F96B0AE7"><p>In order to allow the
context to render to a given surface, you need to call <codeph>eglMakeCurrent()</codeph>.
After doing this you can call EGL client functions, which need a current surface
and context. </p> <codeblock id="GUID-DF027C4F-D0A5-5B2D-A1E9-2910D0D1E77C" xml:space="preserve">// Make the context current on the surface and the display
eglMakeCurrent(display, winSurface, winSurface, contextGL); 
</codeblock> </li>
<li id="GUID-2F5A701F-8D0C-5C11-9DAD-297FE8D01888"><p>You are now ready to
perform your OpenGL ES drawing commands. </p> <p>The main thing to understand
is that the EGL window surface is double-buffered. This means that the drawing
commands are drawn into a back buffer and you need to call <codeph>eglSwapBuffers()</codeph> in
order to make the drawing appear on the screen in the window. This mechanism
has the advantage that it stops flicker. </p> <codeblock id="GUID-C5190E0A-7B93-5041-9CC0-6DDF7519571B" xml:space="preserve">eglSwapBuffers(display, winSurface);</codeblock><p>Because you enabled the preserve buffer option in step 5, the <codeph>eglSwapBuffers()</codeph> promotes
the back buffer to the front for display as usual, and also copies the content
to the new back buffer. This means the client application can provide incremental
drawing commands instead of creating the entire new scene.</p></li>
<li id="GUID-3944687A-E53A-503F-8CCC-7B0C11698341"><p>To release the current
context and surface without assigning a new one, set the context parameter
to <codeph>EGL_NO_CONTEXT</codeph> and set the draw and read surfaces to <codeph>EGL_NO_SURFACE</codeph>.
This flushes the current context for the current rendering API and marks it
as no longer current. The current rendering API does not have a current context
after <codeph>eglMakeCurrent()</codeph> returns. </p> <codeblock id="GUID-5AB57D6A-DC82-5092-8F81-8E9A61939988" xml:space="preserve">eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);</codeblock> </li>
<li id="GUID-F1D7FCF5-8DB3-5C9F-A5F3-89AD110ED3BB"><p>You destroy the rendering
context by calling <codeph>eglDestroyContext()</codeph>. All resources associated
with the context are marked for deletion as soon as possible. If the context
is current to any thread, resources are not actually released while the context
remains current. </p> <codeblock id="GUID-45F64C22-608E-57D7-B607-1D04FD20F0F3" xml:space="preserve">eglDestroyContext(display, contextGL); 
</codeblock> </li>
<li id="GUID-139B4B87-5B83-57ED-A5A0-001475450D2B"><p>You destroy the <codeph>EGLSurface</codeph> by
calling <codeph>eglDestroySurface()</codeph>. All resources associated with
the surface are marked for deletion as soon as possible. If the surface is
current to any thread, the resources are not actually released while the surface
remains current. </p> <codeblock id="GUID-D9E034F1-F6F5-5C8A-A5D5-D34CCE813340" xml:space="preserve">eglDestroySurface(display, winSurface); 
</codeblock> </li>
<li id="GUID-EFEF57E1-49CC-5689-8A90-2208CC62322E"><p>Perform final cleanup
by first terminating the <codeph>EGLDisplay</codeph> using <codeph>eglTerminate()</codeph> and
then releasing any resources still held by EGL by calling <codeph>eglReleaseThread()</codeph>. </p> <codeblock id="GUID-DB4DB0EF-B8B3-516E-9641-CC412C2F221B" xml:space="preserve">eglTerminate(display);
eglReleaseThread();</codeblock> </li>
</ol> </section>
</conbody><related-links>
<link href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita"><linktext>EGL Interface
Overview</linktext></link>
<link href="GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita"><linktext>Symbian-Specific
Behavior</linktext></link>
</related-links></concept>