blob: eee82b96cb1b461bf188a94093449b6ebcce336f [file] [log] [blame]
Name
EXT_win32_keyed_mutex
Name Strings
GL_EXT_win32_keyed_mutex
Contributors
Carsten Rohde, NVIDIA
James Jones, NVIDIA
Contact
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Version
Last Modified Date: June 6, 2017
Revision: 2
Number
506
OpenGL ES Extension #283
Dependencies
Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications.
Requires GL_EXT_memory_object.
Overview
Direct3D image objects may have a built-in synchronization primitive
associated with them that can be used to synchronize access to their
contents across process and API boundaries. This extension provides
access to that synchronization primitive via two new commands that
operate on GL memory objects.
New Procedures and Functions
boolean AcquireKeyedMutexWin32EXT(uint memory,
uint64 key,
uint timeout);
boolean ReleaseKeyedMutexWin32EXT(uint memory,
uint64 key);
New Tokens
Additions to Chapter 4 of the OpenGL 4.5 Specification (Event Model)
Add a new section between sections 4.1, "Sync Objects and Fences"
and section 4.2, "Query Objects and Asynchronous Queries"
4.2 Memory Object Keyed Mutexes
Memory objects imported with the handle types
HANDLE_TYPE_D3D11_IMAGE_EXT and HANDLE_TYPE_D3D11_KMT_IMAGE_EXT may
have a synchronization object known as a keyed mutex associated with
them. The exact behavior and conditions governing availability of
these objects is beyond the scope of this specification, but their
state can be manipulated by performing operations on the memory
object with which they are associated.
To block GL command processing until a keyed mutex is acquired, call
boolean AcquireKeyedMutexWin32EXT(uint memory,
uint64 key,
uint timeout);
where <memory> identifies which keyed mutex to acquire, <key> is the
mutex value to wait for, and <timeout> is the time, in milliseconds,
to wait before failing the acquire operation.
FALSE is returned if the acquire operation timed out or failed. No
error is generated if the operation failed because it timed out.
TRUE is returned if the wait succeeded.
To release a keyed mutex after all prior GL command processing has
completed, call
boolean ReleaseKeyedMutexWin32EXT(uint memory,
uint64 key);
where <memory> identifies the keyed mutex to release, and <key> is
the mutex value set by the release operation.
FALSE is returned if the release operation failed. TRUE is returned
if the release operation succeeded.
Errors
INVALID_VALUE is generated by AcquireKeyedMutexWin32EXT and
ReleaseKeyedMutexWin32EXT if <memory> is not a valid memory object
associated memory.
INVALID_VALUE is generated by AcquireKeyedMutexWin32EXT and
ReleaseKeyedMutexWin32EXT if the memory resource referred to by
<memory> has no associated keyed mutex.
INVALID_OPERATION is generated by AcquireKeyedMutexWin32EXT and
ReleaseKeyedMutexWin32EXT if the acquire or release operation failed
for operating-system-specific reasons.
New State
Issues
None.
Revision History
Revision 2, 2016-06-06 (James Jones)
- Added extension numbers.
- Marked complete.
Revision 1, 2017-03-31 (James Jones)
- Initial draft.