Add VK_EXT_external_memory_metal #2414
+402
−18
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 non-Vulkan 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 | ||
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 it must: be | ||
|
There was a problem hiding this comment.
|
||
| 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 it must: be | ||
|
There was a problem hiding this comment.
|
||
| 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.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/non-Vulkan handles/Metal handles/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The text says "export", but the extension supports import too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let me know if the new wording works!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So close! "Import" is misspelled as "impor". Other than the typo, the text looks good.