1Name 2 3 EXT_platform_base 4 5Name Strings 6 7 EGL_EXT_platform_base 8 9Contributors 10 11 Chad Versace <chad.versace@intel.com> 12 James Jones <jajones@nvidia.com> 13 14Contacts 15 16 Chad Versace <chad.versace@intel.com> 17 18Status 19 20 Complete 21 22Version 23 24 Version 9, 2014.01.09 25 26Number 27 28 EGL Extension #57 29 30Extension Type 31 32 EGL client extension 33 34Dependencies 35 36 Requires EGL 1.4. 37 38 Requires EGL_EXT_client_extensions to query its existence without 39 a display. 40 41 This extension is written against the wording of the 2013.02.11 revision 42 of the EGL 1.4 Specification. 43 44Overview 45 46 This extension defines functionality and behavior for EGL implementations 47 that support multiple platforms at runtime. For example, on Linux an EGL 48 implementation could support X11, Wayland, GBM (Generic Buffer Manager), 49 Surface Flinger, and perhaps other platforms. 50 51 In particular, this extension defines the following: 52 53 1. A mechanism by which an EGL client can detect which platforms the 54 EGL implementation supports. 55 56 2. New functions that enable an EGL client to specify to which 57 platform a native resource belongs when creating an EGL resource 58 from that native resource. For example, this extension enables an 59 EGL client to specify, when creating an EGLSurface from a native 60 window, that the window belongs to X11. 61 62 3. That an EGL client is not restricted to interacting with a single 63 platform per process. A client process can create and manage EGL 64 resources from multiple platforms. 65 66 The generic term 'platform' is used throughout this extension 67 specification rather than 'window system' because not all EGL platforms 68 are window systems. In particular, those platforms that allow headless 69 rendering without a display server, such as GBM, are not window systems. 70 71 This extension does not specify behavior specific to any platform, nor 72 does it specify the set of platforms that an EGL implementation may 73 support. Platform-specific details lie outside this extension's scope and 74 are instead described by extensions layered atop this one. 75 76New Types 77 78 None 79 80New Procedures and Functions 81 82 EGLDisplay eglGetPlatformDisplayEXT( 83 EGLenum platform, 84 void *native_display, 85 const EGLint *attrib_list); 86 87 EGLSurface eglCreatePlatformWindowSurfaceEXT( 88 EGLDisplay dpy, 89 EGLConfig config, 90 void *native_window, 91 const EGLint *attrib_list); 92 93 EGLSurface eglCreatePlatformPixmapSurfaceEXT( 94 EGLDisplay dpy, 95 EGLConfig config, 96 void *native_pixmap, 97 const EGLint *attrib_list); 98 99New Tokens 100 101 None 102 103Additions to the EGL 1.4 Specification 104 105 Replace each occurence of the term "window system" with "platform". The 106 rationale behind this change is that not all platforms are window systems, 107 yet the EGL 1.4 specification uses the two terms interchangeably. In 108 particular, platforms that allow headless rendering without a display 109 server, such as GBM, are not window systems. 110 111 Append the following paragraph to the initial, unnamed subsection of 112 section 2.1 "Native Window System and Rendering APIs". 113 114 "This specification does not define the set of platforms that may be 115 supported by the EGL implementation, nor does it specify behavior specific 116 to any platform. The set of supported platforms and their behavior is 117 defined by extensions. To detect if a particular platform is supported, 118 clients should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using 119 eglQueryString. 120 121 Replace the text of section 3.2 "Initialization", from the start of the 122 section and up to and excluding the phrase "EGL may be intialized on 123 a display", with the following: 124 125 "A display can be obtained by calling 126 127 EGLDisplay eglGetPlatformDisplayEXT( 128 EGLenum platform, 129 void *native_display, 130 const EGLint *attrib_list); 131 132 EGL considers the returned EGLDisplay as belonging to the native platform 133 specified by <platform>. This specification defines no valid value for 134 <platform>. Any specification that does define a valid value for 135 <platform> will also define requirements for the <native_display> 136 parameter. For example, an extension specification that defines support 137 for the X11 platform may require that <native_display> be a pointer to an 138 X11 Display, and an extension specification that defines support for the 139 Microsoft Windows platform may require that <native_display> be a pointer 140 to a Windows Device Context. 141 142 All attribute names in <attrib_list> are immediately followed by the 143 corresponding desired value. The list is terminated with EGL_NONE. The 144 <attrib_list> is considered empty if either <attrib_list> is NULL or if 145 its first element is EGL_NONE. This specification defines no valid 146 attribute names for <attrib_list>. 147 148 Multiple calls made to eglGetPlatformDisplayEXT with the same <platform> 149 and <native_display> will return the same EGLDisplay handle. 150 151 An EGL_BAD_PARAMETER error is generated if <platform> has an invalid value. 152 If <platform> is valid but no display matching <native_display> is 153 available, then EGL_NO_DISPLAY is returned; no error condition is raised 154 in this case. 155 156 A display can also be obtained by calling 157 158 EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id); 159 160 The behavior of eglGetDisplay is similar to that of 161 eglGetPlatformDisplayEXT, but is specifided in terms of implementation- 162 specific behavior rather than platform-specific extensions. 163 As for eglGetPlatformDisplayEXT, EGL considers the returned EGLDisplay 164 as belonging to the same platform as <display_id>. However, the set of 165 platforms to which <display_id> is permitted to belong, as well as the 166 actual type of <display_id>, are implementation-specific. If <display_id> 167 is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls 168 made to eglGetDisplay with the same <display_id> will return the same 169 EGLDisplay handle. If no display matching <display_id> is available, 170 EGL_NO_DISPLAY is returned; no error condition is raised in this case." 171 172 In section 3.5.1 "Creating On-Screen Rendering Surfaces", replace the 173 second paragraph, which begins with "Using the platform-specific type" and 174 ends with "render into this surface", with the following: 175 176 "Then call 177 178 EGLSurface eglCreatePlatformWindowSurfaceEXT( 179 EGLDisplay dpy, 180 EGLConfig config, 181 void *native_window, 182 const EGLint *attrib_list); 183 184 eglCreatePlatformWindowSurfaceEXT creates an onscreen EGLSurface and 185 returns a handle to it. Any EGL context created with a compatible 186 EGLConfig can be used to render into this surface. 187 188 <native_window> must belong to the same platform as <dpy>, and EGL 189 considers the returned EGLSurface as belonging to that same platform. The 190 extension that defines the platform to which <dpy> belongs also defines 191 the requirements for the <native_window> parameter." 192 193 In the remainder of section 3.5.1, replace each occurrence of 194 'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'. 195 196 Insert the sentence below after the first sentence of the last paragraph 197 of section 3.5.1: 198 199 "If <dpy> and <native_window> do not belong to the same platform, then 200 undefined behavior occurs. [1]" 201 202 Add the following footnote to section 3.5.1: 203 204 "[1] See section 3.1.0.2 "Parameter Validation". 205 206 Append the following to section 3.5.1: 207 208 "An on-screen rendering surface may also be created by calling 209 210 EGLSurface eglCreateWindowSurface( 211 EGLDisplay dpy, 212 EGLConfig config, 213 EGLNativeWindowType win, 214 const EGLint *attrib_list); 215 216 The behavior of eglCreateWindowSurface is identical to that of 217 eglCreatePlatformWindowSurfaceEXT except that the set of platforms to 218 which <dpy> is permitted to belong, as well as the actual type of <win>, 219 are implementation specific. 220 221 In section 3.5.4 "Creating Native Pixmap Rendering Surfaces", replace the 222 third paragraph, which begins with "Using the platform-specific type" and 223 ends with "render into this surface", with the following: 224 225 "Then call 226 227 EGLSurface eglCreatePlatformPixmapSurfaceEXT( 228 EGLDisplay dpy, 229 EGLConfig config, 230 void *native_pixmap, 231 const EGLint *attrib_list); 232 233 eglCreatePlatformPixmapSurfaceEXT creates an offscreen EGLSurface and 234 returns a handle to it. Any EGL context created with a compatible 235 EGLConfig can be used to render into this surface. 236 237 <native_pixmap> must belong to the same platform as <dpy>, and EGL 238 considers the returned EGLSurface as belonging to that same platform. The 239 extension that defines the platform to which <dpy> belongs also defines 240 the requirements for the <native_pixmap> parameter." 241 242 In the remainder of section 3.5.4, replace each occurrence of 243 'eglCreatePixmapSurface' with 'eglCreatePlatformPixmapSurfaceEXT' and each 244 occurence of 'eglCreateWindowSurface' with 245 'eglCreatePlatformWindowSurfaceEXT'. 246 247 Insert the sentence below after the first sentence of the last paragraph 248 of section 3.5.4: 249 250 "If <dpy> and <native_pixmap> do not belong to the same platform, then 251 undefined behavior occurs. [1]" 252 253 Add the following footnote to section 3.5.3: 254 255 "[1] See section 3.1.0.2 "Parameter Validation". 256 257 Append the following to section 3.5.2: 258 259 "An offscreen rendering surface may also be created by calling 260 261 EGLSurface eglCreatePixmapSurface( 262 EGLDisplay dpy, 263 EGLConfig config, 264 EGLNativePixmapType pixmap, 265 const EGLint *attrib_list); 266 267 The behavior of eglCreatePixmapSurface is identical to that of 268 eglCreatePlatformPixmapSurfaceEXT except that the set of platforms to 269 which <dpy> is permitted to belong, as well as the actual type of 270 <pixmap>, are implementation specific. 271 272Issues 273 274 1. What rules define how EGL resources are shared among displays belonging 275 to different platforms? 276 277 RESOLVED: Neither the EGL 1.4 specification nor any extension allow EGL 278 resources to be shared among displays. This extension does not remove 279 that restriction. 280 281 2. Rather than define the new function eglGetPlatformDisplayEXT(), should 282 this extension instead define new thread-local state for the currently 283 bound platform and an associated binding function, such as 284 eglBindPlatformEXT()? 285 286 RESOLVED: No, for the following reasons. 287 288 - A current trend among the Khronos workgroups is to remove use of 289 global state by introducing bindless objects. Introducing a new 290 thread-local binding point defies that trend. 291 292 - Additional specification language would be required to define 293 the interactions between the currently bound platform and all 294 EGL functions that accept an EGLDisplay. (For example, if the 295 currently bound platform is Wayland, then what is the result of 296 calling eglCreateWindowSurface() with a display and native 297 window belonging to X11?) By choosing to not introduce the 298 notion of a "currently bound platform", we obtain a cleaner 299 extension specification and eliminate for EGL users a class of 300 potential bugs. 301 302 3. Should this extension define the notion of a default platform? 303 304 RESOLVED: No. eglGetDisplay() can be used if a default platform is 305 needed. 306 307 4. Rather than define the new functions 308 eglCreatePlatform{Window,Pixmap}SurfaceEXT(), should we instead 309 redefine the EGLNative* types in eglplatform.h as void*? 310 311 RESOLVED: No, this introduces problems for X11 applications. 312 313 Suppose that a 64-bit X11 application is compiled against an old EGL 314 library (where EGLNativeWindowType is a typedef for XID, which is in 315 turn a typedef for a 64-bit unsigned integer on Fedora 18) and then 316 attempts to run against a new EGL library (where EGLNativeType is 317 a typedef for void*). To preserve the ABI of eglCreateWindowSurface() 318 in this situation, the new EGL library must re-interpret the 319 <native_window> parameter as an integer. 320 321 However, this preservation of the ABI breaks source compatibility for 322 existing X11 applications. To successfully compile, each call to 323 324 eglCreateWindowSurface(dpy, window, attribs) 325 326 in existing X11 application source code would need to be replaced with 327 328 eglCreateWindowSurface(dpy, (void*) window, attribs) . 329 330 Requiring such widespread code modifications would be an unnecessary 331 burden to developers and Linux package maintainers. 332 333Revision History 334 335 Version 9, 2014.01.09 (Jon Leech) 336 - Fix typo eglGetDisplayPlatformEXT -> eglGetPlatformDisplayEXT 337 338 Version 8, 2013.07.03 (Chad Versace) 339 - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. 340 341 Version 7, 2013.06.07 (Chad Versace) 342 - Fix some awkward text (s/the EGL/EGL/). 343 - Remove text "attribute names are defined by platform-specific 344 extensions". 345 346 Version 6, 2013.06.07 (Chad Versace) 347 - To "Dependencies" section, expand text that discusses 348 EGL_EXT_client_extensions. 349 350 Version 5, 2013.05.18 (Chad Versace) 351 - Removed restriction that "attribute names are defined only by 352 platform-specific extensions". 353 - Resolve issue 3 as NO. 354 - Clarified some text and fixed grammatical errors. 355 356 Version 4, 2013.05.14 (Chad Versace) 357 - Add <attrib_list> parameter to eglGetPlatformDisplayEXT, per 358 feedback at the April Khronos F2F. 359 360 Version 3, 2013.04.26 (Chad Versace) 361 - Add issues 2, 3, 4. 362 363 Version 2, 2013.03.24 (Chad Versace) 364 - Complete draft by adding text for pixmaps. 365 - The footnotes regarding undefined behavior, simplify them by 366 simply referring to section 3.1.0.2. 367 - Add issue 1 from Eric Anholt <eric@anholt.net>. 368 - Fix spelling and formatting errors. 369 370 Version 1, 2013.03.13 (Chad Versace) 371 - Incomplete draft posted for review 372