|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6" xml:lang="en"><title>EGL |
|
13 Collection Overview</title><shortdesc>EGL is an interface between EGL client APIs (such as OpenGL ES |
|
14 and OpenVG) and an underlying native platform window system. EGL is independent |
|
15 of definitions and concepts specific to any native window system or rendering |
|
16 API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p>EGL is an open standard developed by the Khronos Group, which is a member-funded |
|
18 industry consortium. Khronos creates open standard, royalty-free APIs to help |
|
19 write and execute dynamic media on a wide variety of platforms and devices. |
|
20 For more information about EGL operations, functions, errors, versions and |
|
21 header files, see <xref href="http://www.khronos.org/egl/" scope="external">http://www.khronos.org/egl/</xref>. </p> |
|
22 <p>In this documentation the term <b>EGL client API</b> is used to mean a |
|
23 rendering API, such as OpenGL ES or OpenVG, that is a client of EGL. </p> |
|
24 <section id="GUID-D214F4FF-FB17-4427-A301-B4ADE03DE261"><title>Introduction to EGL on the Symbian platform</title> <p>EGL |
|
25 provides: </p> <ul> |
|
26 <li id="GUID-DEBBBE4F-8B61-58EF-A4FE-CFC3C63B0223"><p>Mechanisms that create |
|
27 rendering surfaces onto which EGL client APIs can draw and which they can |
|
28 share. </p> </li> |
|
29 <li id="GUID-1D0D4366-D8B7-50B1-9D5B-1C7BFAC11C94"><p>Methods that create |
|
30 and manage graphics contexts for EGL client APIs. </p> </li> |
|
31 <li id="GUID-67AC4C95-E548-5275-A151-13AE9F4AFFCB"><p>Methods that synchronize |
|
32 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> |
|
33 </ul> <p>One of the purposes of EGL is to provide a means to create EGL client |
|
34 API rendering contexts, and associate them with drawing surfaces. EGL defines |
|
35 three types of drawing surfaces collectively referred to as <codeph>EGLSurfaces</codeph>. |
|
36 These are: </p> <ul> |
|
37 <li id="GUID-21914FD1-9A21-536D-AD5B-09CC15B70ADA"><p> <b>Window surfaces</b>, |
|
38 which are used for on-screen rendering into windows that are provided by the |
|
39 Symbian platform (rather than EGL) .</p> </li> |
|
40 <li id="GUID-230C6E2A-FC78-57C4-8F58-DDB8684D2385"><p> <b>Pbuffer surfaces</b>, |
|
41 which are used for off screen rendering and are entirely provided by EGL. </p> </li> |
|
42 <li id="GUID-76001CBC-8E7C-552A-AAC2-76E159FB0FF4"><p> <b>Pixmap surfaces</b>, |
|
43 which are used for off screen rendering into pixmap buffers that are provided |
|
44 by the Symbian platform (rather than EGL). </p> </li> |
|
45 </ul> <p>Some key points to note include: </p> <ul> |
|
46 <li id="GUID-6CD11A9A-FF10-5939-9C38-F443397DDD01"><p>EGL objects and their |
|
47 related context state cannot be used outside of the address space in which |
|
48 they are created. </p> </li> |
|
49 <li id="GUID-E8A666F7-1B08-5F18-B117-29B6E35D31C0"><p>EGL enables sharing |
|
50 of certain types of context state among contexts existing in a single address |
|
51 space. </p> </li> |
|
52 </ul> <p><b>Thread-safety </b> </p> <p>Currently EGL and its client APIs are |
|
53 only guaranteed to work correctly on the Symbian platform when they are within |
|
54 a single thread. EGL guarantees sequential ordering within a command stream |
|
55 for each of the EGL client APIs. However, there is no guarantee of sequential |
|
56 ordering between EGL client APIs and Symbian APIs which render into the same |
|
57 surface. </p> <p>EGL client API commands may be asynchronous, in order to |
|
58 prevent impairing the interactive use of the windowing system by the user. |
|
59 For example, otherwise rendering a large texture mapped polygon on a system |
|
60 with no graphics hardware, or drawing a large OpenGL ES vertex array, could |
|
61 prevent a user from invoking a menu soon enough to be usable. </p> <p>Synchronization |
|
62 depends on the client—it can be maintained at moderate cost with the careful |
|
63 use of commands such as <codeph>glFinish</codeph>, <codeph>vgFinish</codeph>, <codeph>eglWaitClient</codeph>, |
|
64 and <codeph>eglWaitNative</codeph>, as well as synchronization commands present |
|
65 in the Symbian APIs. The EGL client API and Symbian API rendering can be done |
|
66 in parallel if the client does not prevent it with explicit synchronization |
|
67 calls. Some performance degradation may be experienced when there is unnecessary |
|
68 switching between EGL client APIs and Symbian API rendering. </p> </section> |
|
69 <section id="GUID-483A8427-D740-477D-9357-957C755E053D"><title>Architectural relationships</title> <p>The following diagram |
|
70 shows the key EGL relationships and dependencies within the Symbian platform. |
|
71 On the Symbian platform, OpenGL ES, OpenVG and EGL all have a component (shown |
|
72 in blue) that declares the interface, and all require an implementation that |
|
73 implements that interface (shown in green). </p> <fig id="GUID-BF9F0E84-F1DA-5D9D-9D4B-14AA55C7DA07"> |
|
74 <title> Key EGL relationships and dependencies </title> |
|
75 <image href="GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e210493_href.png" placement="inline"/> |
|
76 </fig> <p>The <xref href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita">EGL Interface |
|
77 component</xref> provides a consistent interface to EGL on the Symbian platform, |
|
78 enabling cross-device compatibility. The component includes the Khronos-released |
|
79 header files (which incorporate some minor changes, such as to the comments). |
|
80 It also provides some Symbian-specific header files and some other files (such |
|
81 as LIB, DEF and MMP files) and UIDs. It does not provide any implementations |
|
82 of the APIs. </p> <p>The EGL Interface component includes the header files |
|
83 for EGL 1.2, 1.3 and 1.4 (which is used by default). The main advantage of |
|
84 EGL 1.4 over previous versions is the introduction of a <b>preserve buffer</b> flag. |
|
85 When supported by the implementation, an EGL window surface can have its color |
|
86 buffer preserved from one frame to the next. This means that the client does |
|
87 not need to send the entire drawing instructions for each frame. Instead the |
|
88 client can simply send the drawing operations for what changes in each frame |
|
89 compared to the previous one. This can reduce the memory footprint and the |
|
90 CPU overhead when an EGL client API renders successive frames. </p> </section> |
|
91 </conbody><related-links> |
|
92 <link href="GUID-8C6D4350-A38D-57A1-8C8D-C777EA7E8A3E.dita"><linktext>EGL |
|
93 Collection</linktext></link> |
|
94 <link href="GUID-1B1C6D35-FFDF-55B3-BCE2-DD0295858E49.dita"><linktext>OpenVG Collection</linktext> |
|
95 </link> |
|
96 <link href="GUID-AB93B01C-B6C2-5B24-ADEF-95706584D625.dita"><linktext>OpenGLES |
|
97 Collection</linktext></link> |
|
98 </related-links></concept> |