EXT_external_objects_win32

GL_EXT_memory_object_win32
GL_EXT_semaphore_win32

Carsten Rohde, NVIDIA
James Jones, NVIDIA
Jan-Harald Fredriksen, ARM
Jeff Juliano, NVIDIA

James Jones, NVIDIA (jajones 'at' nvidia.com)

Complete

Last Modified Date: June 2, 2017
Revision: 8

505
OpenGL ES Extension #282

Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications

GL_EXT_memory_object_win32 requires GL_EXT_memory_object

GL_EXT_semaphore_win32 requires GL_EXT_semaphore

Building upon the OpenGL memory object and semaphore framework
defined in EXT_external_objects, this extension enables an OpenGL
application to import a memory object or semaphore from a Win32 NT
handle or a KMT share handle.

If the GL_EXT_memory_object_win32 string is reported, the following
commands are added:

void ImportMemoryWin32HandleEXT(uint memory,
                                uint64 size,
                                enum handleType,
                                void *handle);

void ImportMemoryWin32NameEXT(uint memory,
                              uint64 size,
                              enum handleType,
                              const void *name);

If the GL_EXT_semaphore_win32 string is reported, the following commands
are added:

void ImportSemaphoreWin32HandleEXT(uint semaphore,
                                   enum handleType,
                                   void *handle);

void ImportSemaphoreWin32NameEXT(uint semaphore,
                                 enum handleType,
                                 const void *name);

The following tokens are added if either of the
GL_EXT_memory_object_win32 or GL_EXT_semaphore_win32 strings are
reported:

Accepted by the <handleType> parameter of
ImportMemoryWin32HandleEXT(), ImportMemoryWin32NameEXT(),
ImportSemaphoreWin32HandleEXT(), and ImportSemaphoreWin32NameEXT():

    HANDLE_TYPE_OPAQUE_WIN32_EXT               0x9587

Accepted by the <handleType> parameter of
ImportMemoryWin32HandleEXT() and ImportSemaphoreWin32HandleEXT():

    HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT           0x9588

Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetFloatv,
GetIntegerv, GetInteger64v, GetBooleani_v, GetIntegeri_v, GetFloati_v,
GetDoublei_v, and GetInteger64i_v:

    DEVICE_LUID_EXT                            0x9599
    DEVICE_NODE_MASK_EXT                       0x959A

Constant values:

    LUID_SIZE_EXT                              8

If the GL_EXT_memory_object_win32 string is reported, the following
tokens are added:

Accepted by the <handleType> parameter of
ImportMemoryWin32HandleEXT() and ImportMemoryWin32NameEXT():

    HANDLE_TYPE_D3D12_TILEPOOL_EXT             0x9589
    HANDLE_TYPE_D3D12_RESOURCE_EXT             0x958A
    HANDLE_TYPE_D3D11_IMAGE_EXT                0x958B

Accepted by the <handleType> parameter of
ImportMemoryWin32HandleEXT():
    HANDLE_TYPE_D3D11_IMAGE_KMT_EXT            0x958C

If the GL_EXT_semaphore_win32 string is reported, the following tokens
are added:

Accepted by the <handleType> parameter of
ImportSemaphoreWin32HandleEXT():

    HANDLE_TYPE_D3D12_FENCE_EXT                0x9594

Accepted by the <pname> parameter of SemaphoreParameterui64v() and
GetSemaphoreParameterui64v():

    D3D12_FENCE_VALUE_EXT                      0x9595

Add the following entries to table 4.2 "Commands for importing
external semaphore handles."

    | Handle Type                      | Import commands                |
    +----------------------------------+--------------------------------+
    | HANDLE_TYPE_OPAQUE_WIN32_EXT     | ImportSemaphoreWin32HandleEXT, |
    |                                  | ImportSemaphoreWin32NameEXT    |
    | HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT | ImportSemaphoreWin32HandleEXT  |
    | HANDLE_TYPE_D3D12_FENCE_EXT      | ImportSemaphoreWin32HandleEXT, |
    |                                  | ImportSemaphoreWin32NameEXT    |
    +----------------------------------+--------------------------------+

Add the following after the second paragraph of section 4.2.1 "Importing
External Semaphore Handles into Semaphores"

    The devices in use by the current context may also be identified by
    an (LUID, node) pair.  To determine the LUID of the
    current context, call GetUnsignedBytev with <pname> set to
    DEVICE_LUID_EXT and <data> set to point to an array of LUID_SIZE_EXT
    unsigned bytes.  Following the call, <data> can be cast to a pointer
    to an LUID object that will be equal to the locally unique
    identifier of an IDXGIAdapter1 object corresponding to the adapter
    used by the current context.  To identify which individual devices
    within an adapter are used by the current context, call GetIntegerv
    with <pname> set to DEVICE_NODE_MASK_EXT.  A bitfield is returned
    with one bit set for each device node used by the current context.
    The bits set will be subset of those available on a Direct3D 12
    device created on an adapter with the same LUID as the current
    context.

Replace the paragraph in section 4.2.1 beginning "External handles
are often defined..." with the following

    The commands

        void ImportSemaphoreWin32HandleEXT(uint semaphore,
                                           enum handleType,
                                           void *handle);

        void ImportSemaphoreWin32NameEXT(uint semaphore,
                                         enum handleType,
                                         const void *name);

    import a semaphore from the win32 handle <handle> or the win32
    object name <name>.  <handle> is a windows HANDLE cast to the type
    "void*".  <name> is a NULL-terminated array of UTF-16 characters.
    What type of object <handle> or <name> refers to is determined by
    <handleType>.  Importing a Windows handle does not transfer
    ownership of the handle to the GL implementation.  For handle types
    defined as NT handles, the application must release the handle using
    an appropriate system call when it is no longer needed.

    The parameter <handle> takes the value of a windows HANDLE cast to


