--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,98 @@
+<?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><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><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_d0e181877_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>
\ No newline at end of file