EXT_client_extensions

EGL_EXT_client_extensions

Chad Versace <chad.versace@intel.com>
Ian Romanick <ian.d.romanick@intel.com>
Jakob Bornecrantz <jakob@vmware.com>
James Jones <jajones@nvidia.com>

Chad Versace <chad.versace@intel.com>

Complete

Version 11, 2013.10.10

EGL Extension #58

EGL client extension

Requires EGL 1.4.

This extension is written against the wording of the EGL 1.4
Specification.

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.

None

None

None

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."

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.

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.

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