Add the following entries to table 4.3 "Semaphore parameters"

    | Name                  | Handle Types                | Legal Values |
    +-----------------------+-----------------------------+--------------+
    | D3D12_FENCE_VALUE_EXT | HANDLE_TYPE_D3D12_FENCE_EXT | any value    |
    +-----------------------+-----------------------------+--------------+

Add the following after the first paragraph of section 4.2.3 "Waiting
for Semaphores"

    If <semaphore> was imported from a handle of the type
    HANDLE_TYPE_D3D12_FENCE_EXT, it will reach the signaled state when
    its value is greater than or equal to the value specified by its
    D3D12_FENCE_VALUE_EXT parameter.

Add the following after the first paragraph of section 4.2.4 "Signaling
Semaphores"

    If <semaphore> was imported from a handle of the type
    HANDLE_TYPE_D3D12_FENCE_EXT, its value will be set to the value
    specified by its D3D12_FENCE_VALUE_EXT parameter when the signal
    operation completes.

Add the following entry to table 6.2 "Commands for importing
external memory handles."

    | Handle Type                      | Import command              |
    +----------------------------------+-----------------------------+
    | HANDLE_TYPE_OPAQUE_WIN32_EXT     | ImportMemoryWin32HandleEXT, |
    |                                  | ImportMemoryWin32NameEXT    |
    | HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT | ImportMemoryWin32HandleEXT, |
    | HANDLE_TYPE_D3D12_TILEPOOL_EXT   | ImportMemoryWin32HandleEXT, |
    |                                  | ImportMemoryWin32NameEXT    |
    | HANDLE_TYPE_D3D12_RESOURCE_EXT   | ImportMemoryWin32HandleEXT, |
    |                                  | ImportMemoryWin32NameEXT    |
    | HANDLE_TYPE_D3D11_IMAGE_EXT      | ImportMemoryWin32HandleEXT, |
    |                                  | ImportMemoryWin32NameEXT    |
    | HANDLE_TYPE_D3D11_KMT_IMAGE_EXT  | ImportMemoryWin32HandleEXT  |
    +----------------------------------------------------------------+

Replace the paragraph in section 6.1 beginning "External handles are
often defined..." with the following

    The commands

        void ImportMemoryWin32HandleEXT(uint memory,
                                        uint64 size,
                                        enum handleType,
                                        void *handle);

        void ImportMemoryWin32NameEXT(uint memory,
                                      uint64 size,
                                      enum handleType,
                                      const void *name);

    import a memory object of length <size> from the win32 handle
    <handle> or the win32 object name <name>.  <handle> is a windows
    HANDLE cast to the type "void*".  <name> is NULL-terminated array of
    UTF-16 characters.  What type of object <handle> or <name> refers to
    is determined by <handleType>.  Importing a Windows handle does not
    transfer ownership of the handle to the GL implementation.  For
    handle types defined as NT handles, the application must release the
    handle using an appropriate system call when it is no longer needed.

1) What should the type of the <name> parameter be in the functions
   ImportMemoryWin32NameEXT() and ImportSemaphoreWin32NameEXT()?

   RESOLVED: const void*.  There is no wchar type in GL, and the issues
   with C's wchar_t make it seem undesirable to introduce one.
   Further, wchar_t isn't necessarily the correct type.  The win32 type
   LPCWSTR is the fully correct type, but using it directly would
   introduce dependencies on windows headers in glext.h.  Reusing
   GLshort or GLushort would result in a correctly sized type, but
   casting would still often be needed, and it looks non-intuitive.
   Therefore, it seems best to leave the pointer loosely typed in the
   prototype and define its type through spec language.

Revision 8, 2017-06-02 (James Jones)
    - Added extension numbers.
    - Fixed the name of GL_HANDLE_TYPE_D3D12_RESOURCE_EXT.
    - Fixed the name -f GL_HANDLE_TYPE_D3D11_IMAGE_KMT_EXT.
    - Clarified which extensions each command and token belongs to.
    - Clarified how to assign values to the "handle" import parameters.
    - Marked complete.

Revision 7, 2017-05-24 (James Jones)
    - Filled in real token values
    - Refer to the GL implementation, not the Vulkan implementation.
    - ImportSemaphoreWin32HandleEXT is used to import semaphores,
      not ImportMemoryWin32HandleEXT.
    - Added name-based object import functions.

Revision 6, 2017-04-05 (James Jones)
    - Added context device LUID and node mask queries.

Revision 5, 2017-04-04 (James Jones)
    - Clarified the effects of import operations on handles.

Revision 4, 2017-03-17 (James Jones)
    - Renamed from KHR to EXT
    - Added D3D12 fence value semaphore parameter

Revision 3, 2016-09-28 (James Jones)
    - Merged the GL_KHR_memory_object_win32 and GL_KHR_semaphore_win32
      specs.
    - Added spec body describing how to use the new commands and tokens.

Revision 2, 2016-08-15 (Jeff Juliano)
    - Clarified overview text.

Revision 1, 2016-08-05 (James Jones)
    - Initial draft.