blob: b763f6db4fc83511de7400a71bef343873ffd8a6 [file] [log] [blame]
Name
EXT_external_objects_win32
Name Strings
GL_EXT_memory_object_win32
GL_EXT_semaphore_win32
Contributors
Carsten Rohde, NVIDIA
James Jones, NVIDIA
Jan-Harald Fredriksen, ARM
Jeff Juliano, NVIDIA
Contact
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Version
Last Modified Date: June 2, 2017
Revision: 8
Number
505
OpenGL ES Extension #282
Dependencies
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
Overview
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.
New Procedures and Functions
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);
New Tokens
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
Additions to Chapter 4 of the OpenGL 4.5 Specification (Event Model)
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.
Additions to Chapter 6 of the OpenGL 4.5 Specification (Memory Objects)
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.
Issues
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 History
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.