Name EXT_client_extensions Name Strings EGL_EXT_client_extensions Contributors Chad Versace Ian Romanick Jakob Bornecrantz James Jones Contacts Chad Versace 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 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 is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set of supported client extensions. If 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 is not a valid display, unless is EGL_NO_DISPLAY and is EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if is a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated if 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: