|
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-2923A42C-1C0E-553D-8563-7B9FC51F153F" xml:lang="en"><title>EGL |
|
13 Functions with Symbian-Specific Behavior</title><shortdesc>This topic describes the EGL functions that are defined as having |
|
14 platform-specific behavior and explains their expected behavior on the Symbian |
|
15 platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>The functions that have Symbian-specific behavior are: </p> |
|
17 <ul> |
|
18 <li id="GUID-26A32D85-FFC6-5EF8-AF56-D4F2BB809D51"><p> <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-4E3AD50C-FBBF-554A-99FE-A637AADAE93C">eglQueryString()</xref> </p> </li> |
|
19 <li id="GUID-04065DA1-A3E1-52C2-9C24-8B48FF3968FE"><p> <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-7D3B2473-5BFA-5C8A-B895-7B7E3D9949A8">eglCreatePixmapSurface()</xref> </p> </li> |
|
20 <li id="GUID-988AF3F7-D2CD-5993-A980-82C46A6E2D36"><p> <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-7FC7E115-F659-5EA0-9BD0-AFFA717C2C00">eglChooseConfig()</xref> </p> </li> |
|
21 <li><p><xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-E6BE99B1-6C0D-4D0D-B956-E7D3A312D75E">eglSurfaceAttrib()</xref></p></li> |
|
22 </ul> |
|
23 <section id="GUID-4E3AD50C-FBBF-554A-99FE-A637AADAE93C"><title>eglQueryString()</title> <codeblock id="GUID-3A9B5681-C61C-581F-A72E-10A821C15C3C" xml:space="preserve">const char *eglQueryString( |
|
24 EGLDisplay dpy, |
|
25 EGLint name)</codeblock> <p>When <codeph>name</codeph> is <codeph>EGL_EXTENSIONS</codeph>, |
|
26 the function returns the list of extensions supported by the implementation. |
|
27 The platform-specific strings are as follows: </p> <table id="GUID-969FA7B5-8C7A-5CD0-AA9E-9EA4AB3B34BA"> |
|
28 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
29 <thead> |
|
30 <row> |
|
31 <entry>String</entry> |
|
32 <entry>Description</entry> |
|
33 </row> |
|
34 </thead> |
|
35 <tbody> |
|
36 <row> |
|
37 <entry><p> <codeph>EGL_SYMBIAN_COMPOSITION</codeph> </p> </entry> |
|
38 <entry><p>Indicates that the ScreenPlay variant is in use. </p> </entry> |
|
39 </row> |
|
40 <row> |
|
41 <entry><p><codeph>EGL_KHR_reusable_sync</codeph></p></entry> |
|
42 <entry><p>Indicates that the EGL reusable sync extension is supported.</p></entry> |
|
43 </row> |
|
44 <row> |
|
45 <entry><codeph>EGL_NOK_resource_profiling</codeph></entry> |
|
46 <entry><p>Indicates that the EGL resource profiling extension is supported.</p></entry> |
|
47 </row> |
|
48 <row> |
|
49 <entry><codeph>EGL_NOK_resource_profiling2</codeph></entry> |
|
50 <entry><p>Indicates that the EGL resource profiling2 extension is supported.</p></entry> |
|
51 </row> |
|
52 </tbody> |
|
53 </tgroup> |
|
54 </table> <p><b>Example </b> </p> <codeblock id="GUID-D509300C-44C2-5AC1-8C8D-A5F42B55D825" xml:space="preserve">if ( NULL == strstr(eglQueryString(display, EGL_EXTENSIONS), "EGL_SYMBIAN_COMPOSITION") ) |
|
55 { |
|
56 RDebug::Printf("ScreenPlay not in use."); |
|
57 error = KErrNotSupported; |
|
58 }</codeblock> </section> |
|
59 <section id="GUID-7D3B2473-5BFA-5C8A-B895-7B7E3D9949A8"><title>eglCreatePixmapSurface()</title> <codeblock id="GUID-70CE6CC8-4F27-5296-B41C-998FDE11C466" xml:space="preserve">EGLSurface eglCreatePixmapSurface( |
|
60 EGLDisplay dpy, |
|
61 EGLConfig config, |
|
62 EGLNativePixmapType pixmap, |
|
63 const EGLint *attrib_list)</codeblock> <p> <codeph>EGLNativePixmapType</codeph> is |
|
64 a <codeph>CFbsBitmap*</codeph> . See <xref href="GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita">Symbian-Specific |
|
65 Behavior</xref> for more information. </p> <p>You must choose <codeph><config></codeph> using |
|
66 the attribute <codeph>EGL_MATCH_NATIVE_PIXMAP</codeph> when calling <xref href="GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F.dita#GUID-2923A42C-1C0E-553D-8563-7B9FC51F153F/GUID-7FC7E115-F659-5EA0-9BD0-AFFA717C2C00">eglChooseConfig()</xref> in |
|
67 order to ensure compatibility with the Symbian pixmap. </p> <p><b>Preconditions </b> </p> <ul> |
|
68 <li id="GUID-765C39DC-C244-5D0D-A084-63F8CCD8BC92"><p> <codeph><pixmap></codeph> has |
|
69 been initialized. </p> </li> |
|
70 <li id="GUID-1C249E36-D0F0-599F-8845-CBCEE4A8DC4F"><p>The <codeph>EGL_VG_ALPHA_FORMAT</codeph> attribute |
|
71 must be set to <codeph>EGL_VG_ALPHA_FORMAT_PRE</codeph> if the following conditions |
|
72 are all true: </p> <ul> |
|
73 <li id="GUID-5C0EB569-7768-5DA6-A114-0DB95380A686"><p>The pixel format of <codeph><pixmap></codeph> specifies |
|
74 premultiplied alpha—such as <codeph>EColor16MAP</codeph>. </p> </li> |
|
75 <li id="GUID-C103868C-106E-5BD3-8CD5-792548A7C30E"><p>The <codeph>EGL_RENDERABLE_TYPE</codeph> of <codeph><config></codeph> includes <codeph>EGL_OPENVG_BIT</codeph>. </p> </li> |
|
76 </ul> </li> |
|
77 </ul> <p><b>Error conditions </b> </p> <table id="GUID-9058A877-4E21-52DD-8F07-9785D46B9B4A"> |
|
78 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
79 <thead> |
|
80 <row> |
|
81 <entry>Error</entry> |
|
82 <entry>Description</entry> |
|
83 </row> |
|
84 </thead> |
|
85 <tbody> |
|
86 <row> |
|
87 <entry><p> <codeph>EGL_NO_SURFACE</codeph> </p> </entry> |
|
88 <entry><p>Returned if any of the preconditions are violated. </p> </entry> |
|
89 </row> |
|
90 <row> |
|
91 <entry><p> <codeph>EGL_BAD_NATIVE_PIXMAP</codeph> </p> </entry> |
|
92 <entry><p>Error generated when <codeph><pixmap></codeph> is not initialized. </p> </entry> |
|
93 </row> |
|
94 <row> |
|
95 <entry><p> <codeph>EGL_BAD_MATCH</codeph> </p> </entry> |
|
96 <entry><p>Error generated when any of the following occur: </p> <ul> |
|
97 <li id="GUID-7669B73A-8066-5488-A9F0-C8CC151107C0"><p>The attributes of <codeph><pixmap></codeph> do |
|
98 not correspond to those of <codeph><config></codeph>. </p> </li> |
|
99 <li id="GUID-C52CFB58-C033-52B6-ADBD-935D2808DD4D"><p> <codeph><config></codeph> does |
|
100 not support rendering to pixmaps (the <codeph>EGL_SURFACE_TYPE</codeph> attribute |
|
101 does not contain the <codeph>EGL_PIXMAP_BIT</codeph>). </p> </li> |
|
102 <li id="GUID-FB3EA01C-CD38-5764-8019-FD63B3B673B4"><p>The <codeph>EGL_VG_ALPHA_FORMAT</codeph> attribute |
|
103 is not set to <codeph>EGL_VG_ALPHA_FORMAT_PRE</codeph> for the cases described |
|
104 in the preconditions section above. </p> </li> |
|
105 </ul> </entry> |
|
106 </row> |
|
107 </tbody> |
|
108 </tgroup> |
|
109 </table> </section> |
|
110 <section id="GUID-7FC7E115-F659-5EA0-9BD0-AFFA717C2C00"><title>eglChooseConfig()</title> <codeblock id="GUID-36D7DCCD-C2AA-5A33-B55C-7648E685DC6B" xml:space="preserve">EGLBoolean eglChooseConfig( |
|
111 EGLDisplay dpy, |
|
112 const EGLint *attrib_list, |
|
113 EGLConfig *configs, |
|
114 EGLint config_size, |
|
115 EGLint *num_config)</codeblock> <p>The <codeph>EGLNativePixmapType</codeph> value |
|
116 corresponding to the <codeph>EGL_MATCH_NATIVE_PIXMAP</codeph> attribute is <codeph>CFbsBitmap*</codeph>. |
|
117 See <xref href="GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita">Symbian-Specific |
|
118 Behavior</xref> for more information. </p> <p>The configuration attribute <codeph>EGL_SWAP_BEHAVIOR_PRESERVED_BIT</codeph> is |
|
119 set by default on window surfaces. This bit is not relevant to pixmap and |
|
120 pbuffer surfaces because they are single-buffered.</p> <p><b>Postconditions </b> </p> <p>The |
|
121 following apply to the <codeph>EGLNativePixmapType</codeph> value only. </p> <ul> |
|
122 <li id="GUID-37ED30DE-703C-5427-9DE5-9D3E0FBDCDC8"><p>The <codeph>EGL_SURFACE_TYPE</codeph> of |
|
123 each matching config contains <codeph>EGL_VG_ALPHA_FORMAT_PRE_BIT</codeph> if |
|
124 the following conditions are all true: </p> <ul> |
|
125 <li id="GUID-ECCF6C6C-B582-5326-B18B-8FB9FCA87309"><p>The pixel format of |
|
126 the pixmap specifies premultiplied alpha—such as <codeph>EColor16MAP</codeph>. </p> </li> |
|
127 <li id="GUID-DC7E7D5B-2E6F-5290-A419-C5BD3EFA69E4"><p>The <codeph>EGL_RENDERABLE_TYPE</codeph> of |
|
128 the config includes <codeph>EGL_OPENVG_BIT</codeph>. </p> </li> |
|
129 </ul> </li> |
|
130 </ul> <p> <i>Note</i>: The <codeph>EGL_RENDERABLE_TYPE</codeph> can be used |
|
131 as an input to <codeph>eglChooseConfig()</codeph> to further filter the set |
|
132 of configs returned. </p> </section> |
|
133 <section id="GUID-E6BE99B1-6C0D-4D0D-B956-E7D3A312D75E"><title>eglSurfaceAttrib()</title><codeblock xml:space="preserve">EGLBoolean eglSurfaceAttrib( |
|
134 EGLDisplay dpy, |
|
135 EGLSurface surface, |
|
136 EGLint attribute, |
|
137 EGLint value);</codeblock><p>If the <codeph>attribute</codeph> is <codeph>EGL_SWAP_BEHAVIOR</codeph>, |
|
138 the value can be one of the following:.</p><ul> |
|
139 <li><p><codeph>EGL_BUFFER_DESTROYED</codeph>: Indicates that posting a surface |
|
140 with <codeph>eglSwapBuffers()</codeph> changes or destroys the back buffer |
|
141 content.</p></li> |
|
142 <li><p><codeph>EGL_BUFFER_PRESERVED</codeph>: Indicates that posting a surface |
|
143 with <codeph>eglSwapBuffers()</codeph> preserves the back buffer content.</p></li> |
|
144 </ul> <p>The preserve buffer feature is relevant only to window surfaces. |
|
145 It is not relevant to pbuffer or pixmap surfaces because they are single-buffered. |
|
146 Therefore setting the swap behavior to preserve buffer is not allowed for |
|
147 these surface types, as shown in the following table. </p> <table id="GUID-1BB87D88-B15C-4BB5-AAC8-88094B4ADB2A"> |
|
148 <title>Configuration behaviors</title> |
|
149 <tgroup cols="4"><colspec colname="col1" colwidth="1.62*"/><colspec colname="col2" colwidth="0.88*"/><colspec colname="col3" colwidth="0.74*"/><colspec colname="col4" colwidth="0.79*"/> |
|
150 <thead> |
|
151 <row> |
|
152 <entry valign="top">Configuration Mask</entry> |
|
153 <entry valign="top">Default EGL_SWAP_BEHAVIOR</entry> |
|
154 <entry valign="top">Set Destroyed Allowed?</entry> |
|
155 <entry valign="top">Set Preserved Allowed?</entry> |
|
156 </row> |
|
157 </thead> |
|
158 <tbody> |
|
159 <row> |
|
160 <entry><codeph>EGL_SWAP_BEHAVIOR_PRESERVED_BIT|EGL_WINDOW_BIT </codeph></entry> |
|
161 <entry>Destroyed</entry> |
|
162 <entry>Yes</entry> |
|
163 <entry>Yes</entry> |
|
164 </row> |
|
165 <row> |
|
166 <entry><codeph>EGL_WINDOW_BIT</codeph> </entry> |
|
167 <entry>Destroyed </entry> |
|
168 <entry>Yes</entry> |
|
169 <entry>Yes</entry> |
|
170 </row> |
|
171 <row> |
|
172 <entry> <codeph>EGL_PIXMAP_BIT</codeph></entry> |
|
173 <entry>Preserved</entry> |
|
174 <entry>Yes</entry> |
|
175 <entry>No</entry> |
|
176 </row> |
|
177 <row> |
|
178 <entry> <codeph>EGL_PBUFFER_BIT</codeph></entry> |
|
179 <entry>Preserved </entry> |
|
180 <entry>Yes</entry> |
|
181 <entry>No</entry> |
|
182 </row> |
|
183 </tbody> |
|
184 </tgroup> |
|
185 </table> <p><b>Error conditions </b></p><p>This applies to attempting to set |
|
186 the <codeph>EGL_SWAP_BEHAVIOR</codeph> attribute to <codeph>EGL_BUFFER_PRESERVED</codeph>. |
|
187 If the surface configuration does not match <codeph>EGL_SWAP_BEHAVIOR_PRESERVED_BIT</codeph>, |
|
188 this function returns <codeph>EGL_FALSE</codeph> and generates an error of <codeph>EGL_BAD_MATCH</codeph>. </p></section> |
|
189 </conbody><related-links> |
|
190 <link href="GUID-A5914CFF-6F86-53E8-9928-36D3379835B1.dita"><linktext>EGL Interface |
|
191 Overview</linktext></link> |
|
192 <link href="GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita"><linktext>Symbian-Specific |
|
193 Behavior</linktext></link> |
|
194 <link href="GUID-46813F51-370B-5853-917C-6916925A347D.dita"><linktext>EGL Tutorial</linktext> |
|
195 </link> |
|
196 <link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL Collection |
|
197 Overview</linktext></link> |
|
198 </related-links></concept> |