1// Copyright 2021-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= VK_EXT_metal_objects 6:toc: left 7:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ 8:sectnums: 9 10This document details API design ideas for the `VK_EXT_metal_objects` extension, 11which, in a Vulkan implementation that is layered on top of Metal on Apple device 12platforms, provides the ability to import and export the underlying Metal objects 13associated with specific Vulkan objects. 14 15 16== Problem Statement 17 18In a Vulkan implementation that is layered on top of Metal on Apple device platforms, 19many Vulkan objects have a corresponding Metal equivalent that provides the underlying 20functionality. When integrating a Vulkan app onto such a platform, it is often useful 21for the app to be able to interact directly with these Metal objects: 22 23 . Pass Metal texture and buffer resources between Vulkan and platform functionality 24 such as camera, video, AR, or inter-process frameworks. 25 . Create hybrid apps that combine and mingle Vulkan and Metal operations, 26 by sharing, in addition to Metal texture and buffer resources, also Metal device, 27 command queues, and synchronization operations. 28 29 30== Solution Space 31 32While the first use case listed above might be addressed via extensions built by adding 33Metal platform variations to the `VK_KHR_external_memory` family of extensions, the 34second use case requires a different approach. Rather than create a fragmented approach 35to managing access to Metal objects, this extension proposes to provide a single unified 36interface to all Metal objects providing functionality to the layered Vulkan implementation. 37Furthermore, this extension has been designed to be easily extendable, to import and export 38new Metal objects that might be introduced in the future. 39 40The intent is that this extension will be advertised and supported only on 41implementations that are layered on top of Metal on Apple device platforms. 42 43 44== Proposal 45 46=== Exporting Metal Objects 47 48To export underlying Metal objects from Vulkan objects, this extension adds one new 49Vulkan command: 50 51[source,c] 52---- 53VKAPI_ATTR void VKAPI_CALL vkExportMetalObjectsEXT( 54 VkDevice device, 55 VkExportMetalObjectsInfoEXT* pMetalObjectsInfo); 56---- 57 58The `pNext` chain of the `VkExportMetalObjectsInfoEXT` in the `pMetalObjectsInfo` 59parameter can contain a variety of specialized structures, each targeted to identify 60a particular Vulkan object and a pointer through which the underlying Metal object 61can be exported, as identified in the following list. The use of `pNext` structures 62allows this extension to be flexibly extended in the future to permit access to 63additional Metal objects, through the future addition of new export object structures. 64 65[source,c] 66---- 67typedef struct VkExportMetalObjectsInfoEXT { 68 VkStructureType sType; 69 const void* pNext; 70} VkExportMetalObjectsInfoEXT; 71 72typedef struct VkExportMetalDeviceInfoEXT { 73 VkStructureType sType; 74 const void* pNext; 75 MTLDevice_id mtlDevice; 76} VkExportMetalDeviceInfoEXT; 77 78typedef struct VkExportMetalCommandQueueInfoEXT { 79 VkStructureType sType; 80 const void* pNext; 81 VkQueue queue; 82 MTLCommandQueue_id mtlCommandQueue; 83} VkExportMetalCommandQueueInfoEXT; 84 85typedef struct VkExportMetalBufferInfoEXT { 86 VkStructureType sType; 87 const void* pNext; 88 VkDeviceMemory memory; 89 MTLBuffer_id mtlBuffer; 90} VkExportMetalBufferInfoEXT; 91 92typedef struct VkExportMetalTextureInfoEXT { 93 VkStructureType sType; 94 const void* pNext; 95 VkImage image; 96 VkImageView imageView; 97 VkBufferView bufferView; 98 VkImageAspectFlagBits plane; 99 MTLTexture_id mtlTexture; 100} VkExportMetalTextureInfoEXT; 101 102typedef struct VkExportMetalIOSurfaceInfoEXT { 103 VkStructureType sType; 104 const void* pNext; 105 VkImage image; 106 IOSurfaceRef ioSurface; 107} VkExportMetalIOSurfaceInfoEXT; 108 109typedef struct VkExportMetalSharedEventInfoEXT { 110 VkStructureType sType; 111 const void* pNext; 112 VkSemaphore semaphore; 113 VkEvent event; 114 MTLSharedEvent_id mtlSharedEvent; 115} VkExportMetalSharedEventInfoEXT; 116---- 117 118To export Metal objects from Vulkan objects, the app must first indicate the 119intention to do so during the creation of the Vulkan object, by including a 120`VkExportMetalObjectCreateInfoEXT` structure in the `pNext` chain of the 121`VkInstanceCreateInfo`, `VkMemoryAllocateInfo`, `VkImageCreateInfo`, 122`VkImageViewCreateInfo`, `VkBufferViewCreateInfo`, `VkSemaphoreCreateInfo`, 123or `VkEventCreateInfo`, in the corresponding Vulkan object creation command. 124 125[source,c] 126---- 127typedef struct VkExportMetalObjectCreateInfoEXT { 128 VkStructureType sType; 129 const void* pNext; 130 VkExportMetalObjectTypeFlagBitsEXT exportObjectType; 131} VkExportMetalObjectCreateInfoEXT; 132 133typedef enum VkExportMetalObjectTypeFlagBitsEXT { 134 VK_EXPORT_METAL_OBJECT_TYPE_METAL_DEVICE_BIT_EXT = 0x00000001, 135 VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT = 0x00000002, 136 VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT = 0x00000004, 137 VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT = 0x00000008, 138 VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT = 0x00000010, 139 VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT = 0x00000020, 140 VK_EXPORT_METAL_OBJECT_TYPE_FLAG_BITS_MAX_ENUM_EXT = 0x7FFFFFFF 141} VkExportMetalObjectTypeFlagBitsEXT; 142typedef VkFlags VkExportMetalObjectTypeFlagsEXT; 143---- 144 145=== Importing Metal Objects 146 147A `VkDeviceMemory` object can be created on an existing `MTLBuffer` object, by including 148the `MTLBuffer` object in a `VkImportMetalBufferInfoEXT` structure in the `pNext` chain 149of the `VkMemoryAllocateInfo` structure in the `vkAllocateMemory` command. 150 151A `VkImage` object can be created on an existing `IOSurface` object, or one or 152more existing Metal `MTLTexture` objects, by including those Metal objects in 153`VkImportMetalIOSurfaceInfoEXT` or `VkImportMetalTextureInfoEXT` structures in the 154`pNext` chain of the `VkImageCreateInfo` structure in the `vkCreateImage` command. 155 156A `VkSemaphore` or `VkEvent` object can be created on an existing `MTLSharedEvent` 157object, by including the `MTLSharedEvent` object in a `VkImportMetalSharedEventInfoEXT` 158structure in the `pNext` chain of the `VkSemaphoreCreateInfo` or `VkEventCreateInfo` 159structure in a `vkCreateSemaphore` or `vkCreateEvent` command, respectively 160 161[source,c] 162---- 163typedef struct VkImportMetalBufferInfoEXT { 164 VkStructureType sType; 165 const void* pNext; 166 MTLBuffer_id mtlBuffer; 167} VkImportMetalBufferInfoEXT; 168 169typedef struct VkImportMetalTextureInfoEXT { 170 VkStructureType sType; 171 const void* pNext; 172 VkImageAspectFlags aspectMask; 173 MTLTexture_id mtlTexture; 174} VkImportMetalTextureInfoEXT; 175 176typedef struct VkImportMetalIOSurfaceInfoEXT { 177 VkStructureType sType; 178 const void* pNext; 179 IOSurfaceRef ioSurface; 180} VkImportMetalIOSurfaceInfoEXT; 181 182typedef struct VkImportMetalSharedEventInfoEXT { 183 VkStructureType sType; 184 const void* pNext; 185 MTLSharedEvent_id mtlSharedEvent; 186} VkImportMetalSharedEventInfoEXT; 187---- 188 189 190== Issues 191 192=== RESOLVED: Should this extension be built by adding Metal platform variations to the `VK_KHR_external_memory` family of extensions? 193 194No. While the `VK_KHR_external_memory` family of extensions is suitable for resource 195objects such as images and buffers, the intent of the `VK_EXT_metal_objects` is to 196provide consistent access to a wide variety of Metal objects, including, but not 197limited to resource objects. 198 199=== RESOLVED: Should this extension be split into two, one for resources and one for other objects? 200 201No. Given the expectation that this extension will be limited to layered implementations 202on top of Metal running only on Apple platforms, the preference was for a single simple 203extension that served the needs of all expected use cases for apps on those platforms. 204Furthermore, the existence of this `VK_EXT_metal_objects` extension does not prevent 205additional resource-only extensions compatible with `VK_KHR_external_memory` from being 206introduced for those specific use cases, and with the expectation that any resulting 207functionality overlap will not cause any issues. 208 209=== RESOLVED: Should the app be required to indicate its intention to export Metal objects when the corresponding Vulkan object is created? 210 211Yes. To improve implementation flexibility and integrity, requiring the app to indicate 212the intention to export provides the implementation with the flexibility to optimize 213internally if it knows certain Metal objects will or will not be required to be available. 214 215=== RESOLVED: Should a `MTLBuffer` be imported and exported through a `VkBuffer` or a `VkDeviceMemory`? 216 217While `MTLBuffer` spans functionality covered by both `VkBuffer` and `VkDeviceMemory`, it 218was felt that `MTLBuffer` maps closest to `VkDeviceMemory`, with a `VkBuffer` essentially 219being a wrapper object around a segment of that `VkDeviceMemory/MTLBuffer`. 220