blob: 9b9b304fd3261b68b15b8641d58b237a284a46eb [file] [log] [blame]
Name
APPLE_sync
Name Strings
GL_APPLE_sync
Contributors
Contributors to ARB_sync desktop OpenGL extension from which this
extension borrows heavily
Contact
Benj Lipchak (lipchak 'at' apple 'dot' com)
Status
Complete
Version
Last Modified Date: July 10, 2012
Author Revision: 3
Number
OpenGL ES Extension #124
Dependencies
OpenGL ES 1.1 or OpenGL ES 2.0 is required.
This specification is written against the OpenGL ES 2.0.25 specification.
EXT_debug_label affects the definition of this extension.
Overview
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
process.
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 FenceSyncAPPLE(enum condition, bitfield flags);
boolean IsSyncAPPLE(sync sync);
void DeleteSyncAPPLE(sync sync);
enum ClientWaitSyncAPPLE(sync sync, bitfield flags, uint64 timeout);
void WaitSyncAPPLE(sync sync, bitfield flags, uint64 timeout);
void GetInteger64vAPPLE(enum pname, int64 *params);
void GetSyncivAPPLE(sync sync, enum pname, sizei bufSize, sizei *length,
int *values);
New Tokens
Accepted as the <pname> parameter of GetInteger64vAPPLE:
MAX_SERVER_WAIT_TIMEOUT_APPLE 0x9111
Accepted as the <pname> parameter of GetSyncivAPPLE:
OBJECT_TYPE_APPLE 0x9112
SYNC_CONDITION_APPLE 0x9113
SYNC_STATUS_APPLE 0x9114
SYNC_FLAGS_APPLE 0x9115
Returned in <values> for GetSynciv <pname> OBJECT_TYPE_APPLE:
SYNC_FENCE_APPLE 0x9116
Returned in <values> for GetSyncivAPPLE <pname> SYNC_CONDITION_APPLE:
SYNC_GPU_COMMANDS_COMPLETE_APPLE 0x9117
Returned in <values> for GetSyncivAPPLE <pname> SYNC_STATUS_APPLE:
UNSIGNALED_APPLE 0x9118
SIGNALED_APPLE 0x9119
Accepted in the <flags> parameter of ClientWaitSyncAPPLE:
SYNC_FLUSH_COMMANDS_BIT_APPLE 0x00000001
Accepted in the <timeout> parameter of WaitSyncAPPLE:
TIMEOUT_IGNORED_APPLE 0xFFFFFFFFFFFFFFFFull
Returned by ClientWaitSyncAPPLE:
ALREADY_SIGNALED_APPLE 0x911A
TIMEOUT_EXPIRED_APPLE 0x911B
CONDITION_SATISFIED_APPLE 0x911C
WAIT_FAILED_APPLE 0x911D
Accepted by the <type> parameter of LabelObjectEXT and
GetObjectLabelEXT:
SYNC_OBJECT_APPLE 0x8A53
Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation)
Add to Table 2.2, GL data types:
"GL Type Minimum Description
Bit Width
------- --------- ----------------------------------------------
int64 64 Signed 2's complement binary integer
uint64 64 Unsigned binary integer
sync <ptrbits> Sync object handle (see section 5.2)"
Additions to Chapter 5 of the OpenGL ES 2.0 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 occuring in
the GL state machine or in the graphics pipeline, and for
synchronizing between multiple graphics contexts, among other
purposes.
Sync objects have a status value with two possible states:
<signaled> and <unsignaled>. Events are associated with a sync
object. When a 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). 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 FenceSyncAPPLE(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 ClientWaitSyncAPPLE or WaitSyncAPPLE commands (see below) blocking
on <sync> to <unblock>. No other state is affected by FenceSyncAPPLE
or by execution of the associated fence command.
<condition> must be SYNC_GPU_COMMANDS_COMPLETE_APPLE. 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
some time 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 FenceSyncAPPLE
are shown in table 5.props:
Property Name Property Value
-------------------- ----------------
OBJECT_TYPE_APPLE SYNC_FENCE_APPLE
SYNC_CONDITION_APPLE <condition>
SYNC_STATUS_APPLE UNSIGNALED_APPLE
SYNC_FLAGS_APPLE <flags>
--------------------------------------
Table 5.props: Initial properties of a
sync object created with FenceSyncAPPLE.
Properties of a sync object may be queried with GetSyncivAPPLE (see
section 6.1.6). The SYNC_STATUS_APPLE property will be changed to
SIGNALED_APPLE when <condition> is satisfied.
If FenceSyncAPPLE 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_APPLE. 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 DeleteSyncAPPLE(sync sync);
If the fence command corresponding to the specified sync object has
completed, or if no ClientWaitSyncAPPLE or WaitSyncAPPLE 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
ClientWaitSyncAPPLE or WaitSyncAPPLE command. In either case, after
returning from DeleteSyncAPPLE the <sync> name is invalid and can no
longer be used to refer to the sync object.
DeleteSyncAPPLE 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 ClientWaitSyncAPPLE(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 ClientWaitSyncAPPLE is called
then ClientWaitSyncAPPLE returns immediately. If <sync> is unsignaled
at the time ClientWaitSyncAPPLE is called then ClientWaitSyncAPPLE 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_APPLE, as discussed in section 5.2.2.
ClientWaitSyncAPPLE returns one of four status values. A return value of
ALREADY_SIGNALED_APPLE indicates that <sync> was signaled at the time
ClientWaitSyncAPPLE was called. ALREADY_SIGNALED_APPLE will always be
returned if <sync> was signaled, even if the value of <timeout> is zero.
A return value of TIMEOUT_EXPIRED_APPLE indicates that the specified
timeout period expired before <sync> was signaled. A return value of
CONDITION_SATISFIED_APPLE indicates that <sync> was signaled before the
timeout expired. Finally, if an error occurs, in addition to
generating a GL error as specified below, ClientWaitSyncAPPLE immediately
returns WAIT_FAILED_APPLE without blocking.
If the value of <timeout> is zero, then ClientWaitSyncAPPLE does not
block, but simply tests the current state of <sync>.
TIMEOUT_EXPIRED_APPLE 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
SYNC_FLUSH_COMMANDS_BIT_APPLE, an INVALID_VALUE error is generated.
The command
void WaitSyncAPPLE(sync sync, bitfield flags, uint64 timeout);
is similar to ClientWaitSyncAPPLE, but instead of blocking and not
returning to the application until <sync> is signaled, WaitSyncAPPLE
returns immediately, instead causing the GL server [fn2] to block
until <sync> is signaled [fn3].
[fn2 - 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.]
[fn3 - WaitSyncAPPLE allows applications to continue to queue commands
from the client in anticipation of the sync being signalled,
increasing client-server parallelism.]
<sync> has the same meaning as for ClientWaitSyncAPPLE.
<timeout> must currently be the special value TIMEOUT_IGNORED_APPLE, and
is not used. Instead, WaitSyncAPPLE will always wait no longer than an
implementation-dependent timeout. The duration of this timeout in
nanoseconds may be queried by calling GetInteger64vAPPLE with <value>
MAX_SERVER_WAIT_TIMEOUT_APPLE. There is currently no way to determine
whether WaitSyncAPPLE unblocked because the timeout expired or because
the sync object being waited on was signaled.
<flags> must be 0.
If an error occurs, WaitSyncAPPLE 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_APPLE, or <flags>
is not zero, an INVALID_VALUE error is generated [fn4].
[fn4 - <flags> and <timeout> are placeholders for anticipated future
extensions of sync object capabilities. They must have these reserved
values in order that existing code calling WaitSyncAPPLE operate properly
in the presence of such extensions.]
Multiple Waiters
----------------
It is possible for both the GL client to be blocked on a sync object
in a ClientWaitSyncAPPLE command, the GL server to be blocked as the
result of a previous WaitSyncAPPLE command, and for additional
WaitSyncAPPLE 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 WaitSyncAPPLE commands will continue immediately when they are
reached.
See appendix C.2 for more information about blocking on a sync
object in multiple GL contexts.
5.2.2 Signalling
----------------
A fence sync object can be in the signaled state only once the
corresponding fence command has completed and signaled the sync
object.
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 ClientWaitSyncAPPLE
may hang forever. To help prevent this behavior [fn5], if the
SYNC_FLUSH_COMMANDS_BIT_APPLE bit is set in <flags>, and <sync> is
unsignaled when ClientWaitSyncAPPLE is called, then the equivalent of
Flush will be performed before blocking on <sync>.
[fn5 - The simple flushing behavior defined by
SYNC_FLUSH_COMMANDS_BIT_APPLE 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 ClientWaitSyncAPPLE command, or a GL server is
blocking on that object as a result of a prior WaitSyncAPPLE 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 C.
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 FenceSyncAPPLE."
Update the Debug Labels section's last sentence to include
SYNC_OBJECT_APPLE as a value supported for the <type> passed to
LabelObjectEXT.
Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
Requests)
Add GetInteger64vAPPLE to the first list of commands in section 6.1.1
"Simple Queries", and change the next sentence to mention the query:
"There are four commands for obtaining simple state variables:
...
void GetInteger64vAPPLE(enum value, int64 *data);
...
The commands obtain boolean, integer, 64-bit integer, or
floating-point..."
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 GetInteger64vAPPLE 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 "String Queries" (subsection
6.1.5) describing sync object queries. Renumber existing subsection
6.1.6 "Buffer Object Queries" and all following 6.1.* subsections.
"6.1.6 Sync Object Queries
Properties of sync objects may be queried using the command
void GetSyncivAPPLE(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, GetSyncivAPPLE 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_APPLE, a single value representing the specific
type of the sync object is placed in <values>. The only type
supported is SYNC_FENCE_APPLE.
If <pname> is SYNC_STATUS_APPLE, a single value representing the status of
the sync object (SIGNALED_APPLE or UNSIGNALED_APPLE) is placed in <values>.
If <pname> is SYNC_CONDITION_APPLE, a single value representing the
condition of the sync object is placed in <values>. The only
condition supported is SYNC_GPU_COMMANDS_COMPLETE_APPLE.
If <pname> is SYNC_FLAGS_APPLE, 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 IsSyncAPPLE(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,
IsSyncAPPLE returns FALSE (note that zero is not the name of a sync
object).
Sync object names immediately become invalid after calling
DeleteSyncAPPLE, 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 *WaitSyncAPPLE command."
Update the Debug Labels section's last sentence to include
SYNC_OBJECT_APPLE as a value supported for the <type> passed to
GetObjectLabelEXT.
Additions to Appendix C (Shared Objects and Multiple Contexts)
In the third paragraph of the appendix, add "sync objects" to the
list of shared state.
Add "sync objects" to the list of objects in the first sentence of
C.1.3. Append the following to the first paragraph of C.1.3:
"A sync object is in use while there is a corresponding fence command
which has not yet completed and signaled the sync object, or while
there are any GL clients and/or servers blocked on the sync object as
a result of ClientWaitSyncAPPLE or WaitSyncAPPLE commands."
"C.1.3 Deleted Object and Object Name Lifetimes
Insert a new section following "Object Deletion Behavior" (section
C.1) describing sync object multicontext behavior. Renumber existing
section C.2 "Propagating State Changes..." and all following C.*
sections.
"C.2 Sync Objects and Multiple Contexts
--------------------------------------
When multiple GL clients and/or servers are blocked on a single sync
object and that sync object is signalled, all such blocks are released.
The order in which blocks are released is implementation-dependent."
Edit the former C.2.1 to read as follows:
"C.3.1 Determining Completion of Changes to an object
----------------------------------------------------
The contents of an object T are considered to have been changed once
a command such as described in section C.2 has completed. Completion
of a command [fn6] may be determined either by calling Finish, or by
calling FenceSyncAPPLE and executing a WaitSyncAPPLE 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.
[fn6: 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.]"
Dependencies on EXT_debug_label
If EXT_debug_label is not available, omit the updates to Debug label
sections of chapters 5 and 6, and omit SYNC_OBJECT_APPLE from Table 6.X.
Errors
INVALID_VALUE is generated if the <sync> parameter of
ClientWaitSyncAPPLE, WaitSyncAPPLE, or GetSyncivAPPLE is not the name
of a sync object.
INVALID_VALUE is generated if the <sync> parameter of DeleteSyncAPPLE
is neither zero nor the name of a sync object.
INVALID_ENUM is generated if the <condition> parameter of FenceSyncAPPLE
is not SYNC_GPU_COMMANDS_COMPLETE_APPLE.
INVALID_VALUE is generated if the <flags> parameter of
ClientWaitSyncAPPLE contains bits other than SYNC_FLUSH_COMMANDS_BIT_APPLE,
or if the <flags> parameter of WaitSyncAPPLE is nonzero.
INVALID_ENUM is generated if the <pname> parameter of GetSyncivAPPLE is
neither OBJECT_TYPE_APPLE, SYNC_CONDITION_APPLE, SYNC_FLAGS_APPLE, nor
SYNC_STATUS_APPLE.
New State
Table 6.X. Sync Objects.
Get value Type Get command Initial value Description Section
-------------------- ---- ----------------- -------------------------------- --------------------- -------
OBJECT_TYPE_APPLE Z_1 GetSyncivAPPLE SYNC_FENCE_APPLE Type of sync object 5.2
SYNC_STATUS_APPLE Z_2 GetSyncivAPPLE UNSIGNALED_APPLE Sync object status 5.2
SYNC_CONDITION_APPLE Z_1 GetSyncivAPPLE SYNC_GPU_COMMANDS_COMPLETE_APPLE Sync object condition 5.2
SYNC_FLAGS_APPLE Z GetSyncivAPPLE SYNC_FLAGS_APPLE Sync object flags 5.2
SYNC_OBJECT_APPLE 0*xc GetObjectLabelEXT empty Debug label 5.X
New Implementation Dependent State
Table 40. Implementation Dependent Values (cont.)
Get value Type Get command Min. value Description Section
------------------ ---- ------------- ---------- ---------------- -------
MAX_SERVER_WAIT_ Z^+ GetInteger64v 0 Maximum WaitSync 5.2
TIMEOUT_APPLE timeout interval
Sample Code
... kick off a lengthy GL operation
/* Place a fence and associate a fence sync object */
GLsyncAPPLE sync = glFenceSyncAPPLE(GLSYNC_GPU_COMMANDS_COMPLETE_APPLE, 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:
*/
GLuint64APPLE timeout = num_seconds * ((GLuint64)1000 * 1000 * 1000);
glWaitSyncAPPLE(sync, 0, timeout);
/* Or to determine the maximum possible wait interval and wait
* that long, do this instead:
*/
GLuint64APPLE max_timeout;
glGetInteger64vAPPLE(GL_MAX_SERVER_WAIT_TIMEOUT_APPLE, &max_timeout);
glWaitSyncAPPLE(sync, 0, max_timeout);
Issues
See ARB_sync issues list: http://www.opengl.org/registry/specs/ARB/sync.txt
Revision History
Version 3, 2012/07/10 - Add support for debug label extension.
Version 2, 2012/06/18 - Correct spec to indicate ES 1.1 may also be okay.
Version 1, 2012/06/01 - Conversion from ARB_sync to APPLE_sync for ES.