<?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-42984078-3DEB-41C7-AC76-C769F7CDB4D0" xml:lang="en"><title>Implementing eglSwapBuffers</title><shortdesc>This topic explains how to implement eglSwapBuffers() on

the Symbian platform. It provides information about how to handle

a window resize and the preserve buffer option.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-FDE82C6A-6F55-437E-B978-C912D41080D2">       <title>Promoting buffers to the screen </title>  

    <p>EGL composition surfaces typically have two or more buffers,

known as the front and back buffers. Call <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref> to initiate the composing of a specified buffer of a composition

surface to the screen. This is an asynchronous operation. If you want

to be notified when it has finished, call <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-E8A784F8-4733-38D0-B282-B7CBD0AE4DCB"><apiname>RSurfaceUpdateSession::NotifyWhenAvailable()</apiname></xref> immediately before you call <codeph>SubmitUpdate()</codeph>. </p> <p> <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-E8A784F8-4733-38D0-B282-B7CBD0AE4DCB"><apiname>RSurfaceUpdateSession::NotifyWhenAvailable()</apiname></xref> takes a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref>, which you can wait on

in the usual way—for example, by using an active object or <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-50223158-D05D-33FE-A3DD-FFA9E2F464FF"><apiname>User::WaitForRequest()</apiname></xref>. </p> <p>If a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> is waiting for the first buffer to complete composition, you need

to submit the second buffer before the first buffer's <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> is signaled (unless there is an error). This means that there is

interleaving between the two buffers. </p>     </section>

<section id="GUID-10CF8F2D-2D57-4A57-B370-3B56DDEF76B9">       <title>Synchronization and threads </title>       <p>First let us consider a scenario that illustrates how <codeph>eglSwapBuffers()</codeph> works. The composition surface has two buffers. The

front buffer (<i>Buffer 0</i>) is in the process of being displayed

and the back buffer (<i>Buffer 1</i>) is receiving drawing commands

for the next animation frame. The client calls <codeph>eglSwapBuffers()</codeph> when all of the drawing commands for the next frame have been issued. </p> <p> <codeph>eglSwapBuffers()</codeph> can promote <i>Buffer 1</i> to the screen by calling <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref>, passing in its index. This makes <i>Buffer 1</i> the front buffer

and <i>Buffer 0</i> should become the new back buffer and all drawing

commands should be directed to it. </p> <p>However, suppose the application

runs faster than the composition engine. <i>Buffer 0</i> cannot become

the new back buffer until its composition is complete. You therefore

need to wait for <i>Buffer 0</i> to complete composition before allowing <codeph>eglSwapBuffers()</codeph> to return. This means that after you submit <i>Buffer 1</i> for composition, you must wait for <i>Buffer 0</i> (not <i>Buffer 1</i>) to complete composition before returning. </p> <p>In

practice it may not be possible to use active objects to do the waiting

because <codeph>eglSwapBuffers()</codeph> must block on the <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> supplied to <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref>. Using a nested <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> is not recommended

because it can cause re-entrant issues. A call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-50223158-D05D-33FE-A3DD-FFA9E2F464FF"><apiname>User::WaitForRequest()</apiname></xref> may therefore be required. However, doing this from within a thread

that has an active scheduler can cause stray signal panics (because

each buffer has a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> but we only wait

for one of these at a time). EGL has no control over whether the thread

has an active scheduler because the thread is owned by the application. </p> <p>A possible solution is to create a separate worker thread that

is owned by the EGL implementation and has no active scheduler. This

thread calls <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-E8A784F8-4733-38D0-B282-B7CBD0AE4DCB"><apiname>RSurfaceUpdateSession::NotifyWhenAvailable()</apiname></xref> and <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref>. It

can safely call <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-50223158-D05D-33FE-A3DD-FFA9E2F464FF"><apiname>User::WaitForRequest()</apiname></xref> to wait

for each <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> to be signaled, because

the thread is guaranteed not to have an active scheduler. Signaling

based on semaphores can be used to control interaction between the

thread that calls <codeph>eglSwapBuffers()</codeph> and the worker

thread that owns the <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref>. </p>     </section>

<section id="GUID-4EF4D8B4-27E5-4D9B-8D22-B6F8C354D6D5">       <title>Handling a window resize event </title>   

   <p>A change in the size of an <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> can be

detected in <codeph>eglSwapBuffers()</codeph>, by calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-2E019F5A-6110-3940-B088-AB13F0EE6AD5"><apiname>RWindow::Size()</apiname></xref> and comparing the result with the previously

recorded size. If the values differ, a resize has occurred. A typical

approach on a resize is as follows (and is illustrated in the following

diagram): </p> <ol id="GUID-529E2F6E-21A1-5618-920C-231CA3FCD2AB">

<li id="GUID-FA1DF0D4-DE06-56AA-8203-1EB42351D2DE"><p>Promote the

current back buffer to the front buffer for display as usual. </p> </li>

<li id="GUID-D254B182-2BC6-5BDF-A76E-CE2FD4527BB1"><p>Create a new

composition surface with the new dimensions and with one of its buffers

designated as the back buffer to receive the next set of drawing commands. </p> </li>

