blob: 2874e40f900b3a4a571a9cf08548c69a6533c80a [file] [log] [blame]
Name
EXT_x11_sync_object
Name Strings
GL_EXT_x11_sync_object
Contributors
Piers Daniell
Pierre-Loup Griffais
James Jones
Aaron Plattner
Contact
James Jones, NVIDIA corporation (jajones 'at' nvidia.com)
Status
Complete.
Version
Last Modified Date: Jan 26, 2011
Author Revision: 2
Number
406
Dependencies
OpenGL 3.2, or an earlier OpenGL version supporting the ARB_sync
extension, is required.
Written based on the wording of the OpenGL 3.2 specification.
ARB_cl_event trivially affects the definition of this extension.
This extension is only supported with contexts created on an X11
display that supports the X Synchronization Extension version 3.1 or
later.
Overview
Synchronization objects added the ability to better coordinate
operations between multiple GL command streams. However, it is
desirable to have the same level of coordination between GL
command streams and external rendering APIs. This extension
introduces two new concepts to build upon the synchronization
infrastructure provided by ARB_sync:
1) A means to import an X Synchronization Fence object into the
GL and use it as a sync object.
2) The concept of a reusable sync object.
The latter is necessary because the import operation is expensive
and performing it every time a synchronization point was reached
would make the synchronization prohibitively slow.
This extension stops short of allowing the GL to change the state
of imported/reusable sync objects, but does not add any language
that would prohibit such functionality from being added in a
subsequent extension.
New Procedures and Functions
sync ImportSyncEXT(enum external_sync_type,
intptr external_sync,
bitfield flags);
New Types
None
New Tokens
Accepted by the <external_sync_type> parameter of
ImportSyncEXT:
SYNC_X11_FENCE_EXT 0x90E1
Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL
Operation)
None
Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)
None
Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment
Operations and the Framebuffer)
None
Additions to Chapter 5 of the OpenGL 3.2 Specification (Special
Functions)
Modify Section 5.2 "Sync Objects and Fences" (p. 241)
(Add after the seventh paragraph, p. 242)
"Additional types of sync objects can be imported from external
APIs. The command
sync ImportSyncEXT(enum external_sync_type,
intptr external_sync,
bitfield flags);
creates a GL sync object of the type <external_sync_type> based on
the object referred to by <external_sync>.
"<external_sync_type> must be SYNC_X11_FENCE_EXT, and
<external_sync> must be the XID of a valid X11 Synchronization Fence
object. The status of the sync object returned will be SIGNALED
when the X object is in the triggered state, or UNSIGNALED
otherwise.
"<flags> must be 0."
(Replace the last sentence of paragraph 8, p. 242)
"The initial property values for a sync object created by FenceSync
or ImportSyncEXT are shown in tables 5.1 or 5.2 respectively. A
sync object created using ImportSyncEXT should hold a reference to
any external resources needed to maintain the GL state associated
with the GL object should the external object be destroyed."
(Replace paragraph 9 with the following, p. 242)
"If FenceSync or ImportSyncEXT fail 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 or <external_sync_type> is not
SYNC_X11_FENCE_EXT. If <flags> is not zero, or if <external_sync>
does not refer to a valid X Synchronization Fence object, an
INVALID_VALUE error is generated.
"However, implementations are not required to validate
<external_sync>, and passing an invalid external sync object handle
may result in undefined behavior up to and including program
termination."
(Add table 5.2 immediately following table 5.1, p. 243)
Property Name Property Value
------------------------ -------------------------------------
OBJECT_TYPE <external_sync_type>
SYNC_CONDITION NONE
SYNC_STATUS dependent on state of <external_sync>
SYNC_FLAGS <flags>
Table 5.2: Initial properties of a sync object created with
ImportSyncEXT.
(Replace paragraph 12 with the following, p. 243)
"If <sync> is in the signaled state, 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 reaches the signaled state 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.
Modify section 5.2.2 "Signaling" (p. 245)
(Replace the first paragraph with the following, p. 245)
"A sync object enters the signaled state only once the corresponding
fence command has completed and signaled the sync object, or the
external sync object associated with it has reached a state
corresponding to the GL signaled state as described in table 5.3."
(Add table 5.3)
OBJECT_TYPE External state corresponding to GL signaled state
------------------ -------------------------------------------------
SYNC_X11_FENCE_EXT triggered
(Replace the last sentence of the last paragraph with the following,
p. 246)
"Additionally, sync objects linked to external sync objects require
implementation-specific, non-queriable internal state uniquely
identifying the external object. The initial values of sync object
state are defined as specified by FenceSync and ImportSyncEXT."
Additions to Chapter 6 of the OpenGL 3.2 Specification (State and State
Requests)
Modify section 6.1.7 "Sync Object State" (p. 256)
(Replace the last sentence of paragraph 4 with the following, p. 256)
"The only types supported are SYNC_FENCE and SYNC_X11_FENCE_EXT."
Additions to Appendix D of the OpenGL 3.2 Specification (Shared Objects
and Multiple Contexts)
Modify section D.1.2 "Deleted Object and Object Name Lifetimes"
(p. 324)
Replace sentence 3 in the first paragraph with the following, (p. 324)
"A sync object is in use while it is not in the signaled state, or
while there are any GL clients and/or servers blocked on the sync
object as a result of ClientWaitSync or WaitSync commands."
GLX Protocol
TBD
Dependencies on ARB_sync
ARB_sync or GL version 3.2 or above are required to implement this
extension.
Dependencies on ARB_cl_event
If ARB_cl_event is present, the language of the two specs must be
merged. There should be no technical conflicts, but the actual
text modifications overlap.
Errors
The error INVALID_ENUM is generated if ImportSyncEXT is called
where <external_sync_type> is not SYNC_X11_FENCE_EXT.
The error INVALID_VALUE is generated if ImportSyncEXT is called
where <external_sync> does not refer to a valid X11 Synchronization
Fence object.
The error INVALID_VALUE is generated if ImportSyncEXT is called
where <flags> is not 0.
New State
None
Issues
1) Should the import command be a generic entry point, or
specialized for X11 sync fence objects?
RESOLVED: A generic command is used. This command can be reused
by future extensions to import other sync types. It takes a
pointer-sized parameter that can be used to import any type of
synchronization object. Objects that require more than one
value to uniquely identify them, e.g. OpenCL events, can define
an intermediate structure that contains all required values and
then pass in a pointer to the structure.
2) What happens if the X11 sync object is destroyed while the GL
sync object referencing it is still in use?
RESOLVED: The GL object should hold a reference on any resources
needed to continue using the sync object until the GL object is
deleted.
Revision History
Date: 26-Jan-2011
Revision: 2 (James Jones)
- Renamed from EXT_x_sync_object to EXT_x11_sync_object.
- Added issues 1 and 2 and related spec language.
- Added language describing when external syncs are signaled.
- Added language describing when external syncs are deleted.
Date: 20-Jan-2011
Revision: 1 (James Jones)
- Initial Revision.