blob: e20d65aad9866b971f08a3eff5126f69a78cbc1b [file] [log] [blame]
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 object’s
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 API’s 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 context’s command
stream. The sync object will not be signaled until all effects from
these commands on the client API’s 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