--- a/Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,98 +1,118 @@
-<?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>
+<?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>
\ No newline at end of file