diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt new file mode 100644 index 0000000..aeef96c --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_wait_sync.txt @@ -0,0 +1,278 @@ +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. |