Name EXT_platform_base Name Strings EGL_EXT_platform_base Contributors Chad Versace James Jones Contacts Chad Versace Status Complete Version Version 9, 2014.01.09 Number EGL Extension #57 Extension Type EGL client extension Dependencies Requires EGL 1.4. Requires EGL_EXT_client_extensions to query its existence without a display. This extension is written against the wording of the 2013.02.11 revision of the EGL 1.4 Specification. Overview This extension defines functionality and behavior for EGL implementations that support multiple platforms at runtime. For example, on Linux an EGL implementation could support X11, Wayland, GBM (Generic Buffer Manager), Surface Flinger, and perhaps other platforms. In particular, this extension defines the following: 1. A mechanism by which an EGL client can detect which platforms the EGL implementation supports. 2. New functions that enable an EGL client to specify to which platform a native resource belongs when creating an EGL resource from that native resource. For example, this extension enables an EGL client to specify, when creating an EGLSurface from a native window, that the window belongs to X11. 3. That an EGL client is not restricted to interacting with a single platform per process. A client process can create and manage EGL resources from multiple platforms. The generic term 'platform' is used throughout this extension specification rather than 'window system' because not all EGL platforms are window systems. In particular, those platforms that allow headless rendering without a display server, such as GBM, are not window systems. This extension does not specify behavior specific to any platform, nor does it specify the set of platforms that an EGL implementation may support. Platform-specific details lie outside this extension's scope and are instead described by extensions layered atop this one. New Types None New Procedures and Functions EGLDisplay eglGetPlatformDisplayEXT( EGLenum platform, void *native_display, const EGLint *attrib_list); EGLSurface eglCreatePlatformWindowSurfaceEXT( EGLDisplay dpy, EGLConfig config, void *native_window, const EGLint *attrib_list); EGLSurface eglCreatePlatformPixmapSurfaceEXT( EGLDisplay dpy, EGLConfig config, void *native_pixmap, const EGLint *attrib_list); New Tokens None Additions to the EGL 1.4 Specification Replace each occurence of the term "window system" with "platform". The rationale behind this change is that not all platforms are window systems, yet the EGL 1.4 specification uses the two terms interchangeably. In particular, platforms that allow headless rendering without a display server, such as GBM, are not window systems. Append the following paragraph to the initial, unnamed subsection of section 2.1 "Native Window System and Rendering APIs". "This specification does not define the set of platforms that may be supported by the EGL implementation, nor does it specify behavior specific to any platform. The set of supported platforms and their behavior is defined by extensions. To detect if a particular platform is supported, clients should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using eglQueryString. Replace the text of section 3.2 "Initialization", from the start of the section and up to and excluding the phrase "EGL may be intialized on a display", with the following: "A display can be obtained by calling EGLDisplay eglGetPlatformDisplayEXT( EGLenum platform, void *native_display, const EGLint *attrib_list); EGL considers the returned EGLDisplay as belonging to the native platform specified by . This specification defines no valid value for . Any specification that does define a valid value for will also define requirements for the parameter. For example, an extension specification that defines support for the X11 platform may require that be a pointer to an X11 Display, and an extension specification that defines support for the Microsoft Windows platform may require that be a pointer to a Windows Device Context. All attribute names in are immediately followed by the corresponding desired value. The list is terminated with EGL_NONE. The is considered empty if either is NULL or if its first element is EGL_NONE. This specification defines no valid attribute names for . Multiple calls made to eglGetPlatformDisplayEXT with the same and will return the same EGLDisplay handle. An EGL_BAD_PARAMETER error is generated if has an invalid value. If is valid but no display matching is available, then EGL_NO_DISPLAY is returned; no error condition is raised in this case. A display can also be obtained by calling EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id); The behavior of eglGetDisplay is similar to that of eglGetPlatformDisplayEXT, but is specifided in terms of implementation- specific behavior rather than platform-specific extensions. As for eglGetPlatformDisplayEXT, EGL considers the returned EGLDisplay as belonging to the same platform as . However, the set of platforms to which is permitted to belong, as well as the actual type of , are implementation-specific. If is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls made to eglGetDisplay with the same will return the same EGLDisplay handle. If no display matching is available, EGL_NO_DISPLAY is returned; no error condition is raised in this case." In section 3.5.1 "Creating On-Screen Rendering Surfaces", replace the second paragraph, which begins with "Using the platform-specific type" and ends with "render into this surface", with the following: "Then call EGLSurface eglCreatePlatformWindowSurfaceEXT( EGLDisplay dpy, EGLConfig config, void *native_window, const EGLint *attrib_list); eglCreatePlatformWindowSurfaceEXT creates an onscreen EGLSurface and returns a handle to it. Any EGL context created with a compatible EGLConfig can be used to render into this surface. must belong to the same platform as , and EGL considers the returned EGLSurface as belonging to that same platform. The extension that defines the platform to which belongs also defines the requirements for the parameter." In the remainder of section 3.5.1, replace each occurrence of 'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'. Insert the sentence below after the first sentence of the last paragraph of section 3.5.1: "If and do not belong to the same platform, then undefined behavior occurs. [1]" Add the following footnote to section 3.5.1: "[1] See section 3.1.0.2 "Parameter Validation". Append the following to section 3.5.1: "An on-screen rendering surface may also be created by calling EGLSurface eglCreateWindowSurface( EGLDisplay dpy, EGLConfig config, EGLNativeWindowType win, const EGLint *attrib_list); The behavior of eglCreateWindowSurface is identical to that of eglCreatePlatformWindowSurfaceEXT except that the set of platforms to which is permitted to belong, as well as the actual type of , are implementation specific. In section 3.5.4 "Creating Native Pixmap Rendering Surfaces", replace the third paragraph, which begins with "Using the platform-specific type" and ends with "render into this surface", with the following: "Then call EGLSurface eglCreatePlatformPixmapSurfaceEXT( EGLDisplay dpy, EGLConfig config, void *native_pixmap, const EGLint *attrib_list); eglCreatePlatformPixmapSurfaceEXT creates an offscreen EGLSurface and returns a handle to it. Any EGL context created with a compatible EGLConfig can be used to render into this surface. must belong to the same platform as , and EGL considers the returned EGLSurface as belonging to that same platform. The extension that defines the platform to which belongs also defines the requirements for the parameter." In the remainder of section 3.5.4, replace each occurrence of 'eglCreatePixmapSurface' with 'eglCreatePlatformPixmapSurfaceEXT' and each occurence of 'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'. Insert the sentence below after the first sentence of the last paragraph of section 3.5.4: "If and do not belong to the same platform, then undefined behavior occurs. [1]" Add the following footnote to section 3.5.3: "[1] See section 3.1.0.2 "Parameter Validation". Append the following to section 3.5.2: "An offscreen rendering surface may also be created by calling EGLSurface eglCreatePixmapSurface( EGLDisplay dpy, EGLConfig config, EGLNativePixmapType pixmap, const EGLint *attrib_list); The behavior of eglCreatePixmapSurface is identical to that of eglCreatePlatformPixmapSurfaceEXT except that the set of platforms to which is permitted to belong, as well as the actual type of , are implementation specific. Issues 1. What rules define how EGL resources are shared among displays belonging to different platforms? RESOLVED: Neither the EGL 1.4 specification nor any extension allow EGL resources to be shared among displays. This extension does not remove that restriction. 2. Rather than define the new function eglGetPlatformDisplayEXT(), should this extension instead define new thread-local state for the currently bound platform and an associated binding function, such as eglBindPlatformEXT()? RESOLVED: No, for the following reasons. - A current trend among the Khronos workgroups is to remove use of global state by introducing bindless objects. Introducing a new thread-local binding point defies that trend. - Additional specification language would be required to define the interactions between the currently bound platform and all EGL functions that accept an EGLDisplay. (For example, if the currently bound platform is Wayland, then what is the result of calling eglCreateWindowSurface() with a display and native window belonging to X11?) By choosing to not introduce the notion of a "currently bound platform", we obtain a cleaner extension specification and eliminate for EGL users a class of potential bugs. 3. Should this extension define the notion of a default platform? RESOLVED: No. eglGetDisplay() can be used if a default platform is needed. 4. Rather than define the new functions eglCreatePlatform{Window,Pixmap}SurfaceEXT(), should we instead redefine the EGLNative* types in eglplatform.h as void*? RESOLVED: No, this introduces problems for X11 applications. Suppose that a 64-bit X11 application is compiled against an old EGL library (where EGLNativeWindowType is a typedef for XID, which is in turn a typedef for a 64-bit unsigned integer on Fedora 18) and then attempts to run against a new EGL library (where EGLNativeType is a typedef for void*). To preserve the ABI of eglCreateWindowSurface() in this situation, the new EGL library must re-interpret the parameter as an integer. However, this preservation of the ABI breaks source compatibility for existing X11 applications. To successfully compile, each call to eglCreateWindowSurface(dpy, window, attribs) in existing X11 application source code would need to be replaced with eglCreateWindowSurface(dpy, (void*) window, attribs) . Requiring such widespread code modifications would be an unnecessary burden to developers and Linux package maintainers. Revision History Version 9, 2014.01.09 (Jon Leech) - Fix typo eglGetDisplayPlatformEXT -> eglGetPlatformDisplayEXT Version 8, 2013.07.03 (Chad Versace) - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. Version 7, 2013.06.07 (Chad Versace) - Fix some awkward text (s/the EGL/EGL/). - Remove text "attribute names are defined by platform-specific extensions". Version 6, 2013.06.07 (Chad Versace) - To "Dependencies" section, expand text that discusses EGL_EXT_client_extensions. Version 5, 2013.05.18 (Chad Versace) - Removed restriction that "attribute names are defined only by platform-specific extensions". - Resolve issue 3 as NO. - Clarified some text and fixed grammatical errors. Version 4, 2013.05.14 (Chad Versace) - Add parameter to eglGetPlatformDisplayEXT, per feedback at the April Khronos F2F. Version 3, 2013.04.26 (Chad Versace) - Add issues 2, 3, 4. Version 2, 2013.03.24 (Chad Versace) - Complete draft by adding text for pixmaps. - The footnotes regarding undefined behavior, simplify them by simply referring to section 3.1.0.2. - Add issue 1 from Eric Anholt . - Fix spelling and formatting errors. Version 1, 2013.03.13 (Chad Versace) - Incomplete draft posted for review