Name
EXT_client_extensions
Name Strings
EGL_EXT_client_extensions
Contributors
Chad Versace <chad.versace@intel.com>
Ian Romanick <ian.d.romanick@intel.com>
Jakob Bornecrantz <jakob@vmware.com>
James Jones <jajones@nvidia.com>
Contacts
Chad Versace <chad.versace@intel.com>
Status
Complete
Version
Version 11, 2013.10.10
Number
EGL Extension #58
Extension Type
EGL client extension
Dependencies
Requires EGL 1.4.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension introduces the concept of *extension type*, requires that
each EGL extension belong to exactly one type, and defines two types:
display and client. It also provides a method to query, without
initializing a display, the set of supported client extensions.
A display extension adds functionality to an individual EGLDisplay. This
type of extension has always existed but, until EGL_EXT_client_extensions,
lacked an identifying name.
A client extension adds functionality that is independent of any display.
In other words, it adds functionality to the EGL client library itself. This
is a new type of extension defined by EGL_EXT_client_extensions.
EGL_EXT_client_extensions is itself a client extension.
We suggest that each future extension clearly state its type by including
the following toplevel section in its extension specification, preceding the
Dependencies section. For client extensions, this suggestion is
a requirement.
Extension Type
<Either "EGL display extension" or "EGL client extension" or
a future extension type.>
By cleanly separating display extensions from client extensions,
EGL_EXT_client_extensions solves a bootstrap problem for future EGL
extensions that will modify display initialization. To query for such
extensions without EGL_EXT_client_extensions, an EGL client would need to
initialize a throw-away EGLDisplay solely to query its extension string.
Initialization of the throw-away display may have undesired side-effects
(discussed in the issues section below) for EGL clients that wish to use the
new methods of display initialization.
New Types
None
New Procedures and Functions
None
New Tokens
None
Additions to the EGL 1.4 Specification:
Add the following section to Chapter 2 "EGL Operation":
"2.n Extensions
EGL implementations may expose additional functionality beyond that
described by this specification. Additional functionality may include new
functions, new enumerant values, and extended behavior for existing
functions. Implementations advertise such extensions to EGL by exposing
*extension strings*, which are queryable with eglQueryString.
Each EGL extension belongs to exactly one of the following types:
Display Extensions
A *display extension* adds functionality to an individual
EGLDisplay. Different instances of EGLDisplay may support different
sets of display extensions.
Client Extensions
A *client extension* adds functionality that is independent of any
display. In other words, it adds functionality to the EGL client
library itself. In a given process, there exists exactly one set,
possibly empty, of supported client extensions. When the client
extension string is first queried, that set becomes immutable."
Replace the paragraph in section 3.3 "EGL Versioning" that begins "The
EGL_EXTENSIONS string" with the following text:
"The EGL_EXTENSIONS string describes which set of EGL extensions are
supported. The string is zero-terminated and contains a space-separated
list of extension names; extension names themselves do not contain spaces.
If there are no extensions to EGL, then the empty string is returned.
If <dpy> is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set
of supported client extensions. If <dpy> is a valid, initialized display,
then the EGL_EXTENSIONS string describes the set of display extensions
supported by the given display. The set of supported client extensions is
disjoint from the set of extensions supported by any given display [fn].
[fn] This is a consequence of the requirement in Section 2.n Extensions that
each extension belong to exactly one extension type."
Replace the last paragraph of section 3.3 "EGL Versioning" with:
"On failure, NULL is returned. An EGL_BAD_DISPLAY error is generated if
<dpy> is not a valid display, unless <dpy> is EGL_NO_DISPLAY and <name> is
EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if <dpy> is
a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated
if <name> is not one of the values described above."
Conformance Tests
1. Before any call to eglGetDisplay, call `eglQueryString(EGL_NO_DISPLAY,
EGL_EXTENSIONS)`. Verify that either
a. The call returns NULL and generates EGL_BAD_DISPLAY.
b. The call returns an extension string that contains, at a minimum,
this extension and generates no error.
2. Obtain a display with eglGetDisplay but do not initialize it. Verity
that passing the uninitialized display to `eglQueryString(dpy,
EGL_EXTENSIONS)` returns NULL and generates EGL_NOT_INITIALIZED.
3. Obtain a list of display extensions by calling `eglQueryString(dpy,
EGL_EXTENSIONS)` on an initialized display. Obtain the list of client
extensions by calling `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`.
If both calls succeed, verify the two lists are disjoint.
Issues
1. How should clients detect if this extension is supported?
RESOLVED: If an EGL implementation supports this extension, then
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` returns
a well-formed extension string and generates no error. Otherwise, it
returns NULL and generates EGL_BAD_DISPLAY.
2. On EGL platforms that define EGL_NO_DISPLAY as NULL, does not calling
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` risk a null pointer
dereference? Therefore, how is it possible on such platforms for
a client to safely detect if this extension is supported?
RESOLVED: According to the EGL 1.4 specification, calling
`eglQueryString(EGL_NO_DISPLAY, name)` returns NULL and generates
EGL_BAD_DISPLAY. No null pointer dereference occurs even if the
platform defines EGL_NO_DISPLAY as NULL.
3. What existing extensions should returned by
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`?
RESOLVED: Possibly EGL_NV_system_time.
4. What should be the relationship between the extension string of
EGL_NO_DISPLAY and the extension string of a valid display? That is,
should the former be a subset of the latter? Should the two be
disjoint? Should the relationship remain undefined?
Another phrasing of this issue is: When, if ever, should client
extensions appear in a display's extension string?
RESOLVED: The extension string of EGL_NO_DISPLAY must be disjoint
from the extension string of any valid display. That is, EGL_NO_DISPLAY
must advertise only client extensions, and valid displays must not
advertise client extensions. By defining a clear relationship between
the two types of extension strings, we enforce consistent behavior among
implementations, thus preventing possible confusion from application
developers.
DISCUSSION: This resolution has special implications for systems where
libEGL is a vendor-independent library that loads and then dispatches
to the appropriate vendor-provided EGL library. The resolution requires
that client extensions, as well the construction of extension strings,
be at least partially implemented in the vendor-independent library.
The alternative resolution of mandating the 'superset' relation (that
is, that the extension string of a valid display must be a superset of
that of EGL_NO_DISPLAY) was rejected due to potential confusion on
behalf of the application developer as well as the driver implementer.
What follows is an example of each.
a) Suppose an EGL implementation supported creation of
a software-renderer EGLDisplay through a client extension named
EGL_XYZ_platform_software_renderer. If the 'superset' relation were
mandated, then each display, whether it were hardware-accelerated or
software-only, would advertise the EGL_XYZ_platform_software_renderer
extension string. This would likely confuse application developers.
b) If the 'superset' relation were mandated, then the possibility
exists that a vendor would ship a hybrid extension that is both
a client extension and a display extension. Such a hybrid extension
poses subtle difficulties for systems where libEGL is
a vendor-independent library that dispatches to the appropriate
vendor-provided EGL driver. On such a system, the extension's hybrid
nature may require that each vendor-provided EGL driver support the
extension before the vendor-independent EGL library could safely
expose the extension. By choosing the 'disjoint' relation rather
than 'superset', we prevent this problematic situation from
occuring.
5. Should client extension specifications explicitly state they are
returned in the extension string of EGL_NO_DISPLAY?
RESOLVED: Yes. Enforce this by requiring that client extension
specifications contain the toplevel section "Extension Type".
6. As explained in the overview section, this "extension solves
a bootstrap problem for future EGL extensions that modify display
initialization". What solutions to the bootstrap problem were
considered? Why was EGL_EXT_client_extensions chosen as the best
solution?
DISCUSSION: First let's discuss the exact nature of the bootstrap
problem and of the future EGL extensions that modify display
initialization.
Mesa's EGL implementation supports multiple native platforms (such as
Wayland, GBM, and X11) at runtime, and we expect that more
implementations will do so in the future. The EGL API is deficient for
such implementations because it does not yet provide a way for clients
to query the set of supported native platforms. Also, EGL provides no
way for clients to specify to which platform the native display belongs
during display initialization. (That is, eglGetDisplay has a native
display parameter, but no parameter specifying the native platform).
Future EGL extensions, currently under progress, will solve these
deficiencies in the EGL API by (1) adding a variant of eglGetDisplay
that allows specification of the platform to which the native display
belongs and (2) by advertising the set of native platforms supported by
the implementation.
However, there exists a bootstrap problem here. To query if a given
native platform is supported, the EGL client must initialize an
EGLDisplay to query its extension string. But, not yet knowing which
native platforms the EGL implementation supports, the client cannot
safely pass any native display to eglGetDisplay, and therefore cannot
obtain an extension string.
The following solutions to this bootstrap problem have been considered.
For conciseness, let's refer to the future EGL extensions that modify
display initialization as "client extensions".
1. PROPOSED SOLUTION: To determine if an EGL implementation supports
a given client extension, require that the EGL client call
eglGetProcAddress on some function defined by the extension. If
eglGetProcAddress returns non-null, then the implementation
supports the extension.
ANALYSIS: The EGL 1.4 spec permits eglGetProcAddress to return
non-null for unrecognized function names. Therefore, this
solution's method may produce false positives on some
implementations.
Also, this solution does not permit detection of client extensions
that add no new functions.
2. PROPOSED SOLUTION: To determine if an EGL implementation supports
a given client extension, the EGL client should examine the
extension string of EGL_DEFAULT_DISPLAY. Querying
EGL_DEFAULT_DISPLAY is a failsafe mechanism by which the EGL
client can obtain an extension string, because EGL_DEFAULT_DISPLAY
is a valid input to eglGetDisplay regardless of which platforms
the EGL implementation supports.
ANALYSIS: This solution is awkward. It requires that the client
initialize a throw-away EGLDisplay solely to query its extension
string, even though the desired extension is not a property of any
display but of the EGL library itself.
This solution also has a subtle fatal problem. It is not backwards
compatible with Mesa. As of 2013-06-07, Mesa's EGL implementation
stores at runtime a user-chosen native platform in global
write-once state. Calling eglGetDisplay is one action that
results in writing to that state. Therefore, if a client process
running on such a problematic version of Mesa initialized
EGL_DEFAULT_DISPLAY solely to detect some client extension, then
the client process would be confined for its lifetime to use only
that platform to which EGL_DEFAULT_DISPLAY belongs. This
confinement may be fatal if the process had wanted to use
a different platform.
3. PROPOSED SOLUTION: Abandon the concept of client extensions.
Instead, in implementations that support multiple window systems
at runtime, eglGetDisplay should autodetect the platform to which
the native display belongs. A suitable error should be generated
if an unsupported native display is passed to eglGetDisplay.
ANALYSIS: For some native platforms, the display type is opaque
with no defined ABI. (For example, in libX11 the 'Display' type is
an opaque typedef). There exists no method by which eglGetDisplay
could reliably detect that the given native display belongs to
such a platform.
This solution also has a subtle fatal problem. The client
extensions will likely specify that an EGL client may create EGL
resources from multiple platforms in the same process. But, Mesa's
global write-once state, mentioned above, prevents using multiple
platforms in one process. Therefore, under this proposed solution
and on a system where a problematic version of Mesa is installed,
the client would be unable to detect if EGL supported multiple
platforms per process without committing to the platform to which
the first initialized display belonged.
4. ACCEPTED SOLUTION: Allow the EGL client to query the extension
string of EGL_NO_DISPLAY, which would contain the client
extensions.
ANALYSIS: This solution does not require the initialization of
a throw-away EGLDisplay, nor does it require that native display
types have a fixed ABI.
This is the solution described by this extension specification,
EGL_EXT_client_extensions.
Revision History
Version 11, 2013.10.10 (Chad Versace)
- Fix conformance test #3. It should require that the display extension
list be disjoint to rather than a superset of the client extension
list. (The 'superset' requirement was changed pre-publication to
'disjoint' in version 8).
Version 10, 2013.07.03 (Chad Versace)
- Version 9 and 10 are identical due to a versioning error.
Version 9, 2013.07.03 (Chad Versace)
- Define the concept of *extension type*, require require that each EGL
extension belong to exactly one type, and define two types: display
and client.
- Suggest new section "Extension Type" for future extension
specifications.
- Add new section 2.n Extensions.
- Simplify modifications to section 3.3 by using the new extension type
terminology.
Version 8, 2013.07.01 (Chad Versace)
- Change resolution of Issue 4 from the 'superset' relation to the
'disjoint' relation, according to discussion with Jakob Bornecrantz.
Acked by James Jones.
Version 7, 2013.06.10 (Chad Versace)
- Fix typos.
s/unitialized/uninitialized/
s/EGL_NO_EXTENSIONS/EGL_EXTENSIONS/
Version 6, 2013.06.07 (Chad Versace)
- Remove the Motivation section, merging its content into the Overview
section and Issue 6.
Version 5, 2013.06.07 (Chad Versace)
- Resolve issue 3 regarding classifying currently published extensions
as client extensions.
- Resolve issue 4 regarding the relationship among client and display
extension strings.
- Add and resolve issue 5, requiring client extension specifications
to contain language about the EGL_NO_DISPLAY extension string.
Version 4, 2013.05.14 (Chad Versace)
- Add issue 4.
Version 3, 2013.03.24 (Chad Versace)
- Fix conformance test condition 1.b. The returned extension string
should list, at a minimum, this extension. [Found by Ian Romanick].
- Add section "Movivation". [Requested by Ian Romanick].
Version 2, 2013.03.06 (Chad Versace)
- Remove enum EGL_CLIENT_EXTENSIONS_EXT. Reuse EGL_EXTENSIONS for that
purpose.
- To obtain client extensions, require the eglQueryString be called
with dpy=EGL_NO_DISPLAY rather than dpy=NULL. [Suggested by James
Jones].
- Add descriptions of conformance tests. [Suggested by Ian Romanick].
- Add sections "Overview" and "Issues".
Version 1, 2013.03.06 (Chad Versace)
- First draft
# vim: filetype=text expandtab autoindent shiftwidth=4 textwidth=80:
