|
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-DC3A8785-3ED3-5696-A5ED-AB66588A5C14" xml:lang="en"><title>EGL |
|
13 Porting Guide</title><shortdesc>This is a guide for implementers of EGL working with the Symbian |
|
14 platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p> <b>Target audience</b>: Device creators. </p> |
|
16 <section id="GUID-B4226103-3C9D-4E49-A447-45B057488305"><title>Required functionality </title> <p>The |
|
17 implementation DLL must implement:</p><ul> |
|
18 <li><p>All of the standard functions declared in the <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL |
|
19 Interface component</xref>.</p></li> |
|
20 <li><p>The <xref href="GUID-DEA883D0-7C53-407A-AC5D-0A3208E667C7.dita">EGL Reusable |
|
21 Sync Extension</xref> if OpenWF Composition is in use.</p></li> |
|
22 <li><p>The <xref href="GUID-8ED4E590-4FDC-4267-87D9-C7E5E57D6B7E.dita">EGL Resource |
|
23 Profiling Extension</xref> which can be used to retrieve GPU |
|
24 resource utilization information. </p></li> |
|
25 </ul><p>Any implementation-specific functions can be included in the DLL or |
|
26 placed into a separate DLL.</p> <p>Symbian implementations must use the following |
|
27 native type interpretations for compatibility. Window and pixmap types are |
|
28 actually defined as <codeph>void*</codeph> to avoid compilation problems for |
|
29 C programs. However, the native types specified must be used, because pointers |
|
30 are cast to these types within the implementation. </p> <table id="GUID-5F79DD06-1F95-5E36-B020-2141A672AE97"> |
|
31 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
32 <thead> |
|
33 <row> |
|
34 <entry>OpenGL ES type</entry> |
|
35 <entry>Native type</entry> |
|
36 <entry>Defined type</entry> |
|
37 </row> |
|
38 </thead> |
|
39 <tbody> |
|
40 <row> |
|
41 <entry><codeph>EGLNativeDisplayType</codeph> </entry> |
|
42 <entry>int </entry> |
|
43 <entry><codeph>int</codeph> </entry> |
|
44 </row> |
|
45 <row> |
|
46 <entry><codeph>EGLNativeWindowType</codeph> </entry> |
|
47 <entry><xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> <codeph>*</codeph> </entry> |
|
48 <entry><codeph>void*</codeph> </entry> |
|
49 </row> |
|
50 <row> |
|
51 |
|
52 <entry><codeph>EGLNativePixmapType</codeph> </entry> |
|
53 <entry><xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> <codeph>* </codeph> </entry> |
|
54 <entry><codeph>void* </codeph> </entry> |
|
55 </row> |
|
56 </tbody> |
|
57 </tgroup> |
|
58 </table> <p>For information about implementing window surfaces and pixmaps, |
|
59 see: </p> <ul> |
|
60 <li id="GUID-3299A027-7B6F-54B2-9E22-28F233D7F2F1"> <xref href="GUID-0B2421FD-8431-5DDA-9FE3-046734AE495E.dita">Window |
|
61 Surface Implementation</xref></li> |
|
62 <li id="GUID-05B529F5-0B80-5A41-866C-4AEA2C9769E4"> <xref href="GUID-453CFE84-B2BA-56E6-BCB2-1162432B2358.dita">Pixmap |
|
63 Implementation</xref></li> |
|
64 </ul> <p><b>Warning </b> </p> <p>Implementations of the EGL APIs must not |
|
65 open a session (<xref href="GUID-E5B29AC0-4953-385F-84C5-13EE6CB77D46.dita"><apiname>RFbsSession</apiname></xref>) with the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font |
|
66 and Bitmap Server</xref> because this can lead to a deadlock caused by the |
|
67 Font and Bitmap Server's dependence on EGL. Therefore within the implementation |
|
68 of the EGL APIs: </p> <ul> |
|
69 <li id="GUID-7BCFEA36-AAFC-5AEF-A9A7-D2B1927389AC"><p>Do not call <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-6CA684BC-746E-3357-90A0-E5105DDC4E01"><apiname>RWsSession::Connect()</apiname></xref> to |
|
70 create a session to the Window Server because this automatically creates an <xref href="GUID-E5B29AC0-4953-385F-84C5-13EE6CB77D46.dita"><apiname>RFbsSession</apiname></xref>. </p> </li> |
|
71 <li id="GUID-41A6C1CE-B87E-55CD-8EC2-A080303612A4"><p>Do not call any of the |
|
72 Font and Bitmap Server APIs except on a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object |
|
73 that has been passed into the function as an argument. </p> <p> </p> </li> |
|
74 </ul> </section> |
|
75 <section id="GUID-3EF15D30-E800-45C7-B1C5-74FD0EC7E3F0"><title>Library file</title> <p>The |
|
76 EGL implementation must not deliver the <filepath>libEGL.lib</filepath> file, |
|
77 because it is provided by the <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL |
|
78 Interface component</xref>. To prevent a LIB file being automatically generated, |
|
79 place the <codeph>NOEXPORTLIBRARY</codeph> directive in the MMP project file |
|
80 that builds the implementation DLL. </p> <p>The LIB file delivered by the <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL Interface component</xref> has |
|
81 only EGL standard functions and no implementation-specific functions. This |
|
82 is to ensure that client programs do not link to implementation-specific functions |
|
83 and so are portable across EGL implementations. </p> </section> |
|
84 <section id="GUID-46E3542D-09D6-43E8-B8B4-B6081450DB8D"><title>EGL version |
|
85 variability point</title> <p>The <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL |
|
86 Interface component</xref> provides header files for EGL 1.2, 1.3 and 1.4. |
|
87 The EGL 1.4 headers are used by default. However, there is a variability point |
|
88 that can be used to change the header version. This allows a staged migration |
|
89 from one version to the next. </p> <p>The variability point consists of adding |
|
90 one of the following <codeph>#define</codeph> identifiers to the <filepath>eglheaders.mmh</filepath> file: </p> <ul> |
|
91 <li id="GUID-D400FDC2-44DB-5D4E-8355-3DB34DAA6549"><codeph>SYMBIAN_EGLHEADERS_API_VERSION_1_4</codeph> </li> |
|
92 <li id="GUID-E6CEFB0E-E60E-5B60-9085-83BC648B085C"><codeph>SYMBIAN_EGLHEADERS_API_VERSION_1_3</codeph> </li> |
|
93 <li id="GUID-BC66DCE0-042E-577F-B1E0-45F72B8FDFC4"><codeph>SYMBIAN_EGLHEADERS_API_VERSION_1_2</codeph> </li> |
|
94 </ul> <p>The <filepath>eglheaders.mmh</filepath> file is <codeph>#included</codeph> in |
|
95 the EGL Interface component's <filepath>bld.inf</filepath> and <filepath>egllib.mmp</filepath> files. </p> </section> |
|
96 <section id="GUID-A9195FBE-2418-5211-BD77-8DE3AFA5F1F4"><title>Ordinal reservation </title> <p>Symbian |
|
97 has adopted an ordinal reservation scheme for EGL in order to maximize extensibility |
|
98 while minimizing compatibility problems. The scheme is shown in the following |
|
99 table. </p> <table id="GUID-827E458D-965F-5258-9DA1-FA0FCB2A9FAE"> |
|
100 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
101 <thead> |
|
102 <row> |
|
103 <entry>Ordinals</entry> |
|
104 <entry>Description</entry> |
|
105 <entry>Owner</entry> |
|
106 </row> |
|
107 </thead> |
|
108 <tbody> |
|
109 <row> |
|
110 <entry><p>1</p> </entry> |
|
111 <entry><p>Reserved for use by implementations. </p> </entry> |
|
112 <entry><p>EGL implementer </p> </entry> |
|
113 </row> |
|
114 <row> |
|
115 <entry><p>2…249 </p> </entry> |
|
116 <entry><p>Reserved for the EGL Interface component to use for the standard |
|
117 functions that are defined in the EGL specification. In order to avoid future |
|
118 binary compatibility issues, do not use these in your implementation. </p> </entry> |
|
119 <entry><p>Symbian </p> </entry> |
|
120 </row> |
|
121 <row> |
|
122 <entry><p>250…499 </p> </entry> |
|
123 <entry><p>Reserved for use by implementations. </p> </entry> |
|
124 <entry><p>EGL implementer </p> </entry> |
|
125 </row> |
|
126 </tbody> |
|
127 </tgroup> |
|
128 </table> <p>The following diagram illustrates a typical ordinal usage scenario. </p> <fig id="GUID-9EDB47A4-043E-52AE-A6F9-E449563B77B7"> |
|
129 <title> Typical EGL ordinal usage scenario </title> |
|
130 <image href="GUID-03ED031D-65DB-51DE-8238-1F2ADF3BC936_d0e245515_href.png" placement="inline"/> |
|
131 </fig> <p>Note the following: </p> <ul> |
|
132 <li id="GUID-050C3247-7462-52BB-A94D-01BC793761FB"><p>The DEF file for the |
|
133 EGL Interface uses ordinal position entry points 2-249. </p> </li> |
|
134 <li id="GUID-D9BD2169-A2ED-5C44-990C-7B705530E7FB"><p>The <codeph>TARGETTYPE</codeph> keyword |
|
135 is set to <codeph>IMPLIB</codeph> in the EGL Interfaces's MMP file to indicate |
|
136 that only a LIB file is to be generated. </p> </li> |
|
137 <li id="GUID-0C96A6C4-6A2D-59AB-B026-8D55982D9485"><p>The DEF file for the |
|
138 EGL implementation uses the full range of ordinal position entry points. </p> </li> |
|
139 <li id="GUID-D822C741-2A75-590A-B519-246CE68D5D4D"><p>The <codeph>NOEXPORT</codeph> keyword |
|
140 is used in the implementation's MMP file to suppress the generation of a LIB |
|
141 file. </p> </li> |
|
142 <li id="GUID-DC7B2260-FEE7-5E29-9CA9-1D9381D528B7"><p>The <codeph>TARGETTYPE</codeph> keyword |
|
143 is set to <codeph>DLL</codeph> in the implementation's MMP file to indicate |
|
144 that it is a DLL project. </p> </li> |
|
145 </ul> </section> |
|
146 <section id="GUID-7B4FCF2F-9130-405B-B0C0-F569A7052885"><title>Internal functions</title> <p>The |
|
147 LIB file that the EGL Interface component produces is used to access the public |
|
148 methods of <filepath>libEGL.dll</filepath>. However, the DLL also has private |
|
149 methods. Sometimes internal access to these private methods is required—for |
|
150 example, by the implementation of an EGL client rendering API, such as OpenVG. </p> <p>When |
|
151 access to the private methods is required, it is recommended that the EGL |
|
152 implementation provides a separate private LIB file containing the internal |
|
153 API calls. This private LIB file works in a similar way to the public one |
|
154 in that it does not create a DLL. Appropriate clients can then link to the |
|
155 private LIB file when required. Applications should use the public LIB file |
|
156 to access the public methods of the EGL DLL. </p> <p>This mechanism ensures |
|
157 that normal clients never see the internal API calls and avoids tight coupling |
|
158 with a specific implementation. </p> <fig id="GUID-BA940F99-A4A4-5DF4-88A3-32A500EC9AC1"> |
|
159 <title> EGL implementation's private LIB file </title> |
|
160 <image href="GUID-FDDDF1F0-42D8-570E-AF06-620825FA1022_d0e245586_href.png" placement="inline"/> |
|
161 </fig> <p>Note the following: </p> <ul> |
|
162 <li id="GUID-C68A977A-0134-550D-8DAB-886B2E83F56E"><p>The DEF file for the |
|
163 private interface uses ordinal position entry points 1 and 250-499. </p> </li> |
|
164 <li id="GUID-61BA63E7-D0A3-531C-B378-7DF6890644CD"><p>The <codeph>TARGETTYPE</codeph> keyword |
|
165 is set to <codeph>IMPLIB</codeph> in the private interface's MMP file to indicate |
|
166 that only a LIB file is to be generated. </p> </li> |
|
167 <li id="GUID-6A0E6E83-DF39-5243-8834-8CAA122A2C7D"><p>The <codeph>LINKAS</codeph> keyword |
|
168 is used in the private interface's MMP file to indicate that it is to work |
|
169 with <codeph>libEGL.dll</codeph>. </p> </li> |
|
170 </ul> </section> |
|
171 <section id="GUID-31B83800-5789-4029-84F4-BD4451C4FA3B"><title>Extension functions</title> <p>If |
|
172 an EGL implementation provides an extension to EGL, clients must use the standard |
|
173 EGL function <codeph>eglGetProcAddress()</codeph> to access that functionality. |
|
174 This mechanism allows client programs to access the extension function without |
|
175 the need to expose the function through the DEF file. </p> </section> |
|
176 <section id="GUID-984B148D-C342-464A-B929-5AA2B8AE6A2E"><title>UIDs</title> <p>The |
|
177 Symbian platform libraries are given unique identifiers when they are built. |
|
178 The following UIDs have been allocated for EGL implementations: </p> <table id="GUID-20E5EE23-06A9-5565-8CF3-63A2CD8D8383"> |
|
179 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
180 <thead> |
|
181 <row> |
|
182 <entry>Library</entry> |
|
183 <entry> UID2</entry> |
|
184 <entry>UID3</entry> |
|
185 </row> |
|
186 </thead> |
|
187 <tbody> |
|
188 <row> |
|
189 <entry>EGL </entry> |
|
190 <entry><codeph>0x1000008d </codeph> </entry> |
|
191 <entry><codeph>0x10281AB8 </codeph> </entry> |
|
192 </row> |
|
193 </tbody> |
|
194 </tgroup> |
|
195 </table> <p>The UIDs are provided in <filepath>egluids.hrh</filepath>, which |
|
196 is provided in the <xref href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita">EGL |
|
197 Interface component</xref>. </p> </section> |
|
198 <section id="GUID-8DF58D61-F0A2-4EFE-8DAD-CFE4117CDFE6"><title>Platform security </title> <p>From |
|
199 Symbian OS v9.0 onwards, platform security must be considered. Essentially |
|
200 this requires adding the following lines to the <filepath>MMP</filepath> file: |
|
201 </p> <codeblock id="GUID-B43D55E9-5F1D-52DB-9B2E-2059B7C8C15C" xml:space="preserve">CAPABILITY All –Tcb |
|
202 VENDORID <your vendor id in hex> </codeblock> </section> |
|
203 <section id="GUID-5DE89FBE-FBD7-4304-A453-32A55E3DAA5E"><title>ROM building </title> <p>Building |
|
204 a ROM image for a target platform involves using IBY files. There is a generic |
|
205 IBY file called <filepath>egl.iby</filepath> for the EGL implementation. This |
|
206 must not be replaced. However, you can create an implementation-specific IBY |
|
207 file. This should have a unique name with the format <filepath>egl_adaptation.iby</filepath>, |
|
208 where <filepath>adaptation</filepath> is replaced by the vendor's name. For |
|
209 example: </p> <codeblock id="GUID-0787AB13-84BD-5CCB-9001-4C4DAF0684CF" xml:space="preserve">// EGL_VENDOR.IBY |
|
210 |
|
211 #ifndef __EGL_VENDOR_IBY__ |
|
212 #define __EGL_VENDOR_IBY__ |
|
213 |
|
214 REM EGL Vendor implementation |
|
215 |
|
216 file=ABI_DIR/BUILD_DIR/libegl_vendor.dll /sys/bin/libEGL.dll |
|
217 |
|
218 #endif</codeblock> <p>This IBY file must be exported by the <filepath>bld.inf</filepath> file |
|
219 to the <filepath>/epoc32/rom/include/</filepath> folder. </p> <p>You can include |
|
220 this implementation-specific IBY file in a device ROM configuration file by |
|
221 adding the following line to a top-level OBY file like this: </p> <codeblock id="GUID-E51D16DC-0059-58D2-A3E4-866E34BFB15E" xml:space="preserve">#define EGL_DRV <egl_vendor.iby></codeblock> <p>This |
|
222 is the preferred method. However, an alternative is to specify the IBY on |
|
223 the BUILDROM command line like this: </p> <codeblock id="GUID-9C5B7F9E-AA57-5694-A4DB-9E4ED500FA98" xml:space="preserve">BUILDROM ... –DEGL_DRV="^<"EGL_vendor.iby"^>" ... </codeblock> <p>Notice that the ^ character is used as an escape character for the < |
|
224 and > characters. </p> <p>See <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection |
|
225 of Adaptations</xref> for more information. </p> </section> |
|
226 <section id="GUID-BD4C33B6-EBBA-44DE-86BB-1896D1E74F79"><title>Project files</title> <p>Here |
|
227 is an example MMP file: </p> <codeblock id="GUID-9F08315E-DB1C-52C9-B777-6FD265EFF1CB" xml:space="preserve">#include "/epoc32/include/platform/egl/egluids.hrh" // For UIDs |
|
228 |
|
229 // These statements are always required: |
|
230 target libEGL.dll // Destination filename |
|
231 targettype dll // Binary build type |
|
232 uid KUidSharedDllUidValue KUidEGLDllUidValue // File UIDs |
|
233 capability All –Tcb // Platform Security requirement |
|
234 vendorid <Your vendor ID in hex> |
|
235 NOEXPORTLIBRARY // Suppress generation of LIB/DSO file |
|
236 DEFFILE libegl13.def |
|
237 |
|
238 // These statements are examples and may vary: |
|
239 userinclude ../include // Local include files |
|
240 systeminclude /epoc32/include // Symbian include files |
|
241 |
|
242 sourcepath ../egl // Relative path to source files |
|
243 |
|
244 source context.cpp // Source files |
|
245 source display.cpp |
|
246 source egl.cpp |
|
247 source surface.cpp |
|
248 |
|
249 library euser.lib // For the user library. |
|
250 library fbscli.lib // For CFbsBitmap, etc. |
|
251 library bitgdi.lib // For CFbsBitmapDevice, CFbsBitGc, etc. |
|
252 library ws32.lib // For RWindow, Direct Screen Access, etc.</codeblock> </section> |
|
253 <section id="GUID-8B5874FB-7367-484E-90B2-2AD9C2F522AB"><title>Example bld.inf</title> <p>A <filepath>bld.inf</filepath> file |
|
254 is also required: </p> <codeblock id="GUID-42A0C512-1685-5A1A-9687-851BF431BC00" xml:space="preserve">PRJ_PLATFORMS |
|
255 DEFAULT |
|
256 |
|
257 PRJ_EXPORTS |
|
258 egl_vendor.iby /epoc32/rom/include/egl_vendor.iby |
|
259 |
|
260 PRJ_MMPFILES |
|
261 ./egl.mmp</codeblock> </section> |
|
262 </conbody><related-links> |
|
263 <link href="GUID-0B2421FD-8431-5DDA-9FE3-046734AE495E.dita"><linktext>Window Surface |
|
264 Implementation</linktext></link> |
|
265 <link href="GUID-453CFE84-B2BA-56E6-BCB2-1162432B2358.dita"><linktext>Pixmap Implementation</linktext> |
|
266 </link> |
|
267 <link href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita"><linktext>EGL Interface |
|
268 Component</linktext></link> |
|
269 <link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL Collection |
|
270 Overview</linktext></link> |
|
271 <link href="http://www.khronos.org/egl/" scope="external"><linktext>http://www.khronos.org/egl/</linktext> |
|
272 </link> |
|
273 </related-links></concept> |