<?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-894AB487-C127-532D-852B-37CB0DEA1440" xml:lang="en"><title>Symbian-Specific Behavior</title><shortdesc>This topic provides information about the points that the

EGL specification explicitly states are platform-specific. This information

is aimed at both users and implementers of EGL on the Symbian platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-E6A596AC-1BCE-4B99-89CF-67EE28A45068"><title>ScreenPlay

(NGA)</title><p>Applications can find out whether ScreenPlay (also

known as the New Graphics Architecture or NGA) is supported on the

device at runtime.  </p><p>To do this, call <codeph>eglQueryString(display,

EGL_EXTENSIONS)</codeph> and search for the string <codeph>EGL_SYMBIAN_COMPOSITION</codeph> within the string returned. If <codeph>EGL_SYMBIAN_COMPOSITION</codeph> is present, it means that ScreenPlay is supported. For further information,

see <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita">EGL Functions

with Symbian-Specific Behavior</xref>.</p><p>By checking for the presence

of the <codeph>EGL_SYMBIAN_COMPOSITION</codeph> string, you can create

applications that can work on both ScreenPlay devices and those with

the non-ScreenPlay architecture.</p></section>

<section id="GUID-5F4317DF-EEDE-434C-906D-A354367AE38D"><title>Symbian

windows</title> <p>EGL window surfaces are on-screen rendering surfaces

that are tied to Symbian windows. The <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> class

is a client-side handle to a Symbian Window Server window. You must

create the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> before creating the EGL window

surface for on-screen rendering.</p><p>Because the EGL window surface

is implemented differently depending on whether ScreenPlay is in use,

there are some differences in how you create an EGL window surface:</p><ul>

<li><p>In ScreenPlay, the pixel format of the EGL window surface is

determined entirely by the EGL config passed to <codeph>eglCreateWindowSurface()</codeph> and not by the properties of the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>.</p></li>

<li><p>On a non-ScreenPlay device, the display mode of the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> must match the buffer size of the EGL window surface.

You can call <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-FE6998EA-7B17-3270-B487-04D98EBB8424"><apiname>RWindowBase::DisplayMode() const</apiname></xref> to

retrieve the window’s display mode and use it to determine the buffer

size when retrieving the EGL config to pass to <codeph>eglCreateWindowSurface()</codeph>. </p></li>

</ul> <p><b>Threading</b>. Because of the limitations of the Window

Server API, clients <b>must</b> create and use an EGL window surface

in the thread in which its <codeph>RWindow</codeph> was created. This

means that the following are <b>not</b> supported and will lead to

undefined behavior:</p><ul>

<li><p>Creating an EGL window surface in thread <i>B</i> using an <codeph>RWindow</codeph> that was created in thread <i>A</i>. </p></li>

<li><p>Using an EGL window surface in thread <i>B</i> when that EGL

window surface and its <codeph>RWindow</codeph> were created in thread <i>A</i>. </p></li>

</ul><p>For example, in the second scenario, EGL in thread <i>B</i> will fail (with a WSERV panic) when it attempts to get the window

size from the <codeph>RWindow</codeph> in thread <i>A</i>.</p><p><b>Buffer handling</b>. By default EGL window surfaces have multiple

buffers, which means that the client can draw to a back buffer, while

the front buffer is being composed to the screen. The client must

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

the screen.</p><p> EGL 1.4 introduces a preserve buffer feature, which

enables the content of the front buffer to be preserved from one frame

to the next. This means that the client can provide incremental drawing

operations rather than the entire drawing operations for each frame.

This feature is usually off by default. This means that legacy applications

that do not expect this feature are not slowed down by the unnecessary

copying of the buffer contents.</p> <p><b>Window resizing</b>. The

size of an application’s view can be changed by a variety of external

events, such as a UI layout switch, a change in the size of the status

pane or the rotation of the screen.  An application can also resize

a window directly, such as through a call to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-BCD76117-54A3-3CD5-8911-E867512BF85B"><apiname>RWindow::SetExtent()</apiname></xref>, <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-B680C675-2146-3162-AAAC-F3E88FA8B045"><apiname>CCoeControl::SetExtent()</apiname></xref> or <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-5A63E1BD-BCCA-356E-BB39-D4BB7B6DC22E"><apiname>CCoeControl::SetExtentToWholeScreen()</apiname></xref>.</p><p>When there is a change in the size of a window that is bound

