// Copyright (c) 2016-2019 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::meta/VK_KHR_external_memory_win32.txt[]

*Last Modified Date*::
    2016-10-21
*IP Status*::
    No known IP claims.
*Contributors*::
  - James Jones, NVIDIA
  - Jeff Juliano, NVIDIA
  - Carsten Rohde, NVIDIA

An application may wish to reference device memory in multiple Vulkan
logical devices or instances, in multiple processes, and/or in multiple
APIs.
This extension enables an application to export Windows handles from Vulkan
memory objects and to import Vulkan memory objects from Windows handles
exported from other Vulkan memory objects or from similar resources in other
APIs.

=== New Object Types

None.

=== New Enum Constants

  * ename:VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR
  * ename:VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR

=== New Enums

None.

=== New Structs

  * slink:VkImportMemoryWin32HandleInfoKHR
  * slink:VkExportMemoryWin32HandleInfoKHR
  * slink:VkMemoryWin32HandlePropertiesKHR
  * slink:VkMemoryGetWin32HandleInfoKHR

=== New Functions

  * flink:vkGetMemoryWin32HandleKHR
  * flink:vkGetMemoryWin32HandlePropertiesKHR

=== Issues

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

ifdef::editing-notes[]
[NOTE]
.editing-note
====
(Jon) This issue refers to a token from
`<<VK_KHR_external_semaphore_win32>>`, but there's no dependency or
interaction with that extension defined above.
====
endif::editing-notes[]

*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 memory object will not destroy the handle or the handle's
reference to the underlying memory 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) How should the valid size and memory type for windows memory handles
created outside of Vulkan be specified?

*RESOLVED*: The valid memory types are queried directly from the external
handle.
The size is determined by the associated image or buffer memory requirements
for external handle types that require dedicated allocations, and by the
size specified when creating the object from which the handle was exported
for other external handle types.