Name
NV_sync
Name Strings
EGL_NV_sync
Contributors
Gary King
Gregory Prisament
Acorn Pooley
Jon Leech
Contacts
Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Status
Complete
Version
Version 7, July 27, 2010
Number
EGL Extension #19
Dependencies
Requires EGL 1.1
This extension is written against the wording of the EGL 1.2
Specification.
Overview
This extension introduces the concept of "sync objects" into EGL.
Sync objects are a synchronization primitive, representing events
whose completion can be tested or waited upon. This extension
borrows heavily from the GL_ARB_sync extension, and like that
extension, introduces only a single type of sync object, the
"fence sync object." Additional types of sync objects may be
introduced in later extensions.
Fence sync objects have corresponding fences, which are inserted
into client API command streams. A sync object can be queried
for a given condition, such as completion of the corresponding
fence. Fence completion allows applications to request a partial
Finish of an API command stream, wherein all commands issued in
a particular client API context will be forced to complete before
control is returned to the calling thread.
This extension is nearly identical to NVIDIA's original proposal for the
EGL_KHR_sync extension, which some minor differences outlined in Issue 7
below.
New Types
/*
* EGLSyncNV is an opaque handle to an EGL sync object
*/
typedef void* EGLSyncNV;
/*
* EGLTimeNV is a 64-bit unsigned integer representing intervals in
* nanoseconds (unadjusted standard time). A type defined in the
* standard Khronos <KHR/khrplatform.h> header is used instead of
* a less-portable native C type.
*/
#include <KHR/khrplatform.h>
typedef khronos_utime_nanoseconds_t EGLTimeNV;
New Procedures and Functions
EGLSyncNV eglCreateFenceSyncNV( EGLDisplay dpy,
EGLenum condition,
const EGLint *attrib_list );
EGLBoolean eglDestroySyncNV( EGLSyncNV sync );
EGLBoolean eglFenceNV( EGLSyncNV sync );
EGLint eglClientWaitSyncNV( EGLSyncNV sync,
EGLint flags, EGLTimeNV timeout );
EGLBoolean eglSignalSyncNV( EGLSyncNV sync, EGLenum mode );
EGLBoolean eglGetSyncAttribNV( EGLSyncNV sync, EGLint attribute,
EGLint *value );
New Tokens
Accepted in the <condition> parameter of eglCreateFenceSyncNV, and
returned in <value> when eglGetSyncAttribNV is called with <attribute>
EGL_SYNC_CONDITION_NV:
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV 0x30E6
Accepted as an attribute name in the <attrib_list> parameter of
eglCreateFenceSyncNV, and by the <attribute> parameter of
eglGetSyncAttribNV:
EGL_SYNC_STATUS_NV 0x30E7
Accepted as an attribute value in the <attrib_list> parameter of
eglCreateFenceSyncNV for the EGL_SYNC_STATUS_NV attribute, by
the <mode> parameter of eglSignalSyncNV and returned in <value>
when eglGetSyncAttribNV is called with <attribute>
EGL_SYNC_STATUS_NV:
EGL_SIGNALED_NV 0x30E8
EGL_UNSIGNALED_NV 0x30E9
Accepted in the <flags> parameter of eglClientWaitSyncNV:
EGL_SYNC_FLUSH_COMMANDS_BIT_NV 0x0001
Accepted in the <timeout> parameter of eglClientWaitSyncNV:
EGL_FOREVER_NV 0xFFFFFFFFFFFFFFFFull
Returned by eglClientWaitSyncNV:
EGL_ALREADY_SIGNALED_NV 0x30EA
EGL_TIMEOUT_EXPIRED_NV 0x30EB
EGL_CONDITION_SATISFIED_NV 0x30EC
Accepted in the <attribute> parameter of eglGetSyncAttribNV:
EGL_SYNC_TYPE_NV 0x30ED
EGL_SYNC_CONDITION_NV 0x30EE
Returned in <value> when eglGetSyncAttribNV is called with
<attribute> EGL_SYNC_TYPE_NV:
EGL_SYNC_FENCE_NV 0x30EF
Returned by eglCreateFenceSyncNV in the event of an error:
EGL_NO_SYNC_NV ((EGLSyncNV)0)
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add a new subsection at the end of Section 3.8, page 43
(Synchronization Primitives)
"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>. Events may be associated with a sync object. When an
event is initially associated with a sync object, the object is
unsignaled (its status is set to unsignaled). Once a sync object has
been created, EGL may be asked to wait for a sync object to become
signaled. Sync objects may also be signaled or unsignaled explicitly.
Sync objects are associated with an EGLDisplay; this association
is made when the sync object is created.
Only one type of sync object is defined, the fence sync object, whose
associated events are triggered by fence commands which are inserted
into the command streams of client API contexts. Fence sync objects may
be used to wait for partial completion of a client API command stream,
as a more flexible form of glFinish / vgFinish.
The command
EGLSyncNV eglCreateFenceSyncNV( EGLDisplay dpy,
enum condition,
EGLint *attrib_list );
creates a fence sync object for the specified display <dpy> and returns
a handle to the new object. The sync object is assigned a type of
EGL_SYNC_FENCE_NV. <condition> must be
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV. <attrib_list> is 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. Attributes accepted by fence sync objects
are listed in table 3.aa
Attribute Name Attribute Value(s) Default Value
--------------- ------------------------------------ --------------
EGL_SYNC_STATUS_NV EGL_SIGNALED_NV, EGL_UNSIGNALED_NV EGL_SIGNALED_NV
Table 3.aa Fence Sync Object Attributes
* If <dpy> is not the name of a valid, initialized EGLDisplay,
EGL_NO_SYNC_NV is returned and an EGL_BAD_DISPLAY error is generated.
* If <condition> is not EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV,
EGL_NO_SYNC_NV is returned and an EGL_BAD_PARAMETER error is generated.
* If any attribute not appearing in table 3.?? is specified in
<attrib_list>, EGL_NO_SYNC_NV is returned and an EGL_BAD_ATTRIBUTE error is
generated.
The command
EGLBoolean eglFenceNV( EGLSyncNV sync );
inserts a fence command into the command stream of the bound API's current
context (i.e., the context returned by eglGetCurrentContext), and
assoicates it with sync object <sync>. <sync> must be a sync object
created with eglCreateFenceSyncNV, and the display associated with <sync>
must match the current display (i.e., the display returned by
eglGetCurrentDisplay). Calling eglFenceNV unsignals <sync>.
When the condition of <sync> is satisfied by the fence command, <sync> is
signaled by the associated client API context, causing any
eglClientWaitSyncNV commands (see below) blocking on <sync> to unblock.
The condition EGL_SYNC_PRIOR_COMMANDS_COMPLETE_NV 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. <sync>
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.
Multiple fence commands may be inserted in any client API command stream
for a single sync object. The sync object is unsignaled every time a new
fence command is issued, and signaled every time a previous fence command
completes, so its status is indeterminate until all fence commands
associated with the sync object have completed. However, each time a fence
command completes (signaling the sync object), at least one
eglClientWaitSyncNV command blocking on that sync object will unblock.
EGL_TRUE is returned upon successful insertion of the fence command.
* If <sync> is not a valid sync object with a type of EGL_SYNC_FENCE_NV,
EGL_FALSE is returned and an EGL_BAD_PARAMETER error is generated.
* If the display associated with <sync> does not match the current
display, EGL_FALSE is returned and an EGL_BAD_MATCH error is generated.
* If no context is current for the bound API (i.e., eglGetCurrentContext
returns EGL_NO_CONTEXT), EGL_FALSE is returned and an EGL_BAD_MATCH error
is generated.
The command
EGLint eglClientWaitSyncNV( EGLSyncNV sync, uint flags,
EGLTimeNV timeout );
blocks the calling thread until the specified sync object <sync> is
signaled, or until a specified timeout value expires. If <sync> is
signaled at the time eglClientWaitSyncNV is called then eglClientWaitSyncNV
will not block. If <sync> is unsignaled at the time eglClientWaitSyncNV is
called then eglClientWaitSyncNV will wait up to <timeout> nanoseconds for
<sync> to become signaled.
If the value of <timeout> is zero, then eglClientWaitSyncNV will never
block and simply tests the current status of <sync>. If the value of
<timeout> is the special value EGL_FOREVER_NV then eglClientWaitSyncNV
does not time out.
eglClientWaitSyncNV returns one of three status values describing the
reason for returning. A return value of EGL_ALREADY_SIGNALED_NV will
always be returned if <sync> was signaled when eglClientWaitSyncNV was
called, even if <timeout> is zero. A return value of
EGL_TIMEOUT_EXPIRED_NV indicates that indicates that the specified
timeout period expired before <sync> was signaled. A return value of
EGL_CONDITION_SATISFIED_NV indicates that <sync> was signaled before
the timeout expired.
Note that a fence sync object can be in the signaled state because one of
three events has occured:
1. A previously inserte fence has completed and has signaled the sync
object.
2. The sync object was created. Creation of a sync object sets it in the
signaled state by default, unless the attribute EGL_SYNC_STATUS_NV
is set to EGL_UNSIGNALED_NV in the attribute list.
3. The sync object was signaled by a previously issued
eglSignalSyncNV(sync, EGL_SIGNALED_NV) command.
If the sync object being blocked upon will not be signaled in finite time
(for example, by an associated fence command issued previously, but not
yet flushed to the graphics pipeline), then eglClientWaitSyncNV may
wait forever. To help prevent this behavior (footnote1), if the
EGL_SYNC_FLUSH_COMMANDS_BIT_NV bit is set in <flags>, and <sync> is
unsignaled when eglClientWaitSyncNV is called, then the equivalent of
Flush() will be performed for the current API context (i.e., the context
returned by eglGetCurrentContext()) before blocking on <sync>. If no
context is current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_NV
bit is ignored.
(footnote 1): The simple Flush behavior defined by
EGL_SYNC_FLUSH_COMMANDS_BIT_NV will not help when waiting for a fence
command issued in a different context's command stream. Applications
which block on a fence sync object must take additional steps to ensure
that the context from which the associated fence command was issued
has flushed that command to the graphics pipeline.
If a sync object is deleted when an eglClientWaitSyncNV is blocking on
that object, the behavior of eglClientWaitSyncNV is undefined. Some
possible behaviors are to return immediately, to wait for fence commands
associated with the deleted sync to complete, or to not return until the
timeout period expires.
* If <sync> is not a valid sync object, EGL_FALSE is returned and an
EGL_BAD_PARAMETER error is generated.
The command
EGLBoolean eglSignalSyncNV( EGLSyncNV sync, enum mode );
signals or unsignals the sync object <sync> by changing its status to
<mode>, which must be one of the values in table 3.bb. If, as a
result of calling eglSignalSyncNV, the status of <sync> transitions
from unsignaled to signaled, then at least one eglClientWaitSyncNV
commands blocking on <sync> will unblock.
Assuming no errors are generated, EGL_TRUE is returned.
Mode Effect
------------------ -------------
EGL_SIGNALED_NV Set the status of <sync> to signaled
EGL_UNSIGNALED_NV Set the status of <sync> to unsignaled
Table 3.bb Modes Accepted by eglSignalSyncNV Command
* If <sync> is not a valid sync object, EGL_FALSE is returned and an
EGL_BAD_PARAMETER error is generated.
The command
EGLBoolean eglGetSyncAttribNV( EGLSyncNV sync, EGLint attribute,
EGLint *value );
is used to query attributes of the sync object <sync>. Legal values for
<attribute> depend on the type of sync object; these are listed in table 3.cc.
Assuming no errors are generated, EGL_TRUE is returned and the value of
the queried attribute is returned in <value>.
Attribute Description Supported Sync Objects
----------------- ----------------------- ---------------------
EGL_SYNC_TYPE_NV Type of the sync object All
EGL_SYNC_STATUS_NV Status of the sync object All
EGL_SYNC_CONDITION_NV Signaling condition EGL_SYNC_FENCE_NV
* If <sync> is not a valid sync object, EGL_FALSE is returned and an
EGL_BAD_PARAMETER error is generated.
The command
EGLBoolean eglDestroySyncNV( EGLSyncNV sync );
is used to destroy an existing sync object. If any eglClientWaitSyncNV
commands are blocking on <sync> when eglDestroySyncNV is called, their
behavior is undefined. After calling eglDestroySyncNV, <sync> is no
longer a valid sync object. Assuming no errors are generated, EGL_TRUE
is returned.
* If <sync> is not a valid sync object, EGL_FALSE is returned and an
EGL_BAD_PARAMETER error is generated.
Issues
1. Explain the key choices made in this extension.
RESPONSE: This extension has been written to enable adoption to be as wide
as possible, and to behave as similarly as possible to synchronization
primitives available in desktop OpenGL (e.g., NV_fence, ARB_sync).
In the interest of enabling widespread adoption, this extension (following
the ARB_sync model) has foregone the inclusion of synchronization primitives
and synchronization tests which may be performed entirely inside client
API command streams, instead performing synchronization tests
(eglClientWaitSyncNV) inside the application & host CPU.
In the interest of maintaining similarity with previous synchronization
primitives, this extension attempts to copy the ARB_sync specification
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. Why place this behavior in EGL, rather than in the client APIs?
RESPONSE: Ultimately, synchronization between multiple asynchronous client
API contexts (potentially executing in different threads) is a problem
which affects or will affect all EGL client APIs. Rather than creating
separate synchronization primitives in each of the client APIs (and then
wrapping them in an EGL container), in the interest of developer simplicity
& consistency this behavior is being placed inside EGL.
3. What does this extension provide that can not be accomplished with the
existing, more efficient eglWaitClient and eglWaitNative API functions?
RESPONSE: eglWaitClient and eglWaitNative may be implemented in extremely
lightweight manners, in some cases not blocking the calling thread at
all; however, they can not be used to synchronize between client API
contexts and native APIs executing in separate threads (or simply between
client API contexts executing in separate threads), such as between a
thread with an active OpenGL context and a second thread performing
video decode.
4. What does this extension provide that could not be accomplished with
native platform synchronization primitives and the existing client API
Finish commands?
RESPONSE: This extension provides a lighter-weight mechanism for
synchronizing an application with client API command streams than the
all-or-nothing Finish commands, enabling applications to block until
a subset of issued client API commands have completed.
5. Should integration with native platform synchronization objects be
included in this extension, or reserved for future (platform-specific)
extensions?
RESOLVED: Integration with native platform synchronization objects should
not be part of this extension, but can be added as future layered
extensions if needed. These layered extensions can be platform-specific,
or perhaps OpenKODE based.
Originally, this extension included the ability to create native platform
synchronization objects from EGLSync objects. This feature was removed
for a few reasons:
i) The proposed mechanism suggested mapping EGLSync objects to pthread
conditional variables on platforms with pthread support. However,
pthread conditional variables require an associated mutex and there
was no mechanism to relay this associated mutex to the application.
ii) On certain platforms support for converting to native platform
synchronization objects adds great complexity to the implementation.
iii) Now that OpenKODE is more mature, it would be better to allow
conversion from EGLSyncNV objects to OpenKODE synchronization
primitives rather than platform-specific ones. We suggest that this
functionality, if needed, be added as a layered extension instead of
being included here. This way, EGL_NV_sync remains minimal and easy
to implement on a variety of platforms.
6. Please provide a more detailed description of how ClientWaitSyncNV
behaves.
RESPONSE: Issue 18 in the ARB_sync specification includes a very
detailed description of ClientWaitSyncARB (the ARB_sync equivalent of
ClientWaitSyncNV). This is provided (unmodified) below:
Does ClientWaitSyncARB wait on an event, or on sync object
status? What is the meaning of sync object status?
RESOLVED: ClientWaitSyncARB blocks until the status of the sync
object transitions to the signaled state. Sync object status is
either signaled or unsignaled. More detailed rules describing
signalling follow (these need to be imbedded into the actual
spec language):
R1) A sync object has two possible status values: signaled or
unsignaled (corresponding to SYNC_STATUS_ARB values of
SIGNALED_ARB or UNSIGNALED_ARB, respectively).
R2) When created, the state of the sync object is signaled by
default, but may be explicitly set to unsignaled.
R3) A fence command is inserted into a command stream. A sync
object is not.
R4) When a fence command is inserted into a command stream using
FenceARB(), the status of the sync object associated with
that fence command is set to the unsignaled state.
R5) Multiple fence commands can be associated with the same sync
object.
R6) A fence command, once its condition has been met, will set
its associated sync object to the signaled state. The only
condition currently supported is
SYNC_PRIOR_COMMANDS_COMPLETE_ARB.
R7) A wait function, such as ClientWaitSyncARB, waits on a sync
object, not on a fence.
R8) A wait function, such as ClientWaitSyncARB, called on a sync
object in the unsignaled state will block. It unblocks
(note, not "returns to the application") when the sync
object transitions to the signaled state.
Some of the behaviors resulting from these rules are:
B1) Calling ClientWaitSyncARB with a timeout of 0 will return
TRUE if the sync object is in the signaled state. Note that
calling ClientWaitSyncARB with a timeout of 0 in a loop can
miss state transitions.
B2) Stacking fences is allowed. Each fence, once its condition
has been met, will set its associated sync object to the
signaled state. If the sync object is already in the
signaled state, it stays in that state.
B3) ClientWaitSyncARB could take a timeout parameter and return
a boolean. If the timeout period has expired,
ClientWaitSyncARB will unblock and return FALSE to the
caller. If ClientWaitSyncARB unblocks because the sync
object it was waiting on is in the signaled state, it will
return TRUE.
B4) We could define a FinishMultipleSync() command that will
unblock once all (or any) of the sync objects passed to it
are in the signaled state (also see issue 12).
B5) We could define a set/resetSyncObject function to manually
set the sync object in the signaled or unsignaled state.
This makes it easy for apps to reuse a sync object in the
multi-context case, so the sync object can be blocked upon
before a fence command is associated with it in the command
stream.
B6) We could define an API to convert a sync object into an OS
specific synchronization primitive (Events on Windows, file
descriptors or X-events or semaphores on Unix?)
7) How does this extension differ from (relate to) EGL_KHR_sync:
RESPONSE:
As of the time of writing this, the EGL_KHR_sync specification has not
been finalized by Khronos and continues to undergo revision. However,
NVIDIA has the functionality outlined in this specification implemented
and has decided to make it available to developers immediately.
For the most part, EGL_KHR_sync is identical to revision 5 of EGL_KHR_sync
with the following changes:
a) Enum values are different
b) EGLTimeNV is unsigned long long instead of uint64_t.
c) Behaviour when there are multiple waiting threads is undefined.
Revision History
#7 (Jon Leech, July 27, 2010)
- Redefine EGLTimeNV type to use a typedef from the standard
Khronos headers instead of a native C type, for portability.
#6 (Greg Prisament, May 28, 2009)
- Branch spec & turn it into an _NV extension.
#5 (Greg Prisament, July 22, 2008)
- Removed NativeSyncKHR, CreateNativeSyncKHR, and corresponding wording.
- Correct EGLuint to EGLint (EGLuint doesn't exist).
#4 (Jon Leech, November 20, 2007)
- Corrected 'enum' to 'EGLenum' in prototypes.
#3 (Jon Leech, April 5, 2007)
- Added draft Status and TBD Number
#2 (November 27, 2006)
- Changed OES token to KHR
