• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright (c) 2016-2020 NVIDIA Corporation
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_NV_win32_keyed_mutex.adoc[]
6
7=== Other Extension Metadata
8
9*Last Modified Date*::
10    2016-08-19
11*IP Status*::
12    No known IP claims.
13*Contributors*::
14  - James Jones, NVIDIA
15  - Carsten Rohde, NVIDIA
16
17=== Description
18
19Applications that wish to import Direct3D 11 memory objects into the Vulkan
20API may wish to use the native keyed mutex mechanism to synchronize access
21to the memory between Vulkan and Direct3D.
22This extension provides a way for an application to access the keyed mutex
23associated with an imported Vulkan memory object when submitting command
24buffers to a queue.
25
26include::{generated}/interfaces/VK_NV_win32_keyed_mutex.adoc[]
27
28=== Examples
29
30[source,c++]
31----------------------------------------
32    //
33    // Import a memory object from Direct3D 11, and synchronize
34    // access to it in Vulkan using keyed mutex objects.
35    //
36
37    extern VkPhysicalDevice physicalDevice;
38    extern VkDevice device;
39    extern HANDLE sharedNtHandle;
40
41    static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
42    static const VkExternalMemoryHandleTypeFlagsNV handleType =
43        VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV;
44
45    VkPhysicalDeviceMemoryProperties memoryProperties;
46    VkExternalImageFormatPropertiesNV properties;
47    VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
48    VkImageCreateInfo imageCreateInfo;
49    VkImage image;
50    VkMemoryRequirements imageMemoryRequirements;
51    uint32_t numMemoryTypes;
52    uint32_t memoryType;
53    VkImportMemoryWin32HandleInfoNV importMemoryInfo;
54    VkMemoryAllocateInfo memoryAllocateInfo;
55    VkDeviceMemory mem;
56    VkResult result;
57
58    // Figure out how many memory types the device supports
59    vkGetPhysicalDeviceMemoryProperties(physicalDevice,
60                                        &memoryProperties);
61    numMemoryTypes = memoryProperties.memoryTypeCount;
62
63    // Check the external handle type capabilities for the chosen format
64    // Importable 2D image support with at least 1 mip level, 1 array
65    // layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
66    // texturing and color rendering is required.
67    result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
68        physicalDevice,
69        format,
70        VK_IMAGE_TYPE_2D,
71        VK_IMAGE_TILING_OPTIMAL,
72        VK_IMAGE_USAGE_SAMPLED_BIT |
73        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
74        0,
75        handleType,
76        &properties);
77
78    if ((result != VK_SUCCESS) ||
79        !(properties.externalMemoryFeatures &
80          VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV)) {
81        abort();
82    }
83
84    // Set up the external memory image creation info
85    memset(&externalMemoryImageCreateInfo,
86           0, sizeof(externalMemoryImageCreateInfo));
87    externalMemoryImageCreateInfo.sType =
88        VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
89    externalMemoryImageCreateInfo.handleTypes = handleType;
90    // Set up the  core image creation info
91    memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
92    imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
93    imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
94    imageCreateInfo.format = format;
95    imageCreateInfo.extent.width = 64;
96    imageCreateInfo.extent.height = 64;
97    imageCreateInfo.extent.depth = 1;
98    imageCreateInfo.mipLevels = 1;
99    imageCreateInfo.arrayLayers = 1;
100    imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
101    imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
102    imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
103        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
104    imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
105    imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
106
107    vkCreateImage(device, &imageCreateInfo, NULL, &image);
108    vkGetImageMemoryRequirements(device,
109                                 image,
110                                 &imageMemoryRequirements);
111
112    // For simplicity, just pick the first compatible memory type.
113    for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
114        if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
115            break;
116        }
117    }
118
119    // At least one memory type must be supported given the prior external
120    // handle capability check.
121    assert(memoryType < numMemoryTypes);
122
123    // Allocate the external memory object.
124    memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
125    exportMemoryAllocateInfo.sType =
126        VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
127    importMemoryInfo.handleTypes = handleType;
128    importMemoryInfo.handle = sharedNtHandle;
129
130    memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
131    memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
132    memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
133    memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
134    memoryAllocateInfo.memoryTypeIndex = memoryType;
135
136    vkAllocateMemory(device, &memoryAllocateInfo, NULL, &mem);
137
138    vkBindImageMemory(device, image, mem, 0);
139
140    ...
141
142    const uint64_t acquireKey = 1;
143    const uint32_t timeout = INFINITE;
144    const uint64_t releaseKey = 2;
145
146    VkWin32KeyedMutexAcquireReleaseInfoNV keyedMutex =
147        { VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV };
148    keyedMutex.acquireCount = 1;
149    keyedMutex.pAcquireSyncs = &mem;
150    keyedMutex.pAcquireKeys = &acquireKey;
151    keyedMutex.pAcquireTimeoutMilliseconds = &timeout;
152    keyedMutex.releaseCount = 1;
153    keyedMutex.pReleaseSyncs = &mem;
154    keyedMutex.pReleaseKeys = &releaseKey;
155
156    VkSubmitInfo submit_info = { VK_STRUCTURE_TYPE_SUBMIT_INFO, &keyedMutex };
157    submit_info.commandBufferCount = 1;
158    submit_info.pCommandBuffers = &cmd_buf;
159    vkQueueSubmit(queue, 1, &submit_info, VK_NULL_HANDLE);
160----------------------------------------
161
162=== Version History
163
164  * Revision 2, 2016-08-11 (James Jones)
165  ** Updated sample code based on the NV external memory extensions.
166  ** Renamed from NVX to NV extension.
167  ** Added Overview and Description sections.
168  ** Updated sample code to use the NV external memory extensions.
169
170  * Revision 1, 2016-06-14 (Carsten Rohde)
171  ** Initial draft.
172