// Copyright (c) 2016-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[VK_KHX_external_semaphore_win32]]
== VK_KHX_external_semaphore_win32

*Name String*::
    +VK_KHX_external_semaphore_win32+
*Extension Type*::
    Device extension
*Registered Extension Number*::
    79
*Status*::
    Draft
*Last Modified Date*::
    2016-10-21
*Revision*::
    1
*IP Status*::
    No known IP claims.
*Dependencies*::
  - This extension is written against version 1.0 of the Vulkan API.
  - Requires +VK_KHR_external_semaphore_capabilities+.
*Contributors*::
  - James Jones, NVIDIA
  - Jeff Juliano, NVIDIA
  - Carsten Rohde, NVIDIA
*Contact*::
    James Jones (jajones 'at' nvidia.com)

An application using external memory may wish to synchronize access to that
memory using semaphores.
This extension enables an application to export semaphore state to and
import semaphore state from Windows handles.

=== New Object Types

None.

=== New Enum Constants

  * ename:VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHX
  * ename:VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHX
  * ename:VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHX

=== New Enums

None.

=== New Structs

  * slink:VkImportSemaphoreWin32HandleInfoKHX
  * slink:VkExportSemaphoreWin32HandleInfoKHX
  * slink:VkD3D12FenceSubmitInfoKHX

=== New Functions

  * flink:vkImportSemaphoreWin32HandleKHX
  * flink:vkGetSemaphoreWin32HandleKHX

=== Issues

1) Do applications need to call code:CloseHandle() on the values returned
from flink:vkGetSemaphoreWin32HandleKHX when pname:handleType is
ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHX?

*RESOLVED*: Yes, unless it is passed back in to another driver instance to
import the object.
A successful get call transfers ownership of the handle to the application.
Destroying the semaphore object will not destroy the handle or the handle's
reference to the underlying semaphore resource.

2) Should the language regarding KMT/Windows 7 handles be moved to a
separate extension so that it can be deprecated over time?

*RESOLVED*: No.
Support for them can be deprecated by drivers if they choose, by no longer
returning them in the supported handle types of the instance level queries.

3) Should applications be allowed to specify additional object attributes
for shared handles?

*RESOLVED*: Yes.
Applications will be allowed to provide similar attributes to those they
would to any other handle creation API.

4) How do applications communicate the desired fence values to use with
D3D12_FENCE-based Vulkan semaphores?

*RESOLVED*: There are a couple of options.
The values for the signaled and reset states could be communicated up front
when creating the object and remain static for the life of the Vulkan
semaphore, or they could be specified using auxiliary structures when
submitting semaphore signal and wait operations, similar to what is done
with the keyed mutex extensions.
The latter is more flexible and consistent with the keyed mutex usage, but
the former is a much simpler API.

Since Vulkan tends to favor flexibility and consistency over simplicity, a
new structure specifying D3D12 fence acquire and release values is added to
the flink:vkQueueSubmit function.
