diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt')
-rw-r--r-- | glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt new file mode 100644 index 0000000..80bd1bc --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt @@ -0,0 +1,371 @@ +Name + + EXT_platform_base + +Name Strings + + EGL_EXT_platform_base + +Contributors + + Chad Versace <chad.versace@intel.com> + James Jones <jajones@nvidia.com> + +Contacts + + Chad Versace <chad.versace@intel.com> + +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 <platform>. This specification defines no valid value for + <platform>. Any specification that does define a valid value for + <platform> will also define requirements for the <native_display> + parameter. For example, an extension specification that defines support + for the X11 platform may require that <native_display> be a pointer to an + X11 Display, and an extension specification that defines support for the + Microsoft Windows platform may require that <native_display> be a pointer + to a Windows Device Context. + + All attribute names in <attrib_list> are immediately followed by the + corresponding desired value. The list is terminated with EGL_NONE. The + <attrib_list> is considered empty if either <attrib_list> is NULL or if + its first element is EGL_NONE. This specification defines no valid + attribute names for <attrib_list>. + + Multiple calls made to eglGetPlatformDisplayEXT with the same <platform> + and <native_display> will return the same EGLDisplay handle. + + An EGL_BAD_PARAMETER error is generated if <platform> has an invalid value. + If <platform> is valid but no display matching <native_display> 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 <display_id>. However, the set of + platforms to which <display_id> is permitted to belong, as well as the + actual type of <display_id>, are implementation-specific. If <display_id> + is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls + made to eglGetDisplay with the same <display_id> will return the same + EGLDisplay handle. If no display matching <display_id> 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. + + <native_window> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_window> 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 <dpy> and <native_window> 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 <dpy> is permitted to belong, as well as the actual type of <win>, + 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. + + <native_pixmap> must belong to the same platform as <dpy>, and EGL + considers the returned EGLSurface as belonging to that same platform. The + extension that defines the platform to which <dpy> belongs also defines + the requirements for the <native_pixmap> 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 <dpy> and <native_pixmap> 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 <dpy> is permitted to belong, as well as the actual type of + <pixmap>, 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 + <native_window> 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 <attrib_list> 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 <eric@anholt.net>. + - Fix spelling and formatting errors. + + Version 1, 2013.03.13 (Chad Versace) + - Incomplete draft posted for review |