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