Name | |
EXT_sync_reuse | |
Name Strings | |
EGL_EXT_sync_reuse | |
Contributors | |
Daniel Kartch | |
Jeff Vigil | |
Ray Smith | |
Contacts | |
Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) | |
Status | |
Complete | |
Version | |
Version 4, May 16, 2018 | |
Number | |
EGL Extension #128 | |
Extension type | |
EGL display extension | |
Dependencies | |
Requires EGL 1.5 or EGL 1.4 with EGL_KHR_fence_sync | |
Interacts with EGL_KHR_reusable_sync | |
Interacts with EGL_ANDROID_native_fence_sync | |
Interacts with EGL_NV_cuda_event | |
This extension is written against the wording of the EGL 1.5 | |
Specification. | |
Overview | |
The original EGLSync extensions separated sync objects into two | |
types: fence sync objects signaled by one time events in an | |
API command pipeline; and reusable sync objects signaled by commands | |
which can be issued again and again. However, this conflates | |
reusability of the event triggering a sync object with the EGLSync | |
object itself. | |
Although the event associated with a fence sync object will only | |
occur once, there is no reason that it can't be replaced with a new | |
event. Doing so would avoid unnecessary allocation and free | |
operations in an application that repeatedly waits for events. With | |
the current interfaces, such applications must constantly create and | |
destroy new EGLSync objects. | |
This extension allows all sync objects to be reusable. When a sync | |
object is in the signaled state, it can be reset back to an | |
unsignaled state, regenerating or reevaluating the events that | |
trigger them. For fence sync objects, this means generating a new | |
fence in the current API. For OpenCL event sync objects, this means | |
waiting for a new OpenCL event handle. This mechanism also allows | |
sync objects to be created in the signaled state with no associated | |
fence/event, and have one applied later. Thus all EGLSyncs required | |
by an application can be allocated up front, before any rendering | |
operations have begun. | |
New Types | |
None | |
New Tokens | |
None | |
New Procedures and Functions | |
EGLBoolean eglUnsignalSyncEXT( | |
EGLDisplay dpy, | |
EGLSync sync, | |
const EGLAttrib *attrib_list); | |
Replace text of subsections of 3.8.1 through 3.8.1.2 of EGL 1.5 | |
Specification. Existing tables are preserved. | |
3.8.1 Sync Objects | |
In addition to the aforementioned synchronization functions, which | |
provide an efficient means of serializing client and native API | |
operations within a thread, <sync objects> are provided to enable | |
synchronization of client API operations between threads and/or | |
between API contexts. Sync objects may be tested or waited upon by | |
application threads. | |
Sync objects have a status with two possible states: <signaled> and | |
<unsignaled>, and may initially be in either state. EGL may be asked | |
to wait for a sync object to become signaled, or a sync objects | |
status may be queried. | |
Depending on the type of a sync object, its status may be changed | |
either by an external event, or by explicitly signaling and/or | |
unsignaling the sync. All sync objects are reusable. Once they enter | |
the signaled state, they may be changed back to unsignaled, possibly | |
replacing the associated external event that signals them. | |
Sync objects are associated with an EGLDisplay when they are | |
created, and have <attributes> defining additional aspects of the | |
sync object. All sync objects include attributes for their type and | |
their status. Additional attributes are discussed below for | |
different types of sync objects. If a sync object is created in the | |
signaled state, its initial attribute list may be incomplete, with | |
attributes necessary for its type provided when it is changed to | |
unsignaled. | |
<Fence sync objects> have an associated fence command in a client | |
API. A new fence command is generated whenever the sync object | |
enters the unsignaled state. When the client API executes the fence | |
command, an event is generated which signals the corresponding fence | |
sync object. Fence sync objects may not be explicitly signaled. | |
Fence sync objects may be used to wait for partial completion of a | |
client API command stream, as a more flexible form of glFinish or | |
vgFinish. | |
An <OpenCL event sync object> reflects the status of a corresponding | |
OpenCL event object to which the sync object is linked. This | |
provides another method of coordinating sharing of images between | |
EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and | |
the cl_khr_egl_image extension). Waiting on such a sync object is | |
equivalent to waiting for completion of the linked OpenCL event | |
object. | |
The command | |
EGLSync eglCreateSync(EGLDisplay dpy, EGLenum type, const | |
EGLAttrib *attrib_list); | |
creates a sync object of the specified <type> associated with the | |
specified display <dpy>, and returns a handle to the new object. | |
<attrib list> is NULL or an attribute-value list specifying other | |
attributes of the sync object, terminated by an attribute entry | |
EGL_NONE. Attributes not specified in the list will be assigned | |
their default values. | |
The EGL_SYNC_STATUS attribute is defined for all sync types, but may | |
only be specified explicitly at creation time for some types of sync | |
objects, as discussed below. Other attributes are only allowed as | |
indicated below for the sync type. | |
Errors | |
eglCreateSync returns EGL_NO_SYNC on failure. | |
If <dpy> is not the name of a valid, initialized EGLDisplay, an | |
EGL_BAD_DISPLAY error is generated. | |
If <attrib_list> contains an attribute name not defined or not | |
allowed for the type of sync object being created, an | |
EGL_BAD_ATTRIBUTE error is generated. | |
If <type> is not a supported type of sync object, an | |
EGL_BAD_PARAMETER error is generated. | |
If <type> is EGL_SYNC_FENCE, the EGL_SYNC_STATUS attribute is | |
set to EGL_UNSIGNALED, and any of the following are true of the | |
current context for the bound API (the context returned by | |
eglGetCurrentContext), an EGL_BAD_MATCH error is generated: | |
* There is no current context (i.e., eglGetCurrentContext | |
returns EGL_NO_CONTEXT). | |
* <dpy> does not match the EGLDisplay of the context (the | |
EGLDisplay returned by eglGetCurrentDisplay). | |
* The context does not support fence commands. | |
While in the unsignaled state, the synchronization event associated | |
with a sync object cannot be changed. When the <condition> of a sync | |
object in the unsignaled state is satisfied, the sync is signaled, | |
causing any eglClientWaitSync or eglWaitSync commands (see below) | |
blocking on the sync to unblock. | |
Once signaled, a sync object may be reused for a new synchronization | |
event by switching it back to unsignaled. The command | |
EGLBoolean eglUnsignalSyncEXT(EGLDisplay dpy, EGLSync sync, | |
const EGLAttrib *attrib_list); | |
can be used to change the <sync> associated with display <dpy> from | |
the signaled state to the unsignaled state. The attribute list may | |
be used to provide or replace attributes specific to the sync type | |
as discussed below. The sync object's type and condition may not be | |
changed. | |
Errors | |
eglUnsignalSyncEXT returns EGL_FALSE on failure, and has no | |
effect on <sync>. | |
If <dpy> is not the name of a valid, initialized EGLDisplay, an | |
EGL_BAD_DISPLAY error is generated. | |
If <sync> is not a valid sync object associated with <dpy>, an | |
EGL_BAD_PARAMETER error is generated. | |
If <attrib_list> contains an attribute name not defined for the | |
type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. | |
If <sync> is already in the unsignaled state, an EGL_BAD_ACCESS | |
error is generated. | |
If <sync>'s type is EGL_SYNC_FENCE and any of the following are | |
true of the current context for the bound API (the context | |
returned by eglGetCurrentContext), an EGL_BAD_MATCH error is | |
generated: | |
* There is no current context (i.e., eglGetCurrentContext | |
returns EGL_NO_CONTEXT). | |
* <dpy> does not match the EGLDisplay of the context (the | |
EGLDisplay returned by eglGetCurrentDisplay). | |
* The context does not support fence commands. | |
If <sync>'s type is EGL_SYNC_CL_EVENT and EGL_CL_EVENT_HANDLE | |
is not specified in <attrib_list>, then an EGL_BAD_ATTRIBUTE | |
error is generated. | |
3.8.1.1 Creating and Signaling Fence Sync Objects | |
If type is EGL_SYNC_FENCE, a fence sync object is created. The | |
EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED | |
or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other | |
attributes may be specified for a fence sync object, either with | |
eglCreateSync or eglUnsignalSyncEXT. Queriable attributes of the | |
fence sync object are set as shown in table 3.7. | |
When a fence sync object is created in the unsignaled state, or | |
switched to that state with eglUnsignalSyncEXT, a fence command is | |
inserted into the command stream of the bound client APIs current | |
context (i.e., the context returned by eglGetCurrentContext), and is | |
associated with the sync object. | |
The only condition supported for fence sync objects is | |
EGL_SYNC_PRIOR_COMMANDS_COMPLETE, which is satisfied by completion | |
of the fence command corresponding to the sync object, and all | |
preceding commands in the associated client API contexts command | |
stream. The sync object will not be signaled until all effects from | |
these commands on the client APIs internal and framebuffer state | |
are fully realized. No other state is affected by execution of the | |
fence command. | |
Generation of fence commands for fence sync objects requires support | |
from the bound client API, and will not succeed unless the client | |
API satisfies one of the following properties. Note that eglWaitSync | |
(see section 3.8.1.3) also requires satisfying these conditions. | |
* client API is OpenGL, and either the OpenGL version is 3.2 or | |
greater, or the GL_ARB_sync extension is supported. | |
* client API is OpenGL ES, and either the OpenGL ES version is 3.0 | |
or greater, or the GL_OES_EGL_sync extension is supported. | |
* client API is OpenVG, and the VG_KHR_EGL_sync extension is | |
supported. | |
3.8.1.2 Creating and Signaling OpenCL Event Sync Objects | |
If type is EGL_SYNC_CL_EVENT, an OpenCL event sync object is | |
created. The EGL_SYNC_STATUS attribute may not be explicitly | |
specified during creation of this type of sync object. If no | |
EGL_CL_EVENT_HANDLE attribute is specified at creation time, the | |
sync object will be created in the signaled state. Otherwise its | |
status will be determined by the provided OpenCL event, as described | |
below. An EGL_CL_EVENT_HANDLE must always be specified for | |
eglUnsignalSyncEXT. | |
To use an OpenCL event sync object, the EGL_SYNC_CL_EVENT attribute | |
must be set to a valid OpenCL <event> handle returned by a call to | |
clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects; other types | |
of OpenCL event handles are not supported. Implementations are not | |
required to validate the OpenCL event, and passing an invalid event | |
handle in <attrib_list> may result in undefined behavior up to and | |
including program termination. Note that EGL_CL_EVENT_HANDLE is not | |
a queriable property of a sync object. Queriable attributes of the | |
OpenCL event sync object are set as shown in table 3.8. | |
The status of such a sync object depends on <event>. When the status | |
of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of | |
the linked sync object will be EGL_UNSIGNALED. When the status of | |
<event> changes to CL_COMPLETE, the status of the linked sync object | |
will become EGL_SIGNALED. | |
The only condition supported for OpenCL event sync objects is | |
EGL_SYNC_CL_EVENT_COMPLETE, which is satisfied when the status of | |
the OpenCL event associated with the sync object changes to | |
CL_COMPLETE. | |
Associating an OpenCL event handle with a sync object places a | |
reference on the linked OpenCL object. When the sync object is | |
deleted or the event handle is replaced, the reference will be | |
removed from the OpenCL object. | |
If EGL_KHR_reusable_sync is present, then for sync objects of type | |
EGL_SYNC_REUSABLE_KHR, the initial value of EGL_SYNC_STATUS may be | |
set to either EGL_UNSIGNALED or EGL_SIGNALED, and will default to | |
EGL_UNSIGNALED. | |
If EGL_ANDROID_native_fence_sync is present, then for native fence sync | |
objects, the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may be specified | |
in eglUnsignalSyncEXT as well as eglCreateSync. If it is set to anything | |
other than EGL_NO_NATIVE_FENCE_FD_ANDROID at creation time, then its | |
initial EGL_SYNC_STATUS will reflect the current status of the provided | |
fence FD, and it is an error to specifically set the status. If it is | |
set to EGL_NO_NATIVE_FENCE_FD_ANDROID, then its EGL_SYNC_STATUS may be | |
set to either EGL_UNSIGNALED (the default) or EGL_SIGNALED. If the | |
status is signaled, then no native fence will be generated until after | |
it is switched to unsignaled. If eglUnsignalSyncEXT is called for a | |
native fence sync object with an FD of EGL_NO_NATIVE_FENCE_FD_ANDROID, | |
then a new native fence will be generated at the next Flush(), as | |
described for eglCreateSync. | |
If EGL_NV_cuda_event is present, then for CUDA event sync objects, the | |
EGL_CUDA_EVENT_HANDLE_NV may be specified in eglUnsignalSyncEXT as well | |
as eglCreateSync. The current CUDA event handle is evaluated at the time | |
the EGL sync object becomes unsignaled, and subsequent modification of | |
the CUDA object with cudaEventRecord has no effect on the sync object | |
until it is signaled. Subsequently restoring the sync object to | |
unsignaled will cause the CUDA object to be reevaluated. | |
Issues | |
1. Should a new attribute be required to specify a sync object as | |
reusable? | |
RESOLVED: No. The presence of this extension is sufficient to | |
indicate reusability of all sync objects. This will not create | |
any incompatibilities with existing applications that use sync | |
objects only once. | |
2. Can we leverage the existing eglSignalSyncKHR function from | |
EGL_KHR_reusable_sync for this extension? | |
RESOLVED: No. Some types of sync objects require attributes | |
which are themselves single-use objects, and must be replaced | |
for the sync object to be reused. Therefore a new function which | |
takes an attribute list is required. | |
3. Should the function for unsignaling be based on eglSignalSyncKHR | |
from the KHR_reusable_sync extension, and take a mode parameter | |
to distinguish signaling/unsignaling? | |
RESOLVED: No. While all sync objects will support unsignaling, | |
the reusable sync object is the only known one that supports | |
direct signaling, rather than signaling through some condition | |
being achieved. Therefore it is simplest to have the new | |
function only support unsignaling, and continue to use the old | |
extension for the one case where signaling is required. | |
4. If the initial attribute list is incomplete (e.g. an OpenCL | |
event handle is not provided during creation of an OpenCL event | |
sync object), should the EGL_SYNC_STATUS default to EGL_SIGNALED | |
rather than generating an error if it is left unspecified? | |
RESOLVED: Handling of allowed/default values for EGL_SYNC_STATUS | |
is based on the sync type. For fence syncs, either value is | |
allowed, defaulting to EGL_UNSIGNALED. For OpenCL event syncs, | |
the value may not be specified, and instead is determined by | |
whether an OpenCL event is provided at creation time, and if so | |
by the status of that event. | |
Revision History | |
#4 (May 16, 2018) Daniel Kartch | |
- Minor corrections to wording | |
#3 (April 20, 2018) Daniel Kartch | |
- Renamed to EXT | |
- Fixed grammatical errors and prepared for publication | |
#2 (January 23, 2018) Daniel Kartch | |
- Rewrote some sections for clarity, and fixed typos | |
- Changed default/allowed behavior for signal state at creation | |
time to be determined by the sync type and other attributes. | |
- Simplified interaction with EGL_KHR_reusable_sync. | |
- Refined interaction with EGL_ANDROID_native_fence_sync to | |
clarify allowed initial states for the sync status and fix the | |
description of when new native fences are generated. | |
#1 (January 16, 2018) Daniel Kartch | |
- Initial draft as XXX |