• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    EXT_external_objects_win32
4
5Name Strings
6
7    GL_EXT_memory_object_win32
8    GL_EXT_semaphore_win32
9
10Contributors
11
12    Carsten Rohde, NVIDIA
13    James Jones, NVIDIA
14    Jan-Harald Fredriksen, ARM
15    Jeff Juliano, NVIDIA
16
17Contact
18
19    James Jones, NVIDIA (jajones 'at' nvidia.com)
20
21Status
22
23    Complete
24
25Version
26
27    Last Modified Date: June 2, 2017
28    Revision: 8
29
30Number
31
32    505
33    OpenGL ES Extension #282
34
35Dependencies
36
37    Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications
38
39    GL_EXT_memory_object_win32 requires GL_EXT_memory_object
40
41    GL_EXT_semaphore_win32 requires GL_EXT_semaphore
42
43Overview
44
45    Building upon the OpenGL memory object and semaphore framework
46    defined in EXT_external_objects, this extension enables an OpenGL
47    application to import a memory object or semaphore from a Win32 NT
48    handle or a KMT share handle.
49
50
51New Procedures and Functions
52
53    If the GL_EXT_memory_object_win32 string is reported, the following
54    commands are added:
55
56    void ImportMemoryWin32HandleEXT(uint memory,
57                                    uint64 size,
58                                    enum handleType,
59                                    void *handle);
60
61    void ImportMemoryWin32NameEXT(uint memory,
62                                  uint64 size,
63                                  enum handleType,
64                                  const void *name);
65
66    If the GL_EXT_semaphore_win32 string is reported, the following commands
67    are added:
68
69    void ImportSemaphoreWin32HandleEXT(uint semaphore,
70                                       enum handleType,
71                                       void *handle);
72
73    void ImportSemaphoreWin32NameEXT(uint semaphore,
74                                     enum handleType,
75                                     const void *name);
76
77New Tokens
78
79    The following tokens are added if either of the
80    GL_EXT_memory_object_win32 or GL_EXT_semaphore_win32 strings are
81    reported:
82
83    Accepted by the <handleType> parameter of
84    ImportMemoryWin32HandleEXT(), ImportMemoryWin32NameEXT(),
85    ImportSemaphoreWin32HandleEXT(), and ImportSemaphoreWin32NameEXT():
86
87        HANDLE_TYPE_OPAQUE_WIN32_EXT               0x9587
88
89    Accepted by the <handleType> parameter of
90    ImportMemoryWin32HandleEXT() and ImportSemaphoreWin32HandleEXT():
91
92        HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT           0x9588
93
94    Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetFloatv,
95    GetIntegerv, GetInteger64v, GetBooleani_v, GetIntegeri_v, GetFloati_v,
96    GetDoublei_v, and GetInteger64i_v:
97
98        DEVICE_LUID_EXT                            0x9599
99        DEVICE_NODE_MASK_EXT                       0x959A
100
101    Constant values:
102
103        LUID_SIZE_EXT                              8
104
105    If the GL_EXT_memory_object_win32 string is reported, the following
106    tokens are added:
107
108    Accepted by the <handleType> parameter of
109    ImportMemoryWin32HandleEXT() and ImportMemoryWin32NameEXT():
110
111        HANDLE_TYPE_D3D12_TILEPOOL_EXT             0x9589
112        HANDLE_TYPE_D3D12_RESOURCE_EXT             0x958A
113        HANDLE_TYPE_D3D11_IMAGE_EXT                0x958B
114
115    Accepted by the <handleType> parameter of
116    ImportMemoryWin32HandleEXT():
117        HANDLE_TYPE_D3D11_IMAGE_KMT_EXT            0x958C
118
119    If the GL_EXT_semaphore_win32 string is reported, the following tokens
120    are added:
121
122    Accepted by the <handleType> parameter of
123    ImportSemaphoreWin32HandleEXT():
124
125        HANDLE_TYPE_D3D12_FENCE_EXT                0x9594
126
127    Accepted by the <pname> parameter of SemaphoreParameterui64v() and
128    GetSemaphoreParameterui64v():
129
130        D3D12_FENCE_VALUE_EXT                      0x9595
131
132Additions to Chapter 4 of the OpenGL 4.5 Specification (Event Model)
133
134    Add the following entries to table 4.2 "Commands for importing
135    external semaphore handles."
136
137        | Handle Type                      | Import commands                |
138        +----------------------------------+--------------------------------+
139        | HANDLE_TYPE_OPAQUE_WIN32_EXT     | ImportSemaphoreWin32HandleEXT, |
140        |                                  | ImportSemaphoreWin32NameEXT    |
141        | HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT | ImportSemaphoreWin32HandleEXT  |
142        | HANDLE_TYPE_D3D12_FENCE_EXT      | ImportSemaphoreWin32HandleEXT, |
143        |                                  | ImportSemaphoreWin32NameEXT    |
144        +----------------------------------+--------------------------------+
145
146    Add the following after the second paragraph of section 4.2.1 "Importing
147    External Semaphore Handles into Semaphores"
148
149        The devices in use by the current context may also be identified by
150        an (LUID, node) pair.  To determine the LUID of the
151        current context, call GetUnsignedBytev with <pname> set to
152        DEVICE_LUID_EXT and <data> set to point to an array of LUID_SIZE_EXT
153        unsigned bytes.  Following the call, <data> can be cast to a pointer
154        to an LUID object that will be equal to the locally unique
155        identifier of an IDXGIAdapter1 object corresponding to the adapter
156        used by the current context.  To identify which individual devices
157        within an adapter are used by the current context, call GetIntegerv
158        with <pname> set to DEVICE_NODE_MASK_EXT.  A bitfield is returned
159        with one bit set for each device node used by the current context.
160        The bits set will be subset of those available on a Direct3D 12
161        device created on an adapter with the same LUID as the current
162        context.
163
164    Replace the paragraph in section 4.2.1 beginning "External handles
165    are often defined..." with the following
166
167        The commands
168
169            void ImportSemaphoreWin32HandleEXT(uint semaphore,
170                                               enum handleType,
171                                               void *handle);
172
173            void ImportSemaphoreWin32NameEXT(uint semaphore,
174                                             enum handleType,
175                                             const void *name);
176
177        import a semaphore from the win32 handle <handle> or the win32
178        object name <name>.  <handle> is a windows HANDLE cast to the type
179        "void*".  <name> is a NULL-terminated array of UTF-16 characters.
180        What type of object <handle> or <name> refers to is determined by
181        <handleType>.  Importing a Windows handle does not transfer
182        ownership of the handle to the GL implementation.  For handle types
183        defined as NT handles, the application must release the handle using
184        an appropriate system call when it is no longer needed.
185
186        The parameter <handle> takes the value of a windows HANDLE cast to
187
188
189    Add the following entries to table 4.3 "Semaphore parameters"
190
191        | Name                  | Handle Types                | Legal Values |
192        +-----------------------+-----------------------------+--------------+
193        | D3D12_FENCE_VALUE_EXT | HANDLE_TYPE_D3D12_FENCE_EXT | any value    |
194        +-----------------------+-----------------------------+--------------+
195
196    Add the following after the first paragraph of section 4.2.3 "Waiting
197    for Semaphores"
198
199        If <semaphore> was imported from a handle of the type
200        HANDLE_TYPE_D3D12_FENCE_EXT, it will reach the signaled state when
201        its value is greater than or equal to the value specified by its
202        D3D12_FENCE_VALUE_EXT parameter.
203
204    Add the following after the first paragraph of section 4.2.4 "Signaling
205    Semaphores"
206
207        If <semaphore> was imported from a handle of the type
208        HANDLE_TYPE_D3D12_FENCE_EXT, its value will be set to the value
209        specified by its D3D12_FENCE_VALUE_EXT parameter when the signal
210        operation completes.
211
212Additions to Chapter 6 of the OpenGL 4.5 Specification (Memory Objects)
213
214    Add the following entry to table 6.2 "Commands for importing
215    external memory handles."
216
217        | Handle Type                      | Import command              |
218        +----------------------------------+-----------------------------+
219        | HANDLE_TYPE_OPAQUE_WIN32_EXT     | ImportMemoryWin32HandleEXT, |
220        |                                  | ImportMemoryWin32NameEXT    |
221        | HANDLE_TYPE_OPAQUE_WIN32_KMT_EXT | ImportMemoryWin32HandleEXT, |
222        | HANDLE_TYPE_D3D12_TILEPOOL_EXT   | ImportMemoryWin32HandleEXT, |
223        |                                  | ImportMemoryWin32NameEXT    |
224        | HANDLE_TYPE_D3D12_RESOURCE_EXT   | ImportMemoryWin32HandleEXT, |
225        |                                  | ImportMemoryWin32NameEXT    |
226        | HANDLE_TYPE_D3D11_IMAGE_EXT      | ImportMemoryWin32HandleEXT, |
227        |                                  | ImportMemoryWin32NameEXT    |
228        | HANDLE_TYPE_D3D11_KMT_IMAGE_EXT  | ImportMemoryWin32HandleEXT  |
229        +----------------------------------------------------------------+
230
231    Replace the paragraph in section 6.1 beginning "External handles are
232    often defined..." with the following
233
234        The commands
235
236            void ImportMemoryWin32HandleEXT(uint memory,
237                                            uint64 size,
238                                            enum handleType,
239                                            void *handle);
240
241            void ImportMemoryWin32NameEXT(uint memory,
242                                          uint64 size,
243                                          enum handleType,
244                                          const void *name);
245
246        import a memory object of length <size> from the win32 handle
247        <handle> or the win32 object name <name>.  <handle> is a windows
248        HANDLE cast to the type "void*".  <name> is NULL-terminated array of
249        UTF-16 characters.  What type of object <handle> or <name> refers to
250        is determined by <handleType>.  Importing a Windows handle does not
251        transfer ownership of the handle to the GL implementation.  For
252        handle types defined as NT handles, the application must release the
253        handle using an appropriate system call when it is no longer needed.
254
255Additions to Chapter 21 of the OpenGL 4.5 Specification (Special Functions)
256
257    Add the following to section 21.4.1, Commands Not Usable in Display
258    Lists.
259
260    Under the "Memory Objects" section:
261
262        ImportMemoryWin32HandleEXT, ImportMemoryWin32NameEXT
263
264    Under the "GL command stream management" section:
265
266        ImportSemaphoreWin32HandleEXT, ImportSemaphoreWin32NameEXT
267
268Issues
269
270    1) What should the type of the <name> parameter be in the functions
271       ImportMemoryWin32NameEXT() and ImportSemaphoreWin32NameEXT()?
272
273       RESOLVED: const void*.  There is no wchar type in GL, and the issues
274       with C's wchar_t make it seem undesirable to introduce one.
275       Further, wchar_t isn't necessarily the correct type.  The win32 type
276       LPCWSTR is the fully correct type, but using it directly would
277       introduce dependencies on windows headers in glext.h.  Reusing
278       GLshort or GLushort would result in a correctly sized type, but
279       casting would still often be needed, and it looks non-intuitive.
280       Therefore, it seems best to leave the pointer loosely typed in the
281       prototype and define its type through spec language.
282
283Revision History
284
285    Revision 9, 2022-07-15 (James Jones)
286        - Added commands to the list of commands not permitted in display
287          lists.
288
289    Revision 8, 2017-06-02 (James Jones)
290        - Added extension numbers.
291        - Fixed the name of GL_HANDLE_TYPE_D3D12_RESOURCE_EXT.
292        - Fixed the name -f GL_HANDLE_TYPE_D3D11_IMAGE_KMT_EXT.
293        - Clarified which extensions each command and token belongs to.
294        - Clarified how to assign values to the "handle" import parameters.
295        - Marked complete.
296
297    Revision 7, 2017-05-24 (James Jones)
298        - Filled in real token values
299        - Refer to the GL implementation, not the Vulkan implementation.
300        - ImportSemaphoreWin32HandleEXT is used to import semaphores,
301          not ImportMemoryWin32HandleEXT.
302        - Added name-based object import functions.
303
304    Revision 6, 2017-04-05 (James Jones)
305        - Added context device LUID and node mask queries.
306
307    Revision 5, 2017-04-04 (James Jones)
308        - Clarified the effects of import operations on handles.
309
310    Revision 4, 2017-03-17 (James Jones)
311        - Renamed from KHR to EXT
312        - Added D3D12 fence value semaphore parameter
313
314    Revision 3, 2016-09-28 (James Jones)
315        - Merged the GL_KHR_memory_object_win32 and GL_KHR_semaphore_win32
316          specs.
317        - Added spec body describing how to use the new commands and tokens.
318
319    Revision 2, 2016-08-15 (Jeff Juliano)
320        - Clarified overview text.
321
322    Revision 1, 2016-08-05 (James Jones)
323        - Initial draft.
324