blob: 209b7fd888080a993f1250c61adc48d69ddf14be [file] [log] [blame]
Name Strings
Barthold Lichtenbelt, NVIDIA
Bill Licea-Kane, ATI
Greg Roth, NVIDIA
Jeff Bolz, NVIDIA
Jeff Juliano, NVIDIA
Jeremy Sandmel, Apple
John Kessenich, Intel
Jon Leech, Khronos
Piers Daniell, NVIDIA
Jon Leech (jon 'at'
Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
IP Status
US patent #6025855 may bear on this extension (based on ARB
discussion in March, 2003).
The related NV_fence extension is marked "NVIDIA Proprietary".
Complete. Approved by the ARB on July 3, 2009.
September 18, 2009 (version 25)
ARB Extension #66
OpenGL 3.1 is required.
The functionality of ARB_sync was added to the OpenGL 3.2 core.
This extension introduces the concept of "sync objects". Sync
objects are a synchronization primitive - a representation of events
whose completion status can be tested or waited upon. One specific
type of sync object, the "fence sync object", is supported in this
extension, and additional types can easily be added in the future.
Fence sync objects have corresponding fences, which are inserted
into the OpenGL command stream at the time the sync object is
created. A sync object can be queried for a given condition. The
only condition supported for fence sync objects is completion of the
corresponding fence command. Fence completion allows applications to
request a partial Finish, wherein all commands prior to the fence
will be forced to complete before control is returned to the calling
These new mechanisms allow for synchronization between the host CPU
and the GPU, which may be accessing the same resources (typically
memory), as well as between multiple GL contexts bound to multiple
threads in the host CPU.
New Types
(Implementer's Note: GLint64 and GLuint64 are defined as appropriate
for an ISO C 99 compiler. Other language bindings, or non-ISO
compilers, may need to use a different approach).
#include <inttypes.h>
typedef int64_t GLint64;
typedef uint64_t GLuint64;
typedef struct __GLsync *GLsync;
New Procedures and Functions
sync FenceSync(enum condition,bitfield flags)
boolean IsSync(sync sync)
void DeleteSync(sync sync)
enum ClientWaitSync(sync sync,bitfield flags,uint64 timeout)
void WaitSync(sync sync,bitfield flags,uint64 timeout)
void GetInteger64v(enum pname, int64 *params);
void GetSynciv(sync sync,enum pname,sizei bufSize,sizei *length,
int *values)
New Tokens
Accepted as the <pname> parameter of GetInteger64v:
Accepted as the <pname> parameter of GetSynciv:
Returned in <values> for GetSynciv <pname> OBJECT_TYPE:
Returned in <values> for GetSynciv <pname> SYNC_CONDITION:
Returned in <values> for GetSynciv <pname> SYNC_STATUS:
Accepted in the <flags> parameter of ClientWaitSync:
Accepted in the <timeout> parameter of WaitSync:
Returned by ClientWaitSync:
Additions to Chapter 2 of the OpenGL 3.1 Specification (OpenGL Operation)
Add to Table 2.2, GL data types:
"GL Type Minimum Description
Bit Width
------- --------- ----------------------------------------------
int64 64 Signed 2's complement binary long integer
uint64 64 Unsigned 2's complement binary long integer.
sync <ptrbits> Sync object handle (see section 5.2)
Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions)
Insert a new section following "Flush and Finish" (Section 5.1)
describing sync objects and fence operation. Renumber existing
section 5.2 "Hints" and all following 5.* sections.
"5.2 Sync Objects and Fences
Sync objects act as a <synchronization primitive> - a representation
of events whose completion status can be tested or waited upon. Sync
objects may be used for synchronization with operations occurring in
the GL state machine or in the graphics pipeline, and for
synchronizing between multiple graphics contexts, among other
Sync objects have a status value with two possible states:
<signaled> and <unsignaled>. Events are associated with a sync
object. When an sync object is created, its status is set to
unsignaled. When the associated event occurs, the sync object is
signaled (its status is set to signaled). Once a sync object has
been created, the GL may be asked to wait for a sync object to
become signaled.
Initially, only one specific type of sync object is defined: the
fence sync object, whose associated event is triggered by a fence
command placed in the GL command stream. Fence sync objects are used
to wait for partial completion of the GL command stream, as a more
flexible form of Finish.
The command
sync FenceSync(enum condition,bitfield flags)
creates a new fence sync object, inserts a fence command in the GL
command stream and associates it with that sync object, and returns
a non-zero name corresponding to the sync object.
When the specified <condition> of the sync object is satisfied by
the fence command, the sync object is signaled by the GL, causing
any ClientWaitSync or WaitSync commands (see below) blocking on
<sync> to <unblock>. No other state is affected by FenceSync or by
execution of the associated fence command.
<condition> must be SYNC_GPU_COMMANDS_COMPLETE. This condition is
satisfied by completion of the fence command corresponding to the
sync object and all preceding commands in the same command stream.
The sync object will not be signaled until all effects from these
commands on GL client and server state and the framebuffer are fully
realized. Note that completion of the fence command occurs once the
state of the corresponding sync object has been changed, but
commands waiting on that sync object may not be unblocked until
after the fence command completes.
<flags> must be 0[fn1].
[fn1: <flags> is a placeholder for anticipated future extensions
of fence sync object capabilities.]
Each sync object contains a number of <properties> which determine
the state of the object and the behavior of any commands associated
with it. Each property has a <property name> and <property value>.
The initial property values for a sync object created by FenceSync
are shown in table 5.props:
Property Name Property Value
------------- --------------
SYNC_CONDITION <condition>
SYNC_FLAGS <flags>
Table 5.props: Initial properties of a
sync object created with FenceSync().
Properties of a sync object may be queried with GetSynciv (see
section 6.1.16). The SYNC_STATUS property will be changed to
SIGNALED when <condition> is satisfied.
If FenceSync fails to create a sync object, zero will be returned
and a GL error will be generated as described. An INVALID_ENUM error
is generated if <condition> is not SYNC_GPU_COMMANDS_COMPLETE. If
<flags> is not zero, an INVALID_VALUE error is generated.
A sync object can be deleted by passing its name to the command
void DeleteSync(sync sync)
If the fence command corresponding to the specified sync object has
completed, or if no ClientWaitSync or WaitSync commands are blocking
on <sync>, the object is deleted immediately. Otherwise, <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
ClientWaitSync or WaitSync command. In either case, after returning
from DeleteSync the <sync> name is invalid and can no longer be used
to refer to the sync object.
DeleteSync will silently ignore a <sync> value of zero. An
INVALID_VALUE error is generated if <sync> is neither zero nor the
name of a sync object.
5.2.1 Waiting for Sync Objects
The command
enum ClientWaitSync(sync sync,bitfield flags,uint64 timeout)
causes the GL to block, and will not return until the sync object
<sync> is signaled, or until the specified <timeout> period expires.
<timeout> is in units of nanoseconds. <timeout> is adjusted to the
closest value allowed by the implementation-dependent timeout
accuracy, which may be substantially longer than one nanosecond, and
may be longer than the requested period.
If <sync> is signaled at the time ClientWaitSync is called
then ClientWaitSync returns immediately. If <sync> is unsignaled at
the time ClientWaitSync is called then ClientWaitSync will block and
will wait up to <timeout> nanoseconds for <sync> to become signaled.
<flags> controls command flushing behavior, and may be
SYNC_FLUSH_COMMANDS_BIT, as discussed in section 5.2.2.
ClientWaitSync returns one of four status values. A return value of
ALREADY_SIGNALED indicates that <sync> was signaled at the time
ClientWaitSync was called. ALREADY_SIGNALED will always be returned
if <sync> was signaled, even if the value of <timeout> is zero. A
return value of TIMEOUT_EXPIRED indicates that the specified timeout
period expired before <sync> was signaled. A return value of
CONDITION_SATISFIED indicates that <sync> was signaled before the
timeout expired. Finally, if an error occurs, in addition to
generating a GL error as specified below, ClientWaitSync immediately
returns WAIT_FAILED without blocking.
If the value of <timeout> is zero, then ClientWaitSync does not
block, but simply tests the current state of <sync>. TIMEOUT_EXPIRED
will be returned in this case if <sync> is not signaled, even though
no actual wait was performed.
If <sync> is not the name of a sync object, an INVALID_VALUE error
is generated. If <flags> contains any bits other than
The command
void WaitSync(sync sync,bitfield flags,uint64 timeout)
is similar to ClientWaitSync, but instead of blocking and not
returning to the application until <sync> is signaled, WaitSync
returns immediately, instead causing the GL server [fn1] to block
until <sync> is signaled [fn2].
[fn1 - the GL server may choose to wait either in the CPU
executing server-side code, or in the GPU hardware if it
supports this operation.]
[fn2 - WaitSync allows applications to continue to queue commands
from the client in anticipation of the sync being signaled,
increasing client-server parallelism.
<sync> has the same meaning as for ClientWaitSync.
<timeout> must currently be the special value TIMEOUT_IGNORED, and
is not used. Instead, WaitSync will always wait no longer than an
implementation-dependent timeout. The duration of this timeout in
nanoseconds may be queried by calling GetInteger64v with <value>
MAX_SERVER_WAIT_TIMEOUT. There is currently no way to determine
whether WaitSync unblocked because the timeout expired or because
the sync object being waited on was signaled.
<flags> must be 0.
If an error occurs, WaitSync generates a GL error as specified
below, and does not cause the GL server to block.
If <sync> is not the name of a sync object, an INVALID_VALUE error
is generated. If <timeout> is not TIMEOUT_IGNORED, or <flags> is not
zero, an INVALID_VALUE error is generated.
Multiple Waiters
It is possible for both the GL client to be blocked on a sync object
in a ClientWaitSync command, the GL server to be blocked as the
result of a previous WaitSync command, and for additional WaitSync
commands to be queued in the GL server, all for a single sync
object. When such a sync object is signaled in this situation, the
client will be unblocked, the server will be unblocked, and all such
queued WaitSync commands will continue immediately when they are
See section D.2 for more information about blocking on a sync
objects in multiple GL contexts.
5.2.2 Signaling
A sync object can be in the signaled state only once the
corresponding fence command has completed and signaled the sync
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 ClientWaitSync
may hang forever. To help prevent this behavior [fn4], if the
SYNC_FLUSH_COMMANDS_BIT bit is set in <flags>, and <sync> is
unsignaled when ClientWaitSync is called, then the equivalent of
Flush will be performed before blocking on <sync>.
[fn4 - The simple flushing behavior defined by
SYNC_FLUSH_COMMANDS_BIT will not help when waiting for a fence
command issued in another context's command stream to complete.
Applications which block on a fence sync object must take
additional steps to assure that the context from which the
corresponding fence command was issued has flushed that command
to the graphics pipeline.]
If a sync object is marked for deletion while a client is blocking
on that object in a ClientWaitSync command, or a GL server is
blocking on that object as a result of a prior WaitSync command,
deletion is deferred until the sync object is signaled and all
blocked GL clients and servers are unblocked.
Additional constraints on the use of sync objects are discussed in
Appendix D.
State must be maintained to indicate which sync object names are
currently in use. The state require for each sync object in use is
an integer for the specific type, an integer for the condition, an
integer for the flags, and a bit indicating whether the object is
signaled or unsignaled. The initial values of sync object state are
defined as specified by FenceSync."
Additions to Chapter 6 of the OpenGL 3.1 Specification (State and State Requests)
Add GetInteger64v to the first list of commands in section 6.1.1
"Simple Queries", and change the next sentence to mention the query:
"There are five commands for obtaining simple state variables:
void GetInteger64v(enum value,int64 *data)
The commands obtain boolean, integer, 64-bit integer,
Modify the third sentence of section 6.1.2 "Data Conversions":
"If any of the other simple queries are called, a boolean value of
TRUE or FALSE is interpreted as 1 or 0, respectively. If GetIntegerv
or GetInteger64v are called, a floating-point value is rounded to
the nearest integer, unless the value is an RGBA color component..."
Insert a new subsection following "Asynchronous Queries" (subsection
6.1.6) describing sync object queries. Renumber existing subsection
6.1.7 "Buffer Object Queries" and all following 6.1.* subsections.
"6.1.7 Sync Object Queries
Properties of sync objects may be queried using the command
void GetSynciv(sync sync,enum pname,sizei bufSize,sizei *length,
int *values)
The value or values being queried are returned in the parameters
<length> and <values>.
On success, GetSynciv replaces up to <bufSize> integers in <values>
with the corresponding property values of the object being queried.
The actual number of integers replaced is returned in *<length>. If
<length> is NULL, no length is returned.
If <pname> is OBJECT_TYPE, a single value representing the specific
type of the sync object is placed in <values>. The only type
supported is SYNC_FENCE.
If <pname> is SYNC_STATUS, a single value representing the status of
the sync object (SIGNALED or UNSIGNALED) is placed in <values>.
If <pname> is SYNC_CONDITION, a single value representing the
condition of the sync object is placed in <values>. The only
condition supported is SYNC_GPU_COMMANDS_COMPLETE.
If <pname> is SYNC_FLAGS, a single value representing the flags with
which the sync object was created is placed in <values>. No flags
are currently supported.
If <sync> is not the name of a sync object, an INVALID_VALUE error
is generated. If <pname> is not one of the values described above,
an INVALID_ENUM error is generated. If an error occurs,
nothing will be written to <values> or <length>.
The command
boolean IsSync(sync sync)
returns TRUE if <sync> is the name of a sync object. If <sync> is
not the name of a sync object, or if an error condition occurs,
IsSync returns FALSE (note that zero is not the name of a sync
Sync object names immediately become invalid after calling
DeleteSync, as discussed in sections 5.2 and D.2, but the underlying
sync object will not be deleted until it is no longer associated
with any fence command and no longer blocking any WaitSync command."
Additions to Appendix D (Shared Objects and Multiple Contexts)
In the first paragraph of the appendix, add "sync objects" to the
list of shared state.
Replace the title and first sentence of section D.1 with:
"D.1 Object Deletion Behavior (other than sync objects)
After a shared object (other than sync objects, discussed in section
D.2) is deleted..."
Insert a new section following "Object Deletion Behavior" (section
D.1) describing sync object multicontext behavior. Renumber existing
section D.2 "Propagating State Changes..." and all following D.*
"D.2 Sync Objects and Multiple Contexts
D.2.1 Sync Object Deletion Behavior
Deleting sync objects is similar to other shared object types in
that the name of the deleted object immediately becomes invalid but
the underlying object will not be deleted until it is no longer in
use. Unlike other shared object types, a sync object is determined
to be in use if there is a corresponding fence command which has not
yet completed (signaling the sync object), or if there are any GL
clients and/or servers blocked on the sync object as a result of
ClientWaitSync or WaitSync commands. Once any corresponding fence
commands have completed, a sync object has been signaled, and all
clients and/or servers blocked on that sync object have been
unblocked, the object may then be deleted.
D.2.2 Multiple Waiters in Multiple Contexts
When multiple GL clients and/or servers are blocked on a single sync
object and that sync object is signaled, all such blocks are
released. The order in which blocks are released is
Promote the fifth paragraph of section D.3 "Propagating State
Changes" (following the itemized list of changes to an object) to a
new subsection D.3.1. Renumber the existing subsection D.3.1
"Definitions" and all following D.3.* subsections.
"D.3.1 Determining Completion of Changes to an object
The object T is considered to have been changed once a command such
as described in section D.3 has completed. Completion of a
command[fn5] may be determined either by calling Finish, or by
calling FenceSync and executing a WaitSync command on the associated
sync object. The second method does not require a round trip to the
GL server and may be more efficient, particularly when changes to T
in one context must be known to have completed before executing
commands dependent on those changes in another context.
[fn5: The GL already specifies that a single context processes
commands in the order they are received. This means that a
change to an object in a context at time <t> must be
completed by the time a command issued in the same context
at time <t+1> uses the result of that change.]"
Change all references to "calling Finish" or "using Finish" in
section D.3.3 "Rules" to refer to section D.3.1.
Additions to the GLX 1.4 Specification
Insert a new section after section 2.5, "Texture Objects":
"2.6 Sync Objects
Sync objects are shared by rendering contexts in the same fashion as
texture objects (see Appendix D, "Shared Objects and Multiple
Contexts", of the OpenGL 3.1 Specification). If a sync object is
blocked upon (glClientWaitSync or glWaitSync), signaled
(glSignalSync), or has events associated with it (glFence) from more
than one context, then it is up to the programmer to ensure that the
correct order of operations results, and that race conditions and
deadlocks are avoided.
All modifications to shared context state as a changing the status
of a sync object are atomic. Also, a sync object will not be deleted
until there are no longer any outstanding fence commands or blocks
associated with it."
Replace the third paragraph of section 3.3.7, "Rendering Contexts":
"If <share_list> is not NULL, then all shareable GL server state
(excluding texture objects named 0) will be shared by <share_list>
and the newly created rendering context. An arbitrary number of
GLXContexts can share server state. The server context state for all
sharing contexts must exist in a single address space or a BadMatch
error is generated."
GLX Protocol
INVALID_VALUE is generated if the <sync> parameter of
ClientWaitSync, SignalSync, WaitSync, or GetSynciv is not the name
of a sync object.
INVALID_VALUE is generated if the <sync> parameter of DeleteSync
is neither zero nor the name of a sync object.
INVALID_ENUM is generated if the <condition> parameter of FenceSync
INVALID_VALUE is generated if the <flags> parameter of
ClientWaitSync contains bits other than SYNC_FLUSH_COMMANDS_BIT, or
if the <flags> parameter of WaitSync is nonzero.
INVALID_ENUM is generated if the <mode> parameter of SignalSync is
INVALID_ENUM is generated if the <pname> parameter of GetSynciv is
New State
Table 6.X. Sync Objects.
Get value Type Get command Initial value Description Section
------------------ ---- ----------- ---------------------------- --------------- -------
OBJECT_TYPE Z_1 GetSynciv SYNC_FENCE Type of sync object 5.2
SYNC_STATUS Z_2 GetSynciv UNSIGNALED Sync object status 5.2
SYNC_CONDITION Z_1 GetSynciv SYNC_GPU_COMMANDS_COMPLETE Sync object condition 5.2
SYNC_FLAGS Z GetSynciv SYNC_FLAGS Sync object flags 5.2
New Implementation Dependent State
Table 40. Implementation Dependent Values (cont.)
Get value Type Get command Minimum value Description Section
------------------ ---- ------------- ---------------------------- --------------- -------
MAX_SERVER_WAIT_ Z^+ GetInteger64v 0 Maximum WaitSync 5.2
TIMEOUT timeout interval
Sample Code
... kick off a length GL operation
/* Place a fence and associate a fence sync object */
GLsync sync = glFenceSync(GLSYNC_GPU_COMMANDS_COMPLETE, 0);
/* Elsewhere, wait for the sync to be signaled */
/* To wait a specified amount of time (possibly clamped), do
* this to convert a time in seconds into nanoseconds:
GLuint64 timeout = num_seconds * ((GLuint64)1000 * 1000 * 1000);
glWaitSync(sync, 0, timeout);
/* Or to determine the maximum possible wait interval and wait
* that long, do this instead:
GLuint64 max_timeout;
glGetInteger64v(GL_MAX_SERVER_WAIT_TIMEOUT, &max_timeout);
glWaitSync(sync, 0, max_timeout);
1) Are sync objects shareable between multiple contexts?
RESOLVED: YES. The sync object namespace is shared, and sync
objects themselves may be shared or not. Shared sync objects can
be blocked upon or deleted from any context they're shared with.
Enabling multi-context aware sync objects is a major change from
earlier versions of the specification. We believe this is now OK
because the rules defining sync object signaling behavior are
clear enough to make us comfortable with restoring full
multi-context awareness.
2) What specializations of sync objects are supported?
RESOLVED: Only fence sync objects (corresponding to synchronous
command stream fences). Additionally, fence sync objects are
constrained so that fence "stacking" is not allowed - the
initial status of a fence sync is unsignaled, and it may only be
We expect to define a way to map sync objects into OpenCL events
to help performance of CL/GL sharing.
EGL sync objects (from the EGL_KHR_sync extension) should be
compatible with GL sync objects, although the sync object
namespace may require remapping between APIs. Also, EGL sync
objects do support fence stacking and unsignaling, possibly
imposing greater complexity and risk of hanging when used with
The sync object framework is intended to generalize to other
types of sync objects, such as mappings of OS-specific events
and semaphores, new specializations of sync objects such as
"pulsed" sync objects associated with video retrace, or other
command stream conditions, such as sync objects which would be
associated with completion of single or multiple asynchronous GL
3) What fence sync object conditions are supported?
to ALL_COMPLETED_NV in NV_fence), meaning that a fence command
has completed in the GPU pipe.
In the future, we could define two additional conditions:
SYNC_SERVER_COMMANDS_COMPLETE would correspond to a command
completing "in the server"; the exact definition of "server"
would have to be nailed down, but generally meaning that the
command has been issued to the GPU by the driver. The primary
purpose of this condition would be to delay use of an object in
one context until after it has been created in another context,
so if it proves too difficult to define "server", the condition
could be restricted to simply meaning that all object creation
commands prior to the fence have realized their effect on server
SYNC_CLIENT_COMMANDS_COMPLETE, would correspond to a command
being issued from the client to the server (although this can
effectively be done already, by explicitly signaling a sync
object in the client).
4) What state is associated with a sync object? Should state be
validated at creation time, or when events are associated with a
sync? This would express itself (for example) by passing a
<condition> parameter to Fence(), rather than to Sync().
RESOLVED: sync object state includes specialization (type),
condition, flags, and status. Status is mutable data; condition
and flags are immutable properties defined defined at creation
In the future, additional state and data may be introduced, such
as a timestamp when the sync object was last signaled, or a
swapbuffer / media stream count (SBC/MSC, in digital media
terminology), for a sync object triggered by display retrace.
5) What is the purpose of the flags argument to FenceSync?
RESOLVED: The flags argument is expected to be used by a vendor
extension to create sync objects in a broader sharing domain
than GLX/WGL share groups. In the future we may reintroduce the
generic property list mechanism if a generic sync object
creation call is defined for multiple types of sync objects, but
for fence sync objects alone, the flags parameter is sufficient
6) Can sync objects and NV_fence fences share enumerants and/or the
namespace of fences / sync objects?
RESOLVED: NO. The sync object namespace cannot be the same as
NV_fence since NV_fence does not put fence names on the share
list, while sync objects and their names are shared. We will
also not reuse enumerant values. The sync object interface is
quite a bit different from NV_fence even though the underlying
fence functionality is not.
7) Should we allow these commands to be compiled within display
RESOLVED: WaitSync and SignalSync are display listable. They
execute on the GL server or in the GL pipeline.
RESOLVED: ClientWaitSync and FenceSync are not display listable.
ClientWaitSync is defined to block the application, not the
server. FenceSync must return a value to the application.
(Note: this is not relevant to this draft of the extension,
which is written against core OpenGL 3.1. However, an
implementation supporting the ARB_compatibility extension should
behave as described. We may wish to add this qualified language
to the extension if it's to be shipped against such an
8) What happens if you set a fence command for a sync object while a
previous fence command is still in flight? Are fences
"stackable"? (also see issue 21)
RESOLVED: Fences are not stackable at present. A single fence
command is associated with a fence sync object when it is
created. In the future we might reintroduce the separate sync
creation (Sync()) and fence-associated (Fence()) commands
present in prior drafts, with all the complexity of stacking
defined therein.
As with OS synchronization primitives, applications are
responsible for using sync objects and fences in ways that avoid
race conditions and hangs. Removing stackable fences may help
reduce the possibility of such errors.
We are still considering potential performance issues and
semantic difficulties of namespace sharing (e.g. when does a
name returned by FenceSync become valid in other contexts of the
share group) associated with this model.
9) What happens to *WaitSyncs blocking on a sync object, and to an
associated fence command still pending execution, when the sync
object is deleted?
RESOLVED: Following the OpenGL 3.0 shared object model, the sync
object name is immediately deleted, but the underlying sync
object is not deleted until all such outstanding references on
it are removed.
NOTE: This specifies behavior left intentionally unspecified by
earlier versions of this extension.
10) Is it possible to have multiple *WaitSyncs blocking on a single
sync object?
RESOLVED: YES, since we support multi-context aware sync
objects. *WaitSync might be issued from multiple contexts on the
same sync object. Additionally, multiple WaitSync commands may
be queued on a single GL server (although only one of them can
actually be blocking at any given time).
11) Can we determine completion time of a sync object?
In the future, we may support variants of sync objects that
record their completion time in queriable object data.
12) Can we block on multiple sync objects?
In the future, *WaitSyncs calls taking a list of sync object
names, a logical condition (any/all complete), and optionally
returning an index/name of a sync object triggering the
condition, like the GL2_async_object API, could be added.
13) Why don't the entry points/enums have ARB appended?
This functionality is going directly into the OpenGL 3.2 core
and also being defined as an extension for older platforms at
the same time, so it does not use ARB suffixes, like other such
new features going directly into the GL core.
14) Where can sync objects be waited on?
RESOLVED: In the client on the CPU, or in the GL server, either
in the CPU or GPU.
Rather than specifying where to wait in the server, the
implementation is allowed to choose.
15) Can the specialization of sync objects be changed, once created?
This seems likely to cause errors and has little obvious use -
making sync objects persistent (being able to reset their status
and associate them with a new fence) should suffice to avoid
excessive creation/deletion of objects.
16) How can sync objects be used to facilitate asynchronous
operations, particularly large data transfer operations?
DISCUSSION: There are several methods. A more readily
supportable one uses multiple GL contexts and threads, with work
performed in one thread associated with a sync. Another thread
finishes, tests for completion, or waits on that sync, depending
on the exact semantic needed.
This method is implementable, but has the disadvantage of requiring
multiple contexts, drawing surfaces, and CPU threads. It also
requires some additional, possibly non-GL synchronization
between the threads (so that the work thread knows when the sync
created in the loader thread is valid - otherwise it can't be
tested without raising an error!)
It seems analogous to pbuffers in terms of overhead. That
suggests lighter-weight mechanisms may be preferable, in the
same fashion that framebuffer objects have become preferable to
A more future-looking mechanism is to support multiple command
streams within a single context. Then the expensive asynchronous
operations can be kicked off without additional CPU threads,
rendering surfaces, or contexts.
This concept has not been implemented in GL yet, although the
original 3Dlabs white paper outlines an approach to it. The
desire for consistency / reproducibility means that retrofitting
multiple command streams onto the current API, defining when and
how resources changed in one stream affect another stream, may
require a great deal of spec work. Furthermore, most hardware
does not actually support multiple command streams, at least in
full generality.
If we do support multiple command streams, then at least at
first, there will probably be severe restrictions on what
commands could go in additional streams beyond the "main" or
"default" stream.
In either case, we will probably need to either define new
commands that are allowed to operate asynchronously (e.g.
TexImageAsync) with respect to surrounding commands, or to
overload existing commands to operate asynchronously when
some global state is set, like the old SGI_async extension.
Note that buffer objects allow the GL to implement data transfer
into, or out of, the buffer object to occur asynchronously.
However, once the transfer is completed, that data is in a buffer
object and not stored in memory that is under application control.
In defining these commands, we will probably need some way to
associate a sync object with them at the time they're issued,
not just place a fence following the async command. One reason
for this is wanting to know when the application data passed
into an asynchronous command has been consumed and can safely be
modified by the app.
17) Can the query object framework be used to support sync objects?
It is straightforward to map the sync object API onto queries,
with the addition of a small number of entry points. However,
the query object namespace is defined not to be shared. This
makes it impossible to implement shared sync objects in the
query namespace without the possibility of breaking existing
code that uses the same query name in multiple contexts.
It is also possible to map occlusion queries into the sync
object API, again with the addition of a small number of entry
points. We might choose to do this in the future.
18) Do *WaitSync wait on an event, or on sync object status? What is
the meaning of sync object status?
RESOLVED: *WaitSync 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
signaling follow (these may need to be imbedded into the actual
spec language):
(Note: much of the following discussion is not relevant for the
constrained fence sync objects currently defined by this
extension, as such objects start in the unsignaled state and may
only transition to the signaled state, not the other way).
R1) A sync object has two possible status values: signaled or
unsignaled (corresponding to SYNC_STATUS values of SIGNALED
or UNSIGNALED, 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
Fence(), 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
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_GPU_COMMANDS_COMPLETE.
R7) A wait function, such as ClientWaitSync or WaitSync, waits
on a sync object, not on a fence.
R8) A wait function 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 ClientWaitSync with a timeout of 0 will return TRUE
if the sync object is in the signaled state. Note that
calling ClientWaitSync 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) ClientWaitSync could take a timeout parameter and return a
boolean. If the timeout period has expired, ClientWaitSync
will unblock and return FALSE to the caller. If
ClientWaitSync 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
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?)
19) Which of the behaviors defined in issue 18 should be added?
RESOLVED: Add B1, B2, and B3 (timeout functionality).
We considered several possibilities including passing a <unit
duration,count> tuple, and adding a TIMEOUT_BIT to the flags to
representing "forever". The end result of discussion was to
introduce a new GL datatype, GLuint64. GLuint64 is a 64-bit
unsigned integer representing intervals in nanoseconds - the
same encoding as the Unadjusted System Time (UST) counter used
in OpenML and OpenKODE. All future uses of time in the GL should
use the GLuint64 datatype.
At present, the timeout duration passed to *WaitSync represents
a time relative to when the driver actually begins waiting. A
future extension could easily allow waiting until a specific UST
by adding a bit to the flags specifying that timeout is
absolute, not relative.
RESOLVED: Do not add B4 yet (easy to put in a future extension).
RESOLVED: Add B5 with a new glSignalSync call taking modes of
SIGNALED or UNSIGNALED. Might add a PULSED mode in the future,
but that's a bit weird - what if the sync object is already
RESOLVED: Add B6 via a WGL extension supporting only
wglConvertSyncToEvent (no wglConvertEventToSync). Figure out the
corresponding Unix/X functionality and define that as well -
should it use pthreads? xsync objects? System V IPC semaphores?
20) How can multi-context aware sync objects be used to synchronize
two contexts?
NOTE: This example needs to be rewritten to accomodate changes
to the API and asynchronous object creation. In particular,
context B must wait for the shared sync object to be
successfully created before waiting on it, which requires either
platform-specific (non-OpenGL) code, or client-side cleverness
suggested by Bill Licea-Kane. There should also be an example
showing specifically how to use sync objects and server waiting
to coordinate waiting on creation of another object.
Example of context B waiting on context A:
A: // Create a sync object in the unsignaled state
int props[] = {
syncObjectA = Sync(SYNC_FENCE, 2, props);
B: // Block, since syncObjectA is in the unsignaled state
A: // Perform rendering that B should wait on
// Insert a fence into the command stream. syncObjectA
// remains in the unsignaled state until completion
// To prevent deadlock, A must make forward progress
B: // Once the fence command issued above completes, the
// ClientWaitSync issued above will unblock and allow B
// to continue.
21) What is the stacking behavior of fence commands?
RESOLVED: Stacking is not allowed.
22) What should the blocking API be called?
RESOLVED: ClientWaitSync for blocking on the client side.
WaitSync for blocking on the GL server (CPU or GPU).
Previously we used FinishSync by analogy with NV_fence's
'glFinishFence'. However, the call may return before an event
has actually signaled a sync, due to timeout. Also, other sync
object specializations do not necessarily have anything to do
with command streams (timers, retrace events, OS events, etc.)
So 'Finish' is the wrong name.
23) How are sync objects implemented in terms of generic object
RESOLVED: An object property name which could be generic is
introduced here (OBJECT_TYPE), but no generic object
manipulation commands are defined.
24) Do we need a default sync object that is always present?
(Notionally the "sync object named zero")?
RESOLVED: NO. Fence sync objects cannot provide this
functionality. Multiple contexts just have to be clever about
use of (potentially client-created) sync object names.
DISCUSSION: The use case for a default sync object is in
coordinating object creation across contexts (see the
out-of-date example in issue 20 as well). Suppose we want to
know in context B when context A has successfully created an
object, so we can start using it. It's possible to do this by
inserting a fence command after object creation in A and waiting
on sync completion in B. But to do this, first we must have a
sync object that is known to exist in both A and B, creating a
circular dependency!
There are several possible approaches.
1) Create a sync object in context A before forking another
thread that would create context B and use it. This wouldn't
help in the indirect rendering / separate process model case.
2) Punt to platform-specific code: create a sync object in A,
verify it was successfully created in A, then use
platform-specific IPC to let other threads / processes know the
sync is ready for use to coordinate object creation. This is
highly inelegant.
3) Mandate that all contexts in a share group have a single,
shared sync object defined, which is present from context
creation time. When requesting this default object, the driver
will either create it, if it doesn't already exist, or return a
handle to the existing default object, if it does. The key point
is that the handle can be obtained in two different contexts
without either one needing to do non-portable or non-GL
operations before knowing the handle is valid.
4) Clever client in context B. Bill has commented on this and
people seem to agree this is doable and won't cause any coding
issues, so we're assuming it's correct.
25) Do we need the ability to WaitSync in the GPU, as well
as in the server?
RESOLVED: The implementation is allowed to choose.
26) How will sync objects be linked to OpenCL events?
NOTE: This is an issue for a future extension defining a new
type of sync object. A suggestion for that extension is
circulating on the OpenCL mailing list. This will likely be done
as a new command taking a CL event handle and returning a GL
sync object behaving like a fence sync, but with a different
object type, and triggered by the CL event rather than a fence.
27) What is the relationship between EGL and OpenGL sync objects?
The goal is that an EGL-based implementation could support both
APIs to a single underlying sync object implementation. It is
unlikely that the namespaces of EGL and GL sync objects could be
shared, however.
28) What is the deletion behavior of sync objects?
RESOLVED: DeleteSync immediately releases the name, but
"bindings" of the underlying object, e.g. outstanding fences or
blocking commands, will keep its underlying storage around until
all such commands complete and unblock all such waiters. This is
consistent with the OpenGL 3.0 shared object appendix, except
references are formed by commands and blocks, rather than by the
attachment hierarchy.
29) Should there be an implementation-dependent maximum timeout
RESOLVED: Not for client waits, which may block "forever", but a
MAX_SERVER_WAIT_TIMEOUT implementation-dependent value exists,
together with a new GetInteger64v query (see issue 30).
In the Windsor F2F, we agreed to remove the value FOREVER.
Because any timeout can be clamped, FOREVER didn't really mean
"forever", so it was misleading (and inconsistent with the
special treatment of FOREVER in the EGL_KHR_sync spec) to have
it. Instead we have a sample code section which shows how to
wait a long time.
30) What is the type of the timeout interval?
RESOLVED: GLuint64. We previously typedefed uint64_t (or
equivalent) as 'GLtime', but now that max timeout intervals are
queriable, a query function is required. A generic query for
64-bit integer data is more useful than a GLtime-specific query.
Consequently the type of <timeout> has been changed to
'GLuint64' and a corresponding 'GetInteger64v' query taking
'GLint64' added (by symmetry with GetInteger, where unsigned
quantities are queries with a function taking a pointer to a
signed integer - the pointer conversion is harmless).
The existing GLintptr argument is not guaranteed to be at least
64 bits long, so is not appropriate here.
NOTE: We might choose a type tag for GLuint64 state other than
the existing 'Z^+'. It is indeed a non-negative integer but the
difference in size might be worth noting in the state tables.
31) Potential naming issues
Are SYNC_CONDITION and SYNC_STATUS too confusingly similar? We
could refine these to SYNC_FENCE_CONDITION and
SYNC_SIGNAL_STATUS at some wordiness cost, although the existing
names match the EGL sync object extension and consistency may be
a virtue. There's also a question of whether future types of
sync objects would have a use for conditions having nothing to
do with fences, e.g. a display sync might have conditions
corresponding to different points in the draw / retrace interval
cycle, which argues in favor of the existing name.
There's still time to change names prior to approval of EGL and
GL sync objects, if anyone wants to make suggestions.
32) Do we need an explicit signaling API (SignalSync)?
RESOLVED: NO, not for fence sync objects. In the future other
types of sync objects may choose to reintroduce this API.
33) What is the datatype of a sync object handle?
RESOLVED: GLsync, which is defined as an anonymous struct
pointer in the C binding. This eases implementability on 64 bit
environments by allowing server pointer representations to be
Revision History
Version 1, 2006/02/08 - First writeup as spec language, based on
Version 2, 2006/02/10 - WaitSync can only wait on fence syncs. Sync
types are immutable once created - FenceSync can be called on an
existing sync of type fence to rebind it to a new fence command, but
it cannot be called on a non-fence sync. Expanded list of errors.
Numbered issues list and added issues 13-16. Noted future "multiple
command stream" concept in issue 16.
Version 3, 2006/02/14 - Change FenceSync behavior to leave the sync
state undefined if a previously issued fence command is still
in-flight when a fence sync is reset. Add a flags parameter to
FinishSync which can be used to produce flushing behavior like
NV_fence in the single-context use case, and note that in the
multiple-context case, applications must do more synchronization
work between threads themselves to ensure that a fence command
issues in one context will reach the hardware before blocking
another context.
Version 4, 2006/02/22 - change sharing behavior so the sync
namespace is shared, but sync objects can only be used from the
context they were created in. Add subsection 2.2.1 and new Appendix
C describing types of shared objects and how sharing affects sync
commands (also as a placeholder for a future, more general
discussion of shared object semantics). Remove WaitSync, since
that's useful when syncs are shared. Add issue 18 discussing the
distinction between waiting on events vs. waiting on changes in sync
status, and issue 19 discussing stacking of fence commands. Split
FenceSync into two parts to create the sync vs. issue the fence
Version 5, 2006/02/24 - Add a bit to FenceSync to control the
initial status value of the sync. Note that TestSync is polling the
status value, not the condition which causes that status value to
change. Make FinishSync return immediately if the status of the sync
being waited on is true at the time it's called, and otherwise wait
for the event underlying the status to occur; change issue 18
Version 6, 2006/02/24 - Added Contributors list. Marked explicitly
RESOLVED all issues that have been closed, including issues 2, 3, 6
(partly unresolved), 7, 8 (merged with 19), 9, 10, 15, 17, and 18.
Allow stacking behavior for Fence and define FinishSync to wait on
the most recently issued fence command at the time FinishSync was
called. Note that DeleteSyncs() may be called while fence commands
are outstanding for a sync (issue 9).
Version 7, 2006/03/07 - Modify DeleteSyncs behavior to allow
deleting syncs from contexts other than the creator, to avoid
orphaned & undeleteable syncs.
Version 8, 2006/03/09 - A terminology change from "sync types" to
"sync specializations" affects wording of several issues. Full
multi-context awareness has been restored, with the aid of a compact
set of rules defining sync signaling behavior (see issue 18). This
significantly changes the resolution and discussion of issues 1, 8
(FinishSync blocks on the first outstanding fence command to
complete, not the most recently issued one), 9 (sync destruction is
delayed until all outstanding fence commands complete), 10, and 18
(describe the rules), and in the corresponding spec language. Added
issues 19-21 discussing additional ways to control sync signaling,
and providing several examples of multi-context sync usage. Enum
values will not be shared with NV_fence.
Version 9, 2006/03/13 - Inserting multiple outstanding fence
commands on a sync from different contexts may not be supported.
Delaying sync destruction until there are no outstanding commands
may be too expensive to support. Note resolution of new features
(support timeouts, form TBD; support SignalSync; support conversion
of syncs to OS events, at least for WGL). Add SignalSync spec
Version 10, 2006/03/20 - major rewrite to replace fence-specific
discussion in FinishSync with Barthold's more powerful and generic
"signaled"/"unsignaled" terminology (also changed name of
parameter to FinishSync and removed the now-redundant TestSync.
Introduced the notion of UST time and the GLtime datatype to
represent it. FinishSync now returns a condition code explaining why
it completed. Corrected "GetFenceuiv" to "GetSyncuiv" in several
places. Changed value of SYNC_FLUSH_COMMANDS_BIT to be exclusive
with SYNC_UNSIGNALED_BIT, even though they are passed to separate
<flag> arguments, since we don't know their future uses.
Version 11, 2006/03/23 - noted potential IP concern (first mentioned
WRT GL2_async_core at the March 2003 ARB meeting). Updated
description of sync deletion for consistency with the description of
texture object deletion in the GLX 1.4 specification. Noted in issue
8 and Appendix C that inserting fence commands on the same sync from
multiple threads is allowed. New issue 22 for better naming of
FinishSync. Noted that accuracy of GLtime is system-dependent. Fixed
several typos and added a missing error condition for FinishSync.
Version 12, 2006/03/31 - Changed FinishSync to ClientWaitSync. Note
that ClientWaitSync behavior is explicitly undefined (and note
several of the possible consequences) when a sync object being
blocked upon is deleted. Used shorthand "signaled" and "unsignaled"
in many places rather than the wordier "placed into the signaled
state". Changed sync status to SIGNALED/UNSIGNALED rather than
TRUE/FALSE, and rewrote SignalSync language accordingly. Updated
Appendix C description of multicontext behavior to explicitly
describe full multi-context awareness. Use "sync object"
consistently throughout and drop the "sync" shorthand. Use
"unsignaled" everywhere, instead of "non-signaled". Clean up Errors
section, but don't remove errors just because they're inferred from
the core spec - many other extensions also try to be comprehensive
in listing errors.
Version 13, 2006/04/03 - Add overview paragraph to start of section
5.6. Replace "poll" terminology with "test". Disambiguate status
value returned from ClientWaitSync when the sync was signaled at
call time, but timeout was zero. Clarify that fence commands are not
events, but their execution triggers events.
Version 14, 2008/06/08 - Merge changes from the Longs Peak object
model version of sync objects back into the GL2 API version for use
in OpenGL 3.0. Introduce generic object interfaces using GL2 names
and explicit attribute lists instead of attribute objects and use
those as the base of sync object manipulation. Move the object
shared flag, condition, and status into the attribute list. Replace
FenceSync creation flags with Sync using an explicit object
type parameter together with an attribute list mechanism. Add
WaitSync and rename SYNC_GPU_COMMANDS_COMPLETE to allow for possible
future definition of server and client completion conditions as
discussed in issue 3. Add issues 23 and 24 discussing generic object
interfaces and the potential utility of a default sync object.
Version 15, 2009/04/23 - Merge changes from (abandoned) draft GL 3.0
language back into this extension for consideration as a GL 3.2 /
ARB extension feature. Minor API and terminology changes, including
generating sync names at creation time instead of using Gen*
functions changing DeleteSyncs to DeleteSync, and using
sync-specific GetSynciv instead of GetObjectiv. Specify that
multiple waiters on a sync object are all released when it's
signaled. Added new issues 25-28 and moved the Issues list to the
bottom of the document.
Version 16, 2009/05/03 - Change Fence -> FenceSync and merge sync
creation into the command, removing Sync (until other sync types are
supported), and also removing the ability to stack fences on a
single fence sync object. Remove <where> parameter from WaitSync and
allow it to wait in either the server or GPU. Make syncs always
shared and remove OBJECT_SHARED property. Add issue 29 on whether
implementation-dependent max timeout intervals should be defined.
Version 17, 2009/05/06 - Replace GLtime with GLuint64. Add
implementation-dependent maximum timeout interval state in table 40.
Modify *WaitSync to clamp requested timeout to the appropriate
maximum interval. Add GetInteger64v query for these values and issue
30 about the type signature of the query. Add clarification in
FenceSync of what it means for a fence command to complete. Add
issue 31 about possibly confusing token naming. Additional minor
typos and wording changes from Greg.
Version 18, 2009/05/08 - Generate INVALID_VALUE instead of
INVALID_OPERATION when passing <sync> parameters that are not the
names of sync objects. Remove leftover language saying that a bit of
state is needed to specify if the sync is shared or not. Add
clarification that requested <timeout> intervals are adjusted to the
closest value supported by the implementation, and a footnote that
FOREVER is just shorthand for the longest representable timeout.
Change parameter names and error handling for GetSynciv to be
consistent with other variable-length queries such as
Version 19, 2009/05/14 - Remove FOREVER and add sample code showing
how to wait in the server for a specified time, or for the
implementation-dependent maximum possible time. Resolve issue 24 by
saying we don't need a "default sync object".
Version 20, 2009/05/15 - Re-tag all issues still marked as
unresolved - none of them affect sync functionality, they are more
speculative for future uses of syncs, or details of spec writing.
Version 21, 2009/07/01 - "Sync" up with 3.2 core spec draft:
* Use GLsync instead of GLuint for sync object handle type in all
relevant commands,
* Change type of FenceSync <condition> to GLenum.
* Add <flags> argument to FenceSync and corresponding SYNC_FLAGS
* Clarify that the actual client wait time may be longer than the
requested <timeout> and that TIMEOUT_EXPIRED may be
returned even when ClientWaitSync is called with a
<timeout> of zero.
* Require the <timeout> parameter to WaitSync to be a no-op value.
* Remove SignalSync, until a sync object type other than a fence
sync is defined.
* Change type of <flags> parameter to
ClientWaitSync and WaitSync to GLbitfield.
* Add issues 31-33 describing some of the changes.
Version 22, 2009/07/01 - Add TIMEOUT_IGNORED and WAIT_FAILED to New
Tokens list.
Version 23, 2009/07/20 (Apollo 11 commemorative edition) - Assign
enum values.
Version 24, 2009/07/24 - Rename stray GetSyncuiv functions to
Version 25, 2009/09/18 - Correct spelling of SYNC_FLUSH_COMMAND_BIT
to SYNC_FLUSH_COMMANDS_BIT in several places.