xref: /third_party/EGL/extensions/KHR/EGL_KHR_wait_sync.txt

Name

    KHR_wait_sync

Name Strings

    EGL_KHR_wait_sync

Contributors

    Jon Leech
    Tom Cooksey
    Alon Or-bach

Contacts

    Jon Leech (jon 'at' alumni.caltech.edu)

Notice

    Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Status

    Complete.
    Approved by the Khronos Board of Promoters on October 26, 2012.

Version

    Version 7, March 12, 2014

Number

    EGL Extension #43

Dependencies

    EGL 1.1 is required.

    EGL_KHR_fence_sync is required.

    EGL_KHR_reusable_sync is affected by this extension.

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

Overview

    This extension adds the ability to wait for signaling of sync objects
    in the server for a client API context, rather than in the application
    thread bound to that context. This form of wait does not necessarily
    block the application thread which issued the wait (unlike
    eglClientWaitSyncKHR), so the application may continue to issue commands
    to the client API context or perform other work in parallel, leading to
    increased performance. The best performance is likely to be achieved by
    implementations which can perform this new wait operation in GPU
    hardware, although this is not required.

New Types

    None

New Procedures and Functions

    EGLint eglWaitSyncKHR(
                  EGLDisplay dpy,
                  EGLSyncKHR sync,
                  EGLint flags)

New Tokens

    None

Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)

    Add to section 3.8.1 "Sync Objects" (as already modified
    by EGL_KHR_fence_sync and/or EGL_KHR_reusable_sync):

    Following the description of eglClientWaitSyncKHR, add:

   "The command

        EGLint eglWaitSyncKHR(EGLDisplay dpy,
                              EGLSyncKHR sync,
                              EGLint flags)

    is similar to eglClientWaitSyncKHR, but instead of blocking and not
    returning to the application until <sync> is signaled, eglWaitSyncKHR
    returns immediately. On success, EGL_TRUE is returned, and the server
    for the client API context [fn1] will block until <sync> is signaled
    [fn2].
       [fn1 - the server may choose to wait either in the CPU executing
        server-side code, or in the GPU hardware if it supports this
        operation.]
       [fn2 - eglWaitSyncKHR allows applications to continue to queue
        commands from the application in anticipation of the sync being
        signaled, potentially increasing parallelism between application,
        client API server code, and the GPU. The server only blocks
        execution of commands for the specific context on which
        eglWaitSyncKHR was issued; other contexts implemented by the same
        server are not affected.]

    <sync> has the same meaning as for eglClientWaitSyncKHR.

    <flags> must be 0.

    Errors
    ------
    eglWaitSyncKHR returns EGL_FALSE on failure and generates an error as
    specified below, but does not cause the server for the client API
    context to block.

      * If the current context for the currently bound client API does not
        support the client API extension indicating it can perform server
        waits, an EGL_BAD_MATCH error is generated.
      * If no context is current for the currently bound client API (i.e.,
        eglGetCurrentContext returns EGL_NO_CONTEXT), an EGL_BAD_MATCH error
        is generated.
      * If <dpy> does not match the EGLDisplay passed to eglCreateSyncKHR
        when <sync> was created, the behavior is undefined.
      * If <sync> is not a valid sync object for <dpy>, an EGL_BAD_PARAMETER
        error is generated.
      * If <flags> is not 0, an EGL_BAD_PARAMETER error is generated.

    Each client API which supports eglWaitSyncKHR indicates this support in
    the form of a client API extension. If the GL_OES_EGL_sync extension is
    supported by any version of OpenGL ES, a server wait may be performed
    when the currently bound API is OpenGL ES. If the VG_KHR_EGL_sync
    extension is supported by OpenVG, a server wait may be performed when
    the currently bound API is OpenVG."

    Add new subsubsection following eglWaitSyncKHR:

   "Multiple Waiters
    ----------------

    It is possible for the application thread calling a client API to be
    blocked on a sync object in a eglClientWaitSyncKHR command, the server
    for that client API context to be blocked as the result of a previous
    eglWaitSyncKHR command, and for additional eglWaitSyncKHR commands to be
    queued in the server, all for a single sync object. When the sync object
    is signaled in this situation, the client will be unblocked, the server
    will be unblocked, and all such queued eglWaitSyncKHR commands will
    continue immediately when they are reached.

    Sync objects may be waited on or signaled from multiple contexts of
    different client API types in multiple threads simultaneously, although
    some client APIs may not support eglWaitSyncKHR. This support is
    determined by client API-specific extensions."

    Additions to the EGL_KHR_reusable_sync extension, modifying the description
    of eglSignalSyncKHR to include both client and server syncs:

   "... If as a result of calling eglSignalSyncKHR the status of <sync>
    transitions from unsignaled to signaled, any eglClientWaitSyncKHR
        * or eglWaitSyncKHR *
    commands blocking on <sync> will unblock. ..."

    Additions to the EGL_KHR_reusable_sync extension, modifying the description
    of eglDestroySyncKHR to include both client and server syncs:

   "... If any eglClientWaitSyncKHR
        * or eglWaitSyncKHR *
    commands are blocking on <sync> when eglDestroySyncKHR is called, they
    will be woken up, as if <sync> were signaled."


    Additions to the EGL_KHR_fence_sync extension, modifying the description
    of eglCreateSyncKHR to include both client and server syncs:

   "... causing any eglClientWaitSyncKHR 
        * or eglWaitSyncKHR *
    commands (see below) blocking on <sync> to unblock ..."

    Additions to the EGL_KHR_fence_sync extension, modifying the description
    of eglDestroySyncKHR to include both client and server syncs:

   "... If any eglClientWaitSyncKHR
        * or eglWaitSyncKHR *
    commands are blocking on <sync> when eglDestroySyncKHR is called, <sync>
    is flagged for deletion and will be deleted when it is no longer
    associated with any fence command and is no longer blocking any
    eglClientWaitSyncKHR or eglWaitSyncKHR commands."


