blob: aeef96c714a920261da810369abdeed6c8a3b690 [file] [log] [blame]
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.