to an EGL window surface, the application must take appropriate action

in its <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-FFF07CE8-61C4-34F9-B9E9-D315782C8476"><apiname>CCoeControl::SizeChanged(</apiname></xref>) or <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-1BC64D91-2796-3F16-AA41-13836BC00701"><apiname>CCoeControl::HandleResourceChange()</apiname></xref> implementation. The action depends on the nature of the application

but might include clipping or scaling the contents to fit the resized

window.</p><p>On the Symbian platform, EGL handles the window resize

in the next call to <codeph>eglSwapBuffers()</codeph>, which resizes

the surface to match the new window size. If the preserve buffer option

is in use, this function also copies across all the pixels from the

old surface that overlap the new surface, although the exact details

depend on the implementation.</p><p>If the surface resize fails, <codeph>eglSwapBuffers()</codeph> returns <codeph>EGL_FALSE</codeph> and

an <codeph>EGL_BAD_ALLOC</codeph> error is raised. This may mean that

the implementation does not support the resizing of a surface or that

there is not enough memory available (on a platform with GPU, this

would be GPU rather than system memory). Applications must always

monitor whether <xref href="GUID-7F4F23A8-26FA-33E5-87DA-4EE1D3DC65AE.dita"><apiname>eglSwapBuffers()</apiname></xref> fails after a

window resize. When it does fail, the application should do the following:</p><ol>

<li id="GUID-81762FDD-72AD-410E-8E18-FFFF75CF6A32"><p>Call <codeph>eglDestroySurface()</codeph> to destroy the current EGL window surface.</p></li>

<li id="GUID-79FFA30C-1F31-47C0-9084-F72FF0E57FC6"><p>Call <codeph>eglCreateWindowSurface()</codeph> to recreate the EGL window surface.</p></li>

</ol> <p>This may cause a noticeable flicker and so should be done

only when necessary.</p><p> <b>Screen rotation</b>. There is no specific

EGL handling for screen rotation—instead screen rotation is handled

in the same way as a change of screen resolution. An application typically

handles changes in screen resolution and rotation in its <xref href="GUID-3AC2CDAC-0291-309F-A020-049BC9F2CF90.dita#GUID-3AC2CDAC-0291-309F-A020-049BC9F2CF90/GUID-5723655E-FC84-35F1-A0E1-FCE92CEBC196"><apiname>CCoeAppUi::HandleScreenDeviceChangedL()</apiname></xref> or <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-A925DD23-4531-3BA5-AF17-E6289F9E370A"><apiname>CCoeControl::HandleResourceChange(TInt)</apiname></xref> implementation. When there is a change in screen rotation, the application

may need to resize its windows and update the content accordingly. </p> <p>The EGL implementation updates the surface size on the next call

to <codeph>eglSwapBuffers()</codeph>.  However, the interim frames

appear in the new orientation, and so an application may want to adjust

the contents to minimize flicker. If the application wants to accept

the system rotation, it does not need to rotate its content. However,

some applications may require a fixed physical orientation. These

need to rotate the window content in order to counteract the physical

rotation. </p><p>Sometimes a screen rotation simply results in the

swapping of the window’s width and height dimensions—for example,

when the application is running in full screen mode and the device

is rotated from portrait to landscape or vice versa. This is guaranteed

to succeed on all Symbian EGL implementations.</p><p>In other situations

the screen rotation must be treated like a window resize and the application

must monitor whether <codeph>eglSwapBuffers()</codeph> succeeds and

take appropriate action if it fails, as described above. For example,

if the application is not in full screen mode, rotating the device

from portrait to landscape may not result in the swapping of the width

and height of the window.</p> <p><b>UI content</b>. Applications that

want to make use of the ScreenPlay ability to place semi-transparent <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering above the EGL window surface should

check whether ScreenPlay is supported on the device as described above. </p><p>On ScreenPlay devices, you can combine <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing and OpenVG/OpenGL ES drawing in the same window, provided

the <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> content is drawn using a semi-transparent

pen or brush color or bitmap. It is also possible to create semi-transparent <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing in another Symbian window placed over

