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