[Mesa-dev] [RFC] EGL_MESA_platform_surfaceless

[Chad Versace]

Mesa's EGL has supported Chrome OS's "surfaceless" platform for many
months, but the behavior of that platform has never been documented.
Here's my attempt to fix that.

I wrote this as a patch to Mesa, but I intend to remove the copy in Mesa
after it enters the Khronos registry.

Here's my plan:
    1. Get feedback. Does this spec look reasonable to everyone?
    2. Commit extension spec to Mesa.
    3. Implement the spec (a tiny amount of code).
    4. Let it bake.
    5. Submit spec to Khronos registry.
    6. Delete Mesa's copy of the spec.
    7. Update Chrome to use eglGetPlatformDisplay(EGL_PLATFORM_SURFACELESS_MESA, ...).

---
 docs/specs/EGL_MESA_platform_surfaceless.txt | 108 +++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 docs/specs/EGL_MESA_platform_surfaceless.txt

diff --git a/docs/specs/EGL_MESA_platform_surfaceless.txt b/docs/specs/EGL_MESA_platform_surfaceless.txt
new file mode 100644
index 0000000..b700370
--- /dev/null
+++ b/docs/specs/EGL_MESA_platform_surfaceless.txt
@@ -0,0 +1,108 @@
+Name
+
+    MESA_platform_surfaceless
+
+Name Strings
+
+    EGL_MESA_platform_surfaceless
+
+Contributors
+
+    Chad Versace <chadversary at google.com>
+    Haixia Shi <hshi at google.com>
+    Stéphane Marchesin <marcheu at google.com>
+    Zach Reizner <zachr at google.com>
+
+Contacts
+
+    Chad Versace <chadversary at google.com>
+
+Status
+
+    DRAFT
+
+Version
+
+    Version 1, 2016-09-23
+
+Number
+
+    EGL Extension #TODO
+
+Extension Type
+
+    EGL client extension
+
+Dependencies
+
+    EGL 1.5 is required.
+
+    This extension is written against the EGL 1.5 Specification (draft
+    20140122).
+
+Overview
+
+    This extension defines a new EGL platform, the "surfaceless" platform. This
+    platfom's defining property is that it has no native surfaces, and hence
+    neither eglCreatePlatformWindowSurface nor eglCreatePlatformPixmapSurface
+    can be used. The platform is independent of any native window system.
+
+    The platform's intended use case is for enabling OpenGL and OpenGL ES
+    applications on systems where no window system exists. However, the
+    platform's permitted usage is not restricted to this case.  Since the
+    platform is independent of any native window system, it may also be used on
+    systems where a window system is present.
+
+New Types
+
+    None
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted as the <platform> argument of eglGetPlatformDisplay:
+
+        EGL_PLATFORM_SURFACELESS_MESA           0xTODO
+
+Additions to the EGL Specification
+
+    None.
+
+New Behavior
+
+    To determine if the EGL implementation supports this extension, clients
+    should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
+
+    To obtain an EGLDisplay on the surfaceless platform, call
+    eglGetPlatformDisplay with <platform> set to EGL_PLATFORM_SURFACELESS_MESA.
+    The <native_display> parameter must be EGL_DEFAULT_DISPLAY.
+
+    eglCreatePlatformWindowSurface fails when called with a <display> that
+    belongs to the surfaceless platform. It returns EGL_NO_SURFACE and
+    generates EGL_BAD_NATIVE_WINDOW. The justification for this unconditional
+    failure is that the surfaceless platform has no native windows, and
+    therefore the <native_window> parameter is always invalid.
+
+    Likewise, eglCreatePlatformPixmapSurface also fails when called with a
+    <display> that belongs to the surfaceless platform.  It returns
+    EGL_NO_SURFACE and generates EGL_BAD_NATIVE_PIXMAP.
+
+    The surfaceless platform imposes no platform-specific restrictions on the
+    creation of pbuffers, as eglCreatePbufferSurface has no native surface
+    parameter. In other words, eglCreatePbufferSurface behaves the same on the
+    surfaceless platform as it does on more traditional platforms, such as
+    EGL_KHR_platform_x11. Specifically, if the EGLDisplay advertises an
+    EGLConfig whose EGL_SURFACE_TYPE attribute contains EGL_PBUFFER_BIT, then
+    the EGLDisplay permits the creation of pbuffers.
+
+Issues
+
+    None.
+
+Revision History
+
+    Version 1, 2016-09-23 (Chad Versace)
+        - Initial version
-- 
2.10.0