<?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>       <title>Promoting buffers to the screen </title>       <p>EGL

composition surfaces have two 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>       <title>Synchronization and threads </title>       <p>First

let us consider a scenario that illustrates how <codeph>eglSwapBuffers()</codeph> works.

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>       <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_d0e246447_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_d0e246471_href.png" placement="inline"/>

</fig>    </section>

<section><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_d0e246511_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>