Issues

    1. Explain the key choices made in this extension.

    RESPONSE: This extension has been written to behave as similarly as
    possible to the glWaitSync functionality available in desktop OpenGL.
    Server waits are functionality which was only available in GL syncs
    until now.

    In the interest of maintaining similarity with OpenGL sync objects, this
    extension attempts to copy the glWaitSync functionality of OpenGL
    wherever possible (both functionally and stylistically), only making
    changes where needed to operate inside EGL (rather than a client API
    context) and match EGL naming conventions.

    2. Must all EGL client APIs support server waits?

    PROPOSED: Only if the client APIs also support fence syncs, which also
    interacts with the server for that client API. The same client API
    extensions defining fence sync support (GL_OES_EGL_sync and
    VG_KHR_EGL_sync) are used here to indicate server wait ability for those
    client APIs.

    Reusable syncs in EGL_KHR_reusable_sync do not have this dependency,
    because it is (at least in principle) possible for eglClientWaitSyncKHR
    to be performed entirely within the EGL implementation. However,
    eglWaitSyncKHR requires cooperation of the client API, whether fence
    syncs or reusable syncs are being waited upon.

    It would be possible to completely decouple fence syncs and the ability
    to do server waits, but this would require new client API extensions.

    3. What is the relationship between EGL sync objects and OpenGL / OpenGL
    ES sync objects?

    RESPONSE: There is no direct relationship. GL and ES servers may not
    even implement sync objects as defined by some versions of those APIs.
    However, EGL sync objects are intended to be functionally equivalent to
    GL sync objects, and the language describing them is drawn from the GL
    specifications. Implementations supporting both forms of sync object
    will probably use the same implementation internally.

    4. Should eglWaitSyncKHR take a timeout as a parameter as its equivalent
    in OpenGL / OpenGL ES and eglWaitClientKHR does?

    PROPOSED: No. A timeout is of limited use to a well-behaved application.
    If a timeout was added, the result of it expiring is likely to be a
    corrupted output. Adding a timeout would likely necessitate a way to
    query if the wait completed because the condition was signaled or
    because of a timeout. There doesn't seem to be an obvious, elegant API
    mechanism to do that. If a timeout is needed in the future, it can be
    added via an additional extension with a new entry-point.

    5. What happens if an application issues a server-side wait on a fence
    which never gets signaled?

    RESPONSE: Further rendering in the context which issued the server-side
    wait will not progress. Any additional behavior is undefined and is
    likely to be different depending on a particular implementation. Could
    be handled in the same way as an extremely long-running GLSL shader.

    6. Does this extension affect the destruction behavior?

    RESOLVED: No. The behavior of eglDestroySyncKHR is determined by the type
    of sync object, and is not affected by this extension.

Revision History

#7   (Alon Or-bach, March 12, 2014)
   - Clarified that eglDestroySyncKHR behavior is set in 
     EGL_KHR_fence_sync / EGL_KHR_reusable_sync and is not modified by this
     extension (bug 11458).
#6   (Jon Leech, January 24, 2013)
   - eglWaitSyncKHR causes a server wait in OpenGL ES when GL_OES_EGL_sync
     is supported, not a client wait as formerly specified (Bug 9493).
#5   (Jon Leech, October 31, 2012)
   - Change return type of eglWaitSyncKHR in spec body to EGLint to match
     New Functions section, and rearrange description of return type and
     errors section for clarity.
#4   (Tom Cooksey, August 16, 2012)
   - Removed timeout parameter and text relating to it. Add issue 4
     discussing timeout parameter. Add issue 5 explaining the behavior of
     waiting on a never-signaled fence. Minor corrections to use US English.
#3   (Jon Leech, June 26, 2012)
   - Fix typos (bug 9137).
#2   (Jon Leech, June 20, 2012)
   - Clarifications and language cleanup (Bug 9137). Some paragraph
     reflowing. Note that eglWaitSyncKHR only blocks the server for the
     specific context on which the wait was issued. Add issue 3 discussing
     relationship to GL/ES sync objects.
#1   (Jon Leech, June 6, 2012)
   - Initial draft branched from GL 4.x API spec language.