the EGL window. To do this, make the Symbian window semi-transparent

by calling <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-47275C08-0C58-3A03-B96F-38F881F49C08"><apiname>RWindow::SetTransparencyAlphaChannel()</apiname></xref>. <xref href="GUID-02BD38E7-A579-5BD5-9444-4E7C14C7809A.dita">Transparent

Windows</xref> has more detail on implementing semi-transparent windows.</p><p>On non-ScreenPlay devices, you need to place the <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> drawing in an opaque child window over the EGL window surface or

implement the UI by using OpenVG/OpenGL ES drawing that is directed

to the EGL window surface itself.</p><p><b>Window lifetime</b>. Clients

must maintain the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> associated with the EGL

window surface for the lifetime of that window surface, provided they

follow the good practice guidelines of unbinding the EGL window surface

from the current context before destroying it. If these guidelines

are not followed, it may be necessary to maintain the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> for the entire duration of EGL usage within the client application.</p><p>For example,  the following pseudocode demonstrates good practice.

The <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> must be valid until <codeph>eglDestroySurface()</codeph> is called:</p><codeblock xml:space="preserve">// Unbind the window surface from the current context.

eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);

// Destroy the window surface.

eglDestroySurface(display, surface);

...

eglTerminate(display)</codeblock><p>When the application does not

follow this good practice and destroys the surface before unbinding

it from the current context, the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> must be

valid for longer. For example in the following pseudocode, <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> must be valid until after <codeph>eglMakeCurrent()</codeph> is called:</p><codeblock xml:space="preserve">eglDestroySurface(display, surface);

eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);

...

eglTerminate(display)</codeblock><p>If <xref href="GUID-2095B4FC-106B-3839-9EE1-9F6B5E8C47B6.dita"><apiname>eglMakeCurrent(</apiname></xref>) is not called with a null surface and null context at all, the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> must be valid until <codeph>eglTerminate()</codeph> is called.</p> </section>

<section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian

pixmap types</title> <p>An EGL implementation can support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer as an <codeph>EGLNativePixmapType</codeph>. This means that it is possible to create an <codeph>EGLSurface</codeph> to render to a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref>. However, it is not

guaranteed to be supported on all EGL implementations.</p> </section>

<section id="GUID-44553B50-C48E-4E6B-AD9C-F3BC7D9D5347"><title>Display

handling</title> <p>Most EGL calls include an <codeph>EGLDisplay</codeph> parameter. The EGL specification describes this as "the abstract

display on which graphics are drawn". On some systems, this corresponds

to a physical screen. However, the details are platform specific and

on Symbian systems, it does <i>not</i> correspond to a physical screen.

When working on the Symbian platform, it is generally more useful

to think of an <codeph>EGLDisplay</codeph> as the EGL session. </p> <p>On Symbian systems, you usually use a single <codeph>EGLDisplay</codeph>. You get this by a call to <codeph>eglGetDisplay()</codeph> and

passing <codeph>EGL_DEFAULT_DISPLAY</codeph> as the <codeph>&lt;display

id&gt;</codeph> parameter. </p> <p>The physical screen on which the content

is displayed is determined by the window's parent window group. In

Symbian, every window (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>) has a parent window

group (<xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>), as shown in the following

diagram. When you create a window group, you can specify the screen

on which it is to be shown. </p> <fig id="GUID-5D5F3C6A-4CFA-5307-8B2D-D2881799D664">

<title>Each window has a parent window group which is associated with

a screen</title>

<image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e206241_href.png" placement="inline"/>

</fig> <p>When you create a window surface in EGL using <codeph>eglCreateWindowSurface</codeph>, you pass in the <codeph>RWindow</codeph> as an argument. The window

surface is then displayed on the screen associated with that window's

parent window group. Currently a window can exist on only one screen. </p> </section>

</conbody><related-links>

<link href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita"><linktext>EGL

Interface Component</linktext></link>

<link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL

Collection Overview</linktext></link>

<link href="GUID-53707903-9A88-409B-80F8-FDF7EF47ACBF.dita"><linktext>Coverflow:

using ScreenPlay</linktext></link>

<link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Drawing

with CWindowGc</linktext></link>