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 is signaled, eglWaitSyncKHR returns immediately. On success, EGL_TRUE is returned, and the server for the client API context [fn1] will block until 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.] has the same meaning as for eglClientWaitSyncKHR. 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 does not match the EGLDisplay passed to eglCreateSyncKHR when was created, the behavior is undefined. * If is not a valid sync object for , an EGL_BAD_PARAMETER error is generated. * If 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 transitions from unsignaled to signaled, any eglClientWaitSyncKHR * or eglWaitSyncKHR * commands blocking on 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 when eglDestroySyncKHR is called, they will be woken up, as if 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 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 when eglDestroySyncKHR is called, 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.