// Copyright 2016-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_external_memory_capabilities.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2016-10-17
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - Interacts with `<<VK_KHR_dedicated_allocation>>`.
  - Interacts with `<<VK_NV_dedicated_allocation>>`.
  - Promoted to Vulkan 1.1 Core
*Contributors*::
  - Ian Elliot, Google
  - Jesse Hall, Google
  - James Jones, NVIDIA

=== Description

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 provides a set of capability queries and handle definitions
that allow an application to determine what types of "`external`" memory
handles an implementation supports for a given set of use cases.

=== Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.

include::{generated}/interfaces/VK_KHR_external_memory_capabilities.txt[]

=== Issues

1) Why do so many external memory capabilities need to be queried on a
per-memory-handle-type basis?

*PROPOSED RESOLUTION*: This is because some handle types are based on
OS-native objects that have far more limited capabilities than the very
generic Vulkan memory objects.
Not all memory handle types can name memory objects that support 3D images,
for example.
Some handle types cannot even support the deferred image and memory binding
behavior of Vulkan and require specifying the image when allocating or
importing the memory object.

2) Do the slink:VkExternalImageFormatPropertiesKHR and
slink:VkExternalBufferPropertiesKHR structs need to include a list of memory
type bits that support the given handle type?

*PROPOSED RESOLUTION*: No.
The memory types that do not support the handle types will simply be
filtered out of the results returned by flink:vkGetImageMemoryRequirements
and flink:vkGetBufferMemoryRequirements when a set of handle types was
specified at image or buffer creation time.

3) Should the non-opaque handle types be moved to their own extension?

*PROPOSED RESOLUTION*: Perhaps.
However, defining the handle type bits does very little and does not require
any platform-specific types on its own, and it is easier to maintain the
bitfield values in a single extension for now.
Presumably more handle types could be added by separate extensions though,
and it would be midly weird to have some platform-specific ones defined in
the core spec and some in extensions

4) Do we need a code:D3D11_TILEPOOL type?

*PROPOSED RESOLUTION*: No.
This is technically possible, but the synchronization is awkward.
D3D11 surfaces must be synchronized using shared mutexes, and these
synchronization primitives are shared by the entire memory object, so D3D11
shared allocations divided among multiple buffer and image bindings may be
difficult to synchronize.

5) Should the Windows 7-compatible handle types be named "`KMT`" handles or
"`GLOBAL_SHARE`" handles?

*PROPOSED RESOLUTION*: KMT, simply because it is more concise.

6) How do applications identify compatible devices and drivers across
instance, process, and API boundaries when sharing memory?

*PROPOSED RESOLUTION*: New device properties are exposed that allow
applications to correctly correlate devices and drivers.
A device and driver UUID that must both match to ensure sharing
compatibility between two Vulkan instances, or a Vulkan instance and an
extensible external API are added.
To allow correlating with Direct3D devices, a device LUID is added that
corresponds to a DXGI adapter LUID.
A driver ID is not needed for Direct3D because mismatched driver component
versions are not currently supported on the Windows OS.
Should support for such configurations be introduced at the OS level,
further Vulkan extensions would be needed to correlate userspace component
builds.

=== Version History

 * Revision 1, 2016-10-17 (James Jones)
   - Initial version
