-
Notifications
You must be signed in to change notification settings - Fork 474
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
59dc3a3
commit 9d16d7e
Showing
9 changed files
with
401 additions
and
12 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 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 |
159 changes: 159 additions & 0 deletions
159
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,159 @@ | ||
| // Copyright 2024 The Khronos Group Inc. | ||
| // | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| === Metal External Memory | ||
|
|
||
| [open,refpage='MTLResource_id',desc='Metal MTLResource type reference',type='basetypes'] | ||
| -- | ||
| The type `id<MTLResource>` is defined in Apple's Metal framework as the | ||
| parent type of `id<MTLBuffer>` and `id<MTLTexture>`. We use `id<MTLResource>` | ||
| to simplify usage and provide a single common type for both resources. To | ||
| remove an unnecessary compile time dependency, an incomplete type definition | ||
| of basetype:MTLResource_id is provided in the Vulkan headers: | ||
|
|
||
| include::{generated}/api/basetypes/MTLResource_id.adoc[] | ||
| -- | ||
|
|
||
|
|
||
| [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 or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_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. | ||
|
|
||
| The lifespan of the returned handle object is the same as the associated `VkDeviceMemory` object. | ||
| The app must: retain the handle object if it intends to use it beyond that lifespan. | ||
|
|
||
| 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:handleType must: have been included in | ||
| slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory | ||
| was created | ||
| * pname:handleType it must: be | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_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 MTLResource_id | ||
| * pname:handleType it must: be | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT or | ||
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_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.