<?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-5F4317DF-EEDE-434C-906D-A354367AE38D"><title>Symbian windows</title> <p>EGL

window surfaces are tied to Symbian windows. To create an on-screen rendering

surface, a Window Server window with attributes corresponding to the desired <codeph>EGLConfig</codeph> must

be created first. The <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> class is a handle to a server-side

window that can be displayed and drawn to, and whose redraws are performed

by the application. </p> <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> may fail

when it attempts to get the window size from the <codeph>RWindow</codeph> in

thread <i>A</i>.</p><p><b>Buffer handling</b>. EGL window surfaces have two

buffers, known as the front and back buffers. This means that the client application

can draw to the 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.

When this is supported by the implementation, the content of the buffer can

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. When the implementation supports this feature, it 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>. A window can be resized using one

of the Window Server or UI Framework APIs, such as <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> or <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>.

When these APIs are called on a window that is bound to an EGL window surface,

the EGL implementation is expected to handle the situation by adjusting its

internal buffers. Applications need not do anything specific with regard to

EGL APIs. Depending on the type of application, APIs may want to adjust their

rendering operations—for example, clip or scale the contents. </p> <p>EGL

handles the resize in the next call to <codeph>eglSwapBuffers()</codeph> by

creating a new surface for the resized window. 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.

A client application may therefore need to provide extra drawing operations,

for example, if the window is made larger.</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. Applications

can detect screen rotation by listening to the Window Server event <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>.

However, applications do not normally use the Window Server API directly,

because they are built on top of the UI Framework layer. This layer provides

a different mechanism to notify applications using—for example, <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>. </p> <p>When

one of the these events is detected, the application may need to resize its

windows and update its content accordingly. If the application wants to accept

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

applications may want to maintain a fixed physical orientation. They would

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

rotation. </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>. </p> <p> <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> bitmaps

are managed by the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font

and Bitmap Server</xref>. The format is internal to Symbian, but the Image

Converter API can be used to convert them to standard formats. The <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> type

has limitations with regard to hardware acceleration. </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_d0e271870_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>