<?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-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6" xml:lang="en"><title>EGL Collection

Overview</title><shortdesc>EGL is an interface between EGL client APIs (such as OpenGL ES

and OpenVG) and an underlying native platform window system. EGL is independent

of definitions and concepts specific to any native window system or rendering

API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>EGL is an open standard developed by the Khronos Group, which is a member-funded

industry consortium. Khronos creates open standard, royalty-free APIs to help

write and execute dynamic media on a wide variety of platforms and devices.

For more information about EGL operations, functions, errors, versions and

header files, see <xref href="http://www.khronos.org/egl/" scope="external">http://www.khronos.org/egl/</xref>. </p>

<p>In this documentation the term <b>EGL client API</b> is used to mean a

rendering API, such as OpenGL ES or OpenVG, that is a client of EGL. </p>

<section id="GUID-D214F4FF-FB17-4427-A301-B4ADE03DE261"><title>Introduction

to EGL on the Symbian platform</title> <p>EGL provides: </p> <ul>

<li id="GUID-DEBBBE4F-8B61-58EF-A4FE-CFC3C63B0223"><p>Mechanisms that create

rendering surfaces onto which EGL client APIs can draw and which they can

share. </p> </li>

<li id="GUID-1D0D4366-D8B7-50B1-9D5B-1C7BFAC11C94"><p>Methods that create

and manage graphics contexts for EGL client APIs. </p> </li>

<li id="GUID-67AC4C95-E548-5275-A151-13AE9F4AFFCB"><p>Methods that synchronize

drawing by EGL client APIs and Symbian APIs (such as <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>). </p> </li>

</ul> <p>One of the purposes of EGL is to provide a means to create EGL client

API rendering contexts, and associate them with drawing surfaces. EGL defines

three types of drawing surfaces collectively referred to as <codeph>EGLSurfaces</codeph>.

These are: </p> <ul>

<li id="GUID-21914FD1-9A21-536D-AD5B-09CC15B70ADA"><p> <b>Window surfaces</b>,

which are used for on-screen rendering into windows that are provided by the

Symbian platform (rather than EGL) .</p> </li>

<li id="GUID-230C6E2A-FC78-57C4-8F58-DDB8684D2385"><p> <b>Pbuffer surfaces</b>,

which are used for off screen rendering and are entirely provided by EGL. </p> </li>

<li id="GUID-76001CBC-8E7C-552A-AAC2-76E159FB0FF4"><p> <b>Pixmap surfaces</b>,

which are used for off screen rendering into pixmap buffers that are provided

by the Symbian platform (rather than EGL). </p> </li>

</ul> <p>Some key points to note include: </p> <ul>

<li id="GUID-6CD11A9A-FF10-5939-9C38-F443397DDD01"><p>EGL objects and their

related context state cannot be used outside of the address space in which

they are created. </p> </li>

<li id="GUID-E8A666F7-1B08-5F18-B117-29B6E35D31C0"><p>EGL enables sharing

of certain types of context state among contexts existing in a single address

space. </p> </li>

</ul> <p><b>Thread-safety </b> </p> <p>Currently EGL and its client APIs are

only guaranteed to work correctly on the Symbian platform when they are within

a single thread. EGL guarantees sequential ordering within a command stream

for each of the EGL client APIs. However, there is no guarantee of sequential

ordering between EGL client APIs and Symbian APIs which render into the same

surface. </p> <p>EGL client API commands may be asynchronous, in order to

prevent impairing the interactive use of the windowing system by the user.

For example, otherwise rendering a large texture mapped polygon on a system

with no graphics hardware, or drawing a large OpenGL ES vertex array, could

prevent a user from invoking a menu soon enough to be usable. </p> <p>Synchronization

depends on the client—it can be maintained at moderate cost with the careful

use of commands such as <codeph>glFinish</codeph>, <codeph>vgFinish</codeph>, <codeph>eglWaitClient</codeph>,

and <codeph>eglWaitNative</codeph>, as well as synchronization commands present

in the Symbian APIs. The EGL client API and Symbian API rendering can be done

in parallel if the client does not prevent it with explicit synchronization

calls. Some performance degradation may be experienced when there is unnecessary

switching between EGL client APIs and Symbian API rendering. </p> </section>

<section id="GUID-483A8427-D740-477D-9357-957C755E053D"><title>Architectural

relationships</title> <p>The following diagram shows the key EGL relationships

and dependencies within the Symbian platform. On the Symbian platform, OpenGL

ES, OpenVG and EGL all have a component (shown in blue) that declares the

interface, and all require an implementation that implements that interface

(shown in green). </p> <fig id="GUID-BF9F0E84-F1DA-5D9D-9D4B-14AA55C7DA07">

<title>              Key EGL relationships and dependencies            </title>

<image href="GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e205483_href.png" placement="inline"/>

</fig> <p>The <xref href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita">EGL Interface

component</xref> provides a consistent interface to EGL on the Symbian platform,

enabling cross-device compatibility. The component includes the Khronos-released

header files (which incorporate some minor changes, such as to the comments).

It also provides some Symbian-specific header files and some other files (such

as LIB, DEF and MMP files) and UIDs. It does not provide any implementations

of the APIs. </p> <p>Symbian^3 introduces <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>,

the new graphics architecture. This has a composition engine, which enables

composition surfaces to be arranged in layers and to be composed together

to produce the final output on the display. All native Symbian drawing (such

as the application UI) is rendered to a special composition surface called

the UI surface, which is the topmost layer and can be semi-transparent. </p> <p>In

a ScreenPlay environment, EGL window surfaces are implemented as composition

surfaces. This means that it is possible to use the native Symbian drawing

APIs (<codeph>CWindowGc</codeph>) to create semi-transparent UI content over

the EGL window surface onto which the OpenVG and OpenGL ES content is rendered.

 See the <xref href="GUID-53707903-9A88-409B-80F8-FDF7EF47ACBF.dita">Coverflow;

using ScreenPlay</xref> application for an example of this.</p> <p>In the

non-ScreenPlay environment, it is not possible to use the native Symbian APIs

to create semi-transparent UI content over the EGL window surface. A different

solution must therefore be used; for example, using Khronos rendering APIs

to create the UI content and direct it onto the EGL window surface or using

the Symbian APIs to create opaque child windows.</p> <p>The EGL Interface

component includes the header files for EGL 1.2, 1.3 and 1.4 (which is used

by default). The main advantage of EGL 1.4 over previous versions is the introduction

of a <b>preserve buffer</b> flag. When supported by the implementation, an

EGL window surface can have its color buffer preserved from one frame to the

next. This means that the client does not need to send the entire drawing

instructions for each frame. Instead the client can simply send the drawing

operations for what changes in each frame compared to the previous one. This

can reduce the memory footprint and the CPU overhead when an EGL client API

renders successive frames. </p> </section>

</conbody><related-links>

<link href="GUID-8C6D4350-A38D-57A1-8C8D-C777EA7E8A3E.dita"><linktext>EGL     

           Collection</linktext></link>

<link href="GUID-1B1C6D35-FFDF-55B3-BCE2-DD0295858E49.dita"><linktext>OpenVG Collection</linktext>

</link>

<link href="GUID-AB93B01C-B6C2-5B24-ADEF-95706584D625.dita"><linktext>OpenGLES

Collection</linktext></link>

<link href="GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita"><linktext>Graphics

Composition</linktext></link>