<?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>
</related-links></concept>