<li id="GUID-DA7BB534-9565-5127-8B40-CA150E90D710"><p>On the next

call to <codeph>eglSwapBuffers()</codeph>, register the new composition

surface as the window's background surface and promote its back buffer

to the front buffer for display. (This step is marked with the number

3 in the following diagram) </p> </li>

<li id="GUID-4209FD9D-C668-5902-863C-DB49343ED634"><p>Close the previous

composition surface. </p> </li>

</ol> <fig id="GUID-B793BDDF-7607-5BCD-94C2-44F8349D7BC5">

<title>The buffers in the typical approach to handling a window resize

event</title>

<image href="GUID-ADC9B349-3CE4-5017-B437-A7F8890C7F0F_d0e271514_href.png" placement="inline"/>

</fig>    </section>

<section id="GUID-CF08037B-2A6A-4B79-9766-E8C730C086F3">       <title>Handling preserve buffers </title>       <p>When the preserve buffer

option is in use, a typical implementation promotes the current back

buffer to the front buffer for display as usual, and copies the back

buffer content to the new back buffer. The client application then

provides incremental drawing operations on the new back buffer. On

the next call to <codeph>eglSwapBuffers()</codeph>, the back buffer

is again promoted for display and the content is preserved. </p><p>The following diagram shows the scenario of a client application

drawing A and later B on a surface with the preserve buffers enabled.

Notice that <codeph>eglSwapBuffers()</codeph> promotes the back buffer

to the front buffer and then immediately copies the contents of the

newly promoted buffer to the new back buffer.</p><fig id="GUID-B9C43452-0627-41FA-A68A-4C9726194A60">

<title>Handling preserve buffers</title>

<image href="GUID-9C54DAFB-843B-41A7-8E54-9B2A39F46527_d0e271538_href.png" placement="inline"/>

</fig>    </section>

<section id="GUID-F357C440-7789-4439-ABBB-8B71FCCB782D"><title>Handling a window resize event with the preserve buffer

option</title><p>If there is a window resize event when the preserve

buffer option is in use, <codeph>eglSwapBuffers()</codeph> creates

a new surface and typically copies into it any pixels that overlap

the previous surface. To illustrate how this works, consider the following

scenario:</p><ol>

<li id="GUID-167D0FD8-22E7-495D-9627-FF7A4DDF654A"><p>A window is

a wide rectangle showing an A.</p></li>

<li id="GUID-3F62A9F4-6830-4010-9327-88BFD33AA818"><p>The application

draws a B so that the window shows AB. </p></li>

<li id="GUID-D8575A54-D2A9-4FDF-999E-E711363AE19D"><p>The user resizes

the window to a tall thin rectangle which can only show A.</p></li>

<li id="GUID-89A1D882-B5DC-4093-98E5-34E3063BBF25"><p>After calling <codeph>eglSwapBuffers()</codeph>, the application draws a C below the A.</p></li>

</ol><p>The following diagram illustrates a typical implementation.

There are more details below the diagram.</p><fig id="GUID-D19DF371-8640-4A2B-AF56-57EF2387CEFD">

<title>Handling a window resize with the preserve buffer option</title>

<image href="GUID-8A8FA00B-58FA-4D4E-A018-70D5558BCBFE_d0e271578_href.png" placement="inline"/>

</fig><p>The first <codeph>eglSwapBuffers()</codeph> call (marked

X in the diagram above) does the following:</p><ol>

<li id="GUID-70603721-5603-4015-B382-8D3F9D693139"><p>Promotes the

current back buffer (showing AB) to the front buffer for display as

usual. </p></li>

<li id="GUID-7040357F-1F40-4E34-ACB2-170815B06D10"><p>Copies the back

buffer content to the new back buffer (showing AB).</p></li>

<li id="GUID-5950B197-5661-44B5-AB7A-475C056F184C"><p>Creates a new

surface  with the new dimensions.</p></li>

<li id="GUID-90909C1D-7335-41BF-973F-B2F82403CF40"><p>Designates one

of the new buffers as the back buffer and copies the overlapping pixels

into it. The new back buffer is then ready to receive new drawing

operations. </p></li>

</ol><p>The Window Server continues to use the old surface s1 until

the next call to <codeph>eglSwapBuffers()</codeph>.</p><p>The second <codeph>eglSwapBuffers()</codeph> call (marked Y in the diagram above) does

the following:</p><ol>

<li id="GUID-05E4F40D-568A-425A-93F8-C30606C50DA8"><p>Promotes the

back buffer (showing A and C) to the front buffer for display as usual.</p></li>

<li id="GUID-84200E5B-CD20-4F4A-8D9D-0460B30D40CA"><p>Copies the back

buffer content to the new back buffer (showing A and C).</p></li>

<li id="GUID-D300A85C-88C3-499A-86A7-EC2B35020E0C"><p>Destroys the

old surface s1.</p></li>

</ol><p>The Window Server now uses the new surface s2.</p></section>

</conbody><related-links>

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

Surface Implementation Overview</linktext></link>

<link href="GUID-599C9890-3AC8-46D3-A8C3-34CAAB5A61CF.dita"><linktext>Implementing

eglCreateWindowSurface</linktext></link>