-
Notifications
You must be signed in to change notification settings - Fork 476
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add VK_EXT_external_memory_metal (#2414)
* Add VK_EXT_external_memory_metal * Add missing VUIDs for VK_EXT_external_memory_metal * Add MTLHeap as a possible handle to export/import * Reword lifespan segment, merge VUID and fix typos * VK_EXT_external_memory_metal fix build due to rebase issue * VK_EXT_external_memory_metal has no features * VK_EXT_external_memory_metal add missing const to param * VK_EXT_external_memory_metal fix parameter name * VK_EXT_external_memory_metal address MTLHeap and VUID feedback * VK_EXT_external_memory_metal typo fixes and allocationSize VUID * VK_EXT_external_memory_metal fix "impor" typo
- Loading branch information
1 parent
840c7b8
commit 25ec2b7
Showing
8 changed files
with
402 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| // Copyright 2024 The Khronos Group Inc. | ||
| // | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| include::{generated}/meta/{refprefix}VK_EXT_external_memory_metal.adoc[] | ||
|
|
||
| === Other Extension Metadata | ||
|
|
||
| *Last Modified Date*:: | ||
| 2024-07-18 | ||
| *IP Status*:: | ||
| No known IP claims. | ||
| *Contributors*:: | ||
| - Aitor Camacho Larrondo, LunarG Inc. | ||
|
|
||
| === Description | ||
|
|
||
| An application may wish to reference device memory in multiple Vulkan device instances, in multiple processes, and/or in Metal API. | ||
| This extension enables an application to export and import Metal handles from Vulkan memory objects such that the underlying | ||
| resources can be referenced outside the scope of the Vulkan device instance that created them. | ||
|
|
||
| include::{generated}/interfaces/VK_EXT_external_memory_metal.adoc[] | ||
|
|
||
| === Version History | ||
|
|
||
| * Revision 1, 2024-07-18 (Aitor Camacho Larrondo) | ||
| ** Initial revision |
153 changes: 153 additions & 0 deletions
153
chapters/VK_EXT_external_memory_metal/device_memory.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| // Copyright 2024 The Khronos Group Inc. | ||
| // | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| === Metal External Memory | ||
|
|
||
| [open,refpage='VkImportMemoryMetalHandleInfoEXT',desc='Import Metal memory created on the same physical device',type='structs'] | ||
| -- | ||
| To import memory from a Metal handle, add a | ||
| slink:VkImportMemoryMetalHandleInfoEXT structure to the pname:pNext chain of | ||
| the slink:VkMemoryAllocateInfo structure. | ||
|
|
||
| The sname:VkImportMemoryMetalHandleInfoEXT structure is defined as: | ||
|
|
||
| include::{generated}/api/structs/VkImportMemoryMetalHandleInfoEXT.adoc[] | ||
|
|
||
| * pname:sType is a elink:VkStructureType value identifying this structure. | ||
| * pname:pNext is `NULL` or a pointer to a structure extending this | ||
| structure. | ||
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value | ||
| specifying the type of pname:handle or pname:name. | ||
| * pname:handle is `NULL` or the external handle to import. | ||
|
|
||
| Importing memory object payloads from Metal handles shares the | ||
| ownership of the handle to the Vulkan implementation. | ||
|
|
||
| Applications can: import the same payload into multiple instances of Vulkan, | ||
| into the same instance from which it was exported, and multiple times into a | ||
| given Vulkan instance. | ||
| In all cases, each import operation must: create a distinct | ||
| sname:VkDeviceMemory object. | ||
|
|
||
| .Valid Usage | ||
| **** | ||
| * If pname:handleType is not `0`, it must: be supported for import, as | ||
| reported by slink:VkExternalImageFormatProperties or | ||
| slink:VkExternalBufferProperties | ||
| * The memory from which pname:handle was exported must: have been created | ||
| on the same underlying physical device as pname:device | ||
| * If pname:handleType is not `0`, it must: be | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT, | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXT | ||
| * If pname:handleType is not `0` , pname:handle must: be a valid non-NULL | ||
| handle of the type specified by pname:handleType | ||
| * pname:handle must: obey any requirements listed for pname:handleType in | ||
| <<external-memory-handle-types-compatibility,external memory handle | ||
| types compatibility>> | ||
| **** | ||
|
|
||
| include::{generated}/validity/structs/VkImportMemoryMetalHandleInfoEXT.adoc[] | ||
| -- | ||
|
|
||
| [open,refpage='vkGetMemoryMetalHandleEXT',desc='Get a Metal handle for a memory object',type='protos'] | ||
| -- | ||
| To export a Metal handle representing the payload of a Vulkan device | ||
| memory object, call: | ||
|
|
||
| include::{generated}/api/protos/vkGetMemoryMetalHandleEXT.adoc[] | ||
|
|
||
| * pname:device is the logical device that created the device memory being | ||
| exported. | ||
| * pname:pGetMetalHandleInfo is a pointer to a | ||
| slink:VkMemoryGetMetalHandleInfoEXT structure containing parameters of | ||
| the export operation. | ||
| * pname:pHandle will return the Metal handle representing the payload of | ||
| the device memory object. | ||
|
|
||
| Unless the app retains the handle object returned by the call, the lifespan will be the same as | ||
| the associated `VkDeviceMemory`. | ||
|
|
||
| include::{generated}/validity/protos/vkGetMemoryMetalHandleEXT.adoc[] | ||
| -- | ||
|
|
||
| [open,refpage='VkMemoryGetMetalHandleInfoEXT',desc='Structure describing a Metal handle memory export operation',type='structs'] | ||
| -- | ||
| The sname:VkMemoryGetMetalHandleInfoEXT structure is defined as: | ||
|
|
||
| include::{generated}/api/structs/VkMemoryGetMetalHandleInfoEXT.adoc[] | ||
|
|
||
| * pname:sType is a elink:VkStructureType value identifying this structure. | ||
| * pname:pNext is `NULL` or a pointer to a structure extending this | ||
| structure. | ||
| * pname:memory is the memory object from which the handle will be | ||
| exported. | ||
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value | ||
| specifying the type of handle requested. | ||
|
|
||
| The properties of the handle returned depend on the value of | ||
| pname:handleType. | ||
| See elink:VkExternalMemoryHandleTypeFlagBits for a description of the | ||
| properties of the defined external memory handle types. | ||
|
|
||
| .Valid Usage | ||
| **** | ||
| * pname:memory must: have been created with a valid | ||
| slink:VkExportMemoryAllocateInfo | ||
| * pname:handleType must: have been included in | ||
| slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory | ||
| was created | ||
| * pname:handleType must: be | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT, | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXT | ||
| **** | ||
|
|
||
| include::{generated}/validity/structs/VkMemoryGetMetalHandleInfoEXT.adoc[] | ||
| -- | ||
|
|
||
| [open,refpage='vkGetMemoryMetalHandlePropertiesEXT',desc='Get Properties of External Memory Metal Handles',type='protos'] | ||
| -- | ||
| Metal memory handles compatible with Vulkan may: also be created by | ||
| non-Vulkan APIs using methods beyond the scope of this specification. | ||
| To determine the correct parameters to use when importing such handles, | ||
| call: | ||
|
|
||
| include::{generated}/api/protos/vkGetMemoryMetalHandlePropertiesEXT.adoc[] | ||
|
|
||
| * pname:device is the logical device that will be importing pname:handle. | ||
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value | ||
| specifying the type of the handle pname:handle. | ||
| * pname:handle is the handle which will be imported. | ||
| * pname:pMemoryMetalHandleProperties is a pointer to a | ||
| slink:VkMemoryMetalHandlePropertiesEXT structure in which properties of | ||
| pname:handle are returned. | ||
|
|
||
| .Valid Usage | ||
| **** | ||
| * pname:handle must: point to a valid id<MTLBuffer>, id<MTLTexture> or | ||
| id<MTLDevice> | ||
| * pname:handleType must: be | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT, | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXT | ||
| **** | ||
|
|
||
| include::{generated}/validity/protos/vkGetMemoryMetalHandlePropertiesEXT.adoc[] | ||
| -- | ||
|
|
||
| [open,refpage='VkMemoryMetalHandlePropertiesEXT',desc='Properties of External Memory Metal Handles',type='structs'] | ||
| -- | ||
| The sname:VkMemoryMetalHandlePropertiesEXT structure returned is defined as: | ||
|
|
||
| include::{generated}/api/structs/VkMemoryMetalHandlePropertiesEXT.adoc[] | ||
|
|
||
| * pname:sType is a elink:VkStructureType value identifying this structure. | ||
| * pname:pNext is `NULL` or a pointer to a structure extending this | ||
| structure. | ||
| * pname:memoryTypeBits is a bitmask containing one bit set for every | ||
| memory type which the specified Metal handle can: be imported as. | ||
|
|
||
| include::{generated}/validity/structs/VkMemoryMetalHandlePropertiesEXT.adoc[] | ||
| -- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.