1Name 2 3 EXT_client_extensions 4 5Name Strings 6 7 EGL_EXT_client_extensions 8 9Contributors 10 11 Chad Versace <chad.versace@intel.com> 12 Ian Romanick <ian.d.romanick@intel.com> 13 Jakob Bornecrantz <jakob@vmware.com> 14 James Jones <jajones@nvidia.com> 15 16Contacts 17 18 Chad Versace <chad.versace@intel.com> 19 20Status 21 22 Complete 23 24Version 25 26 Version 11, 2013.10.10 27 28Number 29 30 EGL Extension #58 31 32Extension Type 33 34 EGL client extension 35 36Dependencies 37 38 Requires EGL 1.4. 39 40 This extension is written against the wording of the EGL 1.4 41 Specification. 42 43Overview 44 45 This extension introduces the concept of *extension type*, requires that 46 each EGL extension belong to exactly one type, and defines two types: 47 display and client. It also provides a method to query, without 48 initializing a display, the set of supported client extensions. 49 50 A display extension adds functionality to an individual EGLDisplay. This 51 type of extension has always existed but, until EGL_EXT_client_extensions, 52 lacked an identifying name. 53 54 A client extension adds functionality that is independent of any display. 55 In other words, it adds functionality to the EGL client library itself. This 56 is a new type of extension defined by EGL_EXT_client_extensions. 57 EGL_EXT_client_extensions is itself a client extension. 58 59 We suggest that each future extension clearly state its type by including 60 the following toplevel section in its extension specification, preceding the 61 Dependencies section. For client extensions, this suggestion is 62 a requirement. 63 64 Extension Type 65 66 <Either "EGL display extension" or "EGL client extension" or 67 a future extension type.> 68 69 By cleanly separating display extensions from client extensions, 70 EGL_EXT_client_extensions solves a bootstrap problem for future EGL 71 extensions that will modify display initialization. To query for such 72 extensions without EGL_EXT_client_extensions, an EGL client would need to 73 initialize a throw-away EGLDisplay solely to query its extension string. 74 Initialization of the throw-away display may have undesired side-effects 75 (discussed in the issues section below) for EGL clients that wish to use the 76 new methods of display initialization. 77 78New Types 79 80 None 81 82New Procedures and Functions 83 84 None 85 86New Tokens 87 88 None 89 90Additions to the EGL 1.4 Specification: 91 92 93 Add the following section to Chapter 2 "EGL Operation": 94 95 "2.n Extensions 96 97 EGL implementations may expose additional functionality beyond that 98 described by this specification. Additional functionality may include new 99 functions, new enumerant values, and extended behavior for existing 100 functions. Implementations advertise such extensions to EGL by exposing 101 *extension strings*, which are queryable with eglQueryString. 102 103 Each EGL extension belongs to exactly one of the following types: 104 105 Display Extensions 106 A *display extension* adds functionality to an individual 107 EGLDisplay. Different instances of EGLDisplay may support different 108 sets of display extensions. 109 110 Client Extensions 111 A *client extension* adds functionality that is independent of any 112 display. In other words, it adds functionality to the EGL client 113 library itself. In a given process, there exists exactly one set, 114 possibly empty, of supported client extensions. When the client 115 extension string is first queried, that set becomes immutable." 116 117 Replace the paragraph in section 3.3 "EGL Versioning" that begins "The 118 EGL_EXTENSIONS string" with the following text: 119 120 "The EGL_EXTENSIONS string describes which set of EGL extensions are 121 supported. The string is zero-terminated and contains a space-separated 122 list of extension names; extension names themselves do not contain spaces. 123 If there are no extensions to EGL, then the empty string is returned. 124 125 If <dpy> is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set 126 of supported client extensions. If <dpy> is a valid, initialized display, 127 then the EGL_EXTENSIONS string describes the set of display extensions 128 supported by the given display. The set of supported client extensions is 129 disjoint from the set of extensions supported by any given display [fn]. 130 131 [fn] This is a consequence of the requirement in Section 2.n Extensions that 132 each extension belong to exactly one extension type." 133 134 Replace the last paragraph of section 3.3 "EGL Versioning" with: 135 136 "On failure, NULL is returned. An EGL_BAD_DISPLAY error is generated if 137 <dpy> is not a valid display, unless <dpy> is EGL_NO_DISPLAY and <name> is 138 EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if <dpy> is 139 a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated 140 if <name> is not one of the values described above." 141 142Conformance Tests 143 144 1. Before any call to eglGetDisplay, call `eglQueryString(EGL_NO_DISPLAY, 145 EGL_EXTENSIONS)`. Verify that either 146 147 a. The call returns NULL and generates EGL_BAD_DISPLAY. 148 b. The call returns an extension string that contains, at a minimum, 149 this extension and generates no error. 150 151 2. Obtain a display with eglGetDisplay but do not initialize it. Verity 152 that passing the uninitialized display to `eglQueryString(dpy, 153 EGL_EXTENSIONS)` returns NULL and generates EGL_NOT_INITIALIZED. 154 155 3. Obtain a list of display extensions by calling `eglQueryString(dpy, 156 EGL_EXTENSIONS)` on an initialized display. Obtain the list of client 157 extensions by calling `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`. 158 If both calls succeed, verify the two lists are disjoint. 159 160Issues 161 162 1. How should clients detect if this extension is supported? 163 164 RESOLVED: If an EGL implementation supports this extension, then 165 `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` returns 166 a well-formed extension string and generates no error. Otherwise, it 167 returns NULL and generates EGL_BAD_DISPLAY. 168 169 2. On EGL platforms that define EGL_NO_DISPLAY as NULL, does not calling 170 `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` risk a null pointer 171 dereference? Therefore, how is it possible on such platforms for 172 a client to safely detect if this extension is supported? 173 174 RESOLVED: According to the EGL 1.4 specification, calling 175 `eglQueryString(EGL_NO_DISPLAY, name)` returns NULL and generates 176 EGL_BAD_DISPLAY. No null pointer dereference occurs even if the 177 platform defines EGL_NO_DISPLAY as NULL. 178 179 3. What existing extensions should returned by 180 `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`? 181 182 RESOLVED: Possibly EGL_NV_system_time. 183 184 4. What should be the relationship between the extension string of 185 EGL_NO_DISPLAY and the extension string of a valid display? That is, 186 should the former be a subset of the latter? Should the two be 187 disjoint? Should the relationship remain undefined? 188 189 Another phrasing of this issue is: When, if ever, should client 190 extensions appear in a display's extension string? 191 192 RESOLVED: The extension string of EGL_NO_DISPLAY must be disjoint 193 from the extension string of any valid display. That is, EGL_NO_DISPLAY 194 must advertise only client extensions, and valid displays must not 195 advertise client extensions. By defining a clear relationship between 196 the two types of extension strings, we enforce consistent behavior among 197 implementations, thus preventing possible confusion from application 198 developers. 199 200 DISCUSSION: This resolution has special implications for systems where 201 libEGL is a vendor-independent library that loads and then dispatches 202 to the appropriate vendor-provided EGL library. The resolution requires 203 that client extensions, as well the construction of extension strings, 204 be at least partially implemented in the vendor-independent library. 205 206 The alternative resolution of mandating the 'superset' relation (that 207 is, that the extension string of a valid display must be a superset of 208 that of EGL_NO_DISPLAY) was rejected due to potential confusion on 209 behalf of the application developer as well as the driver implementer. 210 What follows is an example of each. 211 212 a) Suppose an EGL implementation supported creation of 213 a software-renderer EGLDisplay through a client extension named 214 EGL_XYZ_platform_software_renderer. If the 'superset' relation were 215 mandated, then each display, whether it were hardware-accelerated or 216 software-only, would advertise the EGL_XYZ_platform_software_renderer 217 extension string. This would likely confuse application developers. 218 219 b) If the 'superset' relation were mandated, then the possibility 220 exists that a vendor would ship a hybrid extension that is both 221 a client extension and a display extension. Such a hybrid extension 222 poses subtle difficulties for systems where libEGL is 223 a vendor-independent library that dispatches to the appropriate 224 vendor-provided EGL driver. On such a system, the extension's hybrid 225 nature may require that each vendor-provided EGL driver support the 226 extension before the vendor-independent EGL library could safely 227 expose the extension. By choosing the 'disjoint' relation rather 228 than 'superset', we prevent this problematic situation from 229 occuring. 230 231 5. Should client extension specifications explicitly state they are 232 returned in the extension string of EGL_NO_DISPLAY? 233 234 RESOLVED: Yes. Enforce this by requiring that client extension 235 specifications contain the toplevel section "Extension Type". 236 237 6. As explained in the overview section, this "extension solves 238 a bootstrap problem for future EGL extensions that modify display 239 initialization". What solutions to the bootstrap problem were 240 considered? Why was EGL_EXT_client_extensions chosen as the best 241 solution? 242 243 DISCUSSION: First let's discuss the exact nature of the bootstrap 244 problem and of the future EGL extensions that modify display 245 initialization. 246 247 Mesa's EGL implementation supports multiple native platforms (such as 248 Wayland, GBM, and X11) at runtime, and we expect that more 249 implementations will do so in the future. The EGL API is deficient for 250 such implementations because it does not yet provide a way for clients 251 to query the set of supported native platforms. Also, EGL provides no 252 way for clients to specify to which platform the native display belongs 253 during display initialization. (That is, eglGetDisplay has a native 254 display parameter, but no parameter specifying the native platform). 255 256 Future EGL extensions, currently under progress, will solve these 257 deficiencies in the EGL API by (1) adding a variant of eglGetDisplay 258 that allows specification of the platform to which the native display 259 belongs and (2) by advertising the set of native platforms supported by 260 the implementation. 261 262 However, there exists a bootstrap problem here. To query if a given 263 native platform is supported, the EGL client must initialize an 264 EGLDisplay to query its extension string. But, not yet knowing which 265 native platforms the EGL implementation supports, the client cannot 266 safely pass any native display to eglGetDisplay, and therefore cannot 267 obtain an extension string. 268 269 The following solutions to this bootstrap problem have been considered. 270 For conciseness, let's refer to the future EGL extensions that modify 271 display initialization as "client extensions". 272 273 1. PROPOSED SOLUTION: To determine if an EGL implementation supports 274 a given client extension, require that the EGL client call 275 eglGetProcAddress on some function defined by the extension. If 276 eglGetProcAddress returns non-null, then the implementation 277 supports the extension. 278 279 ANALYSIS: The EGL 1.4 spec permits eglGetProcAddress to return 280 non-null for unrecognized function names. Therefore, this 281 solution's method may produce false positives on some 282 implementations. 283 284 Also, this solution does not permit detection of client extensions 285 that add no new functions. 286 287 2. PROPOSED SOLUTION: To determine if an EGL implementation supports 288 a given client extension, the EGL client should examine the 289 extension string of EGL_DEFAULT_DISPLAY. Querying 290 EGL_DEFAULT_DISPLAY is a failsafe mechanism by which the EGL 291 client can obtain an extension string, because EGL_DEFAULT_DISPLAY 292 is a valid input to eglGetDisplay regardless of which platforms 293 the EGL implementation supports. 294 295 ANALYSIS: This solution is awkward. It requires that the client 296 initialize a throw-away EGLDisplay solely to query its extension 297 string, even though the desired extension is not a property of any 298 display but of the EGL library itself. 299 300 This solution also has a subtle fatal problem. It is not backwards 301 compatible with Mesa. As of 2013-06-07, Mesa's EGL implementation 302 stores at runtime a user-chosen native platform in global 303 write-once state. Calling eglGetDisplay is one action that 304 results in writing to that state. Therefore, if a client process 305 running on such a problematic version of Mesa initialized 306 EGL_DEFAULT_DISPLAY solely to detect some client extension, then 307 the client process would be confined for its lifetime to use only 308 that platform to which EGL_DEFAULT_DISPLAY belongs. This 309 confinement may be fatal if the process had wanted to use 310 a different platform. 311 312 3. PROPOSED SOLUTION: Abandon the concept of client extensions. 313 Instead, in implementations that support multiple window systems 314 at runtime, eglGetDisplay should autodetect the platform to which 315 the native display belongs. A suitable error should be generated 316 if an unsupported native display is passed to eglGetDisplay. 317 318 ANALYSIS: For some native platforms, the display type is opaque 319 with no defined ABI. (For example, in libX11 the 'Display' type is 320 an opaque typedef). There exists no method by which eglGetDisplay 321 could reliably detect that the given native display belongs to 322 such a platform. 323 324 This solution also has a subtle fatal problem. The client 325 extensions will likely specify that an EGL client may create EGL 326 resources from multiple platforms in the same process. But, Mesa's 327 global write-once state, mentioned above, prevents using multiple 328 platforms in one process. Therefore, under this proposed solution 329 and on a system where a problematic version of Mesa is installed, 330 the client would be unable to detect if EGL supported multiple 331 platforms per process without committing to the platform to which 332 the first initialized display belonged. 333 334 4. ACCEPTED SOLUTION: Allow the EGL client to query the extension 335 string of EGL_NO_DISPLAY, which would contain the client 336 extensions. 337 338 ANALYSIS: This solution does not require the initialization of 339 a throw-away EGLDisplay, nor does it require that native display 340 types have a fixed ABI. 341 342 This is the solution described by this extension specification, 343 EGL_EXT_client_extensions. 344 345Revision History 346 347 Version 11, 2013.10.10 (Chad Versace) 348 - Fix conformance test #3. It should require that the display extension 349 list be disjoint to rather than a superset of the client extension 350 list. (The 'superset' requirement was changed pre-publication to 351 'disjoint' in version 8). 352 353 Version 10, 2013.07.03 (Chad Versace) 354 - Version 9 and 10 are identical due to a versioning error. 355 356 Version 9, 2013.07.03 (Chad Versace) 357 - Define the concept of *extension type*, require require that each EGL 358 extension belong to exactly one type, and define two types: display 359 and client. 360 - Suggest new section "Extension Type" for future extension 361 specifications. 362 - Add new section 2.n Extensions. 363 - Simplify modifications to section 3.3 by using the new extension type 364 terminology. 365 366 Version 8, 2013.07.01 (Chad Versace) 367 - Change resolution of Issue 4 from the 'superset' relation to the 368 'disjoint' relation, according to discussion with Jakob Bornecrantz. 369 Acked by James Jones. 370 371 Version 7, 2013.06.10 (Chad Versace) 372 - Fix typos. 373 s/unitialized/uninitialized/ 374 s/EGL_NO_EXTENSIONS/EGL_EXTENSIONS/ 375 376 Version 6, 2013.06.07 (Chad Versace) 377 - Remove the Motivation section, merging its content into the Overview 378 section and Issue 6. 379 380 Version 5, 2013.06.07 (Chad Versace) 381 - Resolve issue 3 regarding classifying currently published extensions 382 as client extensions. 383 - Resolve issue 4 regarding the relationship among client and display 384 extension strings. 385 - Add and resolve issue 5, requiring client extension specifications 386 to contain language about the EGL_NO_DISPLAY extension string. 387 388 Version 4, 2013.05.14 (Chad Versace) 389 - Add issue 4. 390 391 Version 3, 2013.03.24 (Chad Versace) 392 - Fix conformance test condition 1.b. The returned extension string 393 should list, at a minimum, this extension. [Found by Ian Romanick]. 394 - Add section "Movivation". [Requested by Ian Romanick]. 395 396 Version 2, 2013.03.06 (Chad Versace) 397 - Remove enum EGL_CLIENT_EXTENSIONS_EXT. Reuse EGL_EXTENSIONS for that 398 purpose. 399 - To obtain client extensions, require the eglQueryString be called 400 with dpy=EGL_NO_DISPLAY rather than dpy=NULL. [Suggested by James 401 Jones]. 402 - Add descriptions of conformance tests. [Suggested by Ian Romanick]. 403 - Add sections "Overview" and "Issues". 404 405 Version 1, 2013.03.06 (Chad Versace) 406 - First draft 407 408# vim: filetype=text expandtab autoindent shiftwidth=4 textwidth=80: 409