[Mesa-dev] [RFC] Changing eglBindAPI in the EGL specification

[Chad Versace]

The EGL Work Group at Khronos is considering changing the semantics of
eglBindAPI(). Such a change would require a change in Mesa's EGL
implementation. I'd like to hear your feedback on the issue.


Proposal
========

Currently there are two distinct APIs for OpenGL and OpenGL ES:

    EGL_OPENGL_API
    EGL_OPENGL_ES_API

The currently bound API affects the following calls:

    eglGetCurrentContext
    eglGetCurrentSurface
    eglGetCurrentDisplay
    eglWaitClient
    eglWaitNative
    eglCreateContext
    eglMakeCurrent (when ctx is NO_CONTEXT)

The proposal is to change the behavior of these functions so that
EGL_OPENGL_ES_API and EGL_OPENGL_API are equivalent for all purposes except
eglCreateContext() (where it determines whether an OpenGL or OpenGL ES context
is created).

There appears to be consensus within the EGL Work Group to adopt the proposal
and update the EGL specification accordingly.  However, this change to the
spec would require a change to Mesa's EGL implementation. I'm in favor of the
proposal, but want to receive feedback from Mesa's EGL stakeholders before
proceeding with the change.


Mesa's Current Behavior
=======================

A strict reading of the EGL spec mandates certain unintuitive, and I claim
undesirable, behavior regarding the the interaction among the bound API and
the above functions. Mesa faitfully implements that undesirable behavior, just
as the spec mandates.


Example 1
---------
Suppose the following. Thread #1 calls eglBindAPI(EGL_OPENGL_API) and then
creates an OpenGL context. Thread #2 binds the context with eglMakeCurrent and
begins rendering.  It later calls eglWaitClient. The spec requires that on
initialization of a thread the bound API is EGL_OPENGL_ES_API, if the
driver supports that API. If thread #2 has never bound EGL_OPENGL_API, then
the call to eglWaitClient is a no-op. The application now has a bug due to
some undesirable subtlety in the EGL spec.

    // thread #1
    eglBindAPI(EGL_OPENGL_API);
    gl_ctx = eglCreateContext(...);

    // thread #2
    eglMakeCurrent(gl_ctx);
    // Do some rendering.
    eglWaitClient();
    // No waiting occurs. This likely causes an application bug.


Example 2
---------
Suppose that a thread has bound an OpenGL context with eglMakeCurrent and that
the currently bound API is EGL_OPENGL_ES.  Then an attempt to unbind the
context will be a no-op that silently succeeds. If the application relied on
the implicit flush that accompanies unbinding a context, then this likely
causes an application bug.

    eglBindAPI(EGL_OPENGL_API);
    gl_ctx = eglCreateContext(...);

    eglBindAPI(EGL_OPENGL_ES_API)
    gles_ctx = eglCreateContext(...);

    // Now it's time to use the GL context.
    eglMakeCurrent(gl_ctx);
    // Do some rendering.
    eglMakeCurrent(dpy, 0, 0, 0);
    // The ctx is still current! No flush occured.
    // This likely causes an application bug.