xref: /third_party/openGLES/extensions/EXT/EXT_win32_keyed_mutex.txt

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.