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
