xref: /third_party/EGL/extensions/EXT/EGL_EXT_platform_base.txt

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