summaryrefslogtreecommitdiff
path: root/glew/auto/EGL-Registry/extensions/EXT/EGL_EXT_platform_base.txt
diff options
context:
space:
mode:
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.txt371
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