{-# language CPP #-} -- | = Name -- -- VK_KHR_external_memory - device extension -- -- == VK_KHR_external_memory -- -- [__Name String__] -- @VK_KHR_external_memory@ -- -- [__Extension Type__] -- Device extension -- -- [__Registered Extension Number__] -- 73 -- -- [__Revision__] -- 1 -- -- [__Extension and Version Dependencies__] -- -- - Requires Vulkan 1.0 -- -- - Requires @VK_KHR_external_memory_capabilities@ -- -- [__Deprecation state__] -- -- - /Promoted/ to -- <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#versions-1.1-promotions Vulkan 1.1> -- -- [__Contact__] -- -- - James Jones -- <https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_KHR_external_memory:%20&body=@cubanismo%20 > -- -- == Other Extension Metadata -- -- [__Last Modified Date__] -- 2016-10-20 -- -- [__IP Status__] -- No known IP claims. -- -- [__Interactions and External Dependencies__] -- -- - Interacts with @VK_KHR_dedicated_allocation@. -- -- - Interacts with @VK_NV_dedicated_allocation@. -- -- - Promoted to Vulkan 1.1 Core -- -- [__Contributors__] -- -- - Jason Ekstrand, Intel -- -- - Ian Elliot, Google -- -- - Jesse Hall, Google -- -- - Tobias Hector, Imagination Technologies -- -- - James Jones, NVIDIA -- -- - Jeff Juliano, NVIDIA -- -- - Matthew Netsch, Qualcomm Technologies, Inc. -- -- - Daniel Rakos, AMD -- -- - Carsten Rohde, NVIDIA -- -- - Ray Smith, ARM -- -- - Chad Versace, Google -- -- == Description -- -- An application may wish to reference device memory in multiple Vulkan -- logical devices or instances, in multiple processes, and\/or in multiple -- APIs. 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 logical device that created -- them. -- -- == Promotion to Vulkan 1.1 -- -- All functionality in this extension is included in core Vulkan 1.1, with -- the KHR suffix omitted. The original type, enum and command names are -- still available as aliases of the core functionality. -- -- == New Structures -- -- - Extending 'Vulkan.Core10.Buffer.BufferCreateInfo': -- -- - 'ExternalMemoryBufferCreateInfoKHR' -- -- - Extending 'Vulkan.Core10.Image.ImageCreateInfo': -- -- - 'ExternalMemoryImageCreateInfoKHR' -- -- - Extending 'Vulkan.Core10.Memory.MemoryAllocateInfo': -- -- - 'ExportMemoryAllocateInfoKHR' -- -- == New Enum Constants -- -- - 'KHR_EXTERNAL_MEMORY_EXTENSION_NAME' -- -- - 'KHR_EXTERNAL_MEMORY_SPEC_VERSION' -- -- - 'Vulkan.Core10.APIConstants.QUEUE_FAMILY_EXTERNAL_KHR' -- -- - Extending 'Vulkan.Core10.Enums.Result.Result': -- -- - 'ERROR_INVALID_EXTERNAL_HANDLE_KHR' -- -- - Extending 'Vulkan.Core10.Enums.StructureType.StructureType': -- -- - 'STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR' -- -- - 'STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR' -- -- - 'STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR' -- -- == Issues -- -- 1) How do applications correlate two physical devices across process or -- Vulkan instance boundaries? -- -- __RESOLVED__: New device ID fields have been introduced by -- @VK_KHR_external_memory_capabilities@. These fields, combined with the -- existing -- 'Vulkan.Core10.DeviceInitialization.PhysicalDeviceProperties'::@driverVersion@ -- field can be used to identify compatible devices across processes, -- drivers, and APIs. -- 'Vulkan.Core10.DeviceInitialization.PhysicalDeviceProperties'::@pipelineCacheUUID@ -- is not sufficient for this purpose because despite its description in -- the specification, it need only identify a unique pipeline cache format -- in practice. Multiple devices may be able to use the same pipeline cache -- data, and hence it would be desirable for all of them to have the same -- pipeline cache UUID. However, only the same concrete physical device can -- be used when sharing memory, so an actual unique device ID was -- introduced. Further, the pipeline cache UUID was specific to Vulkan, but -- correlation with other, non-extensible APIs is required to enable -- interoperation with those APIs. -- -- 2) If memory objects are shared between processes and APIs, is this -- considered aliasing according to the rules outlined in the -- <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#resources-memory-aliasing Memory Aliasing> -- section? -- -- __RESOLVED__: Yes. Applications must take care to obey all restrictions -- imposed on aliased resources when using memory across multiple Vulkan -- instances or other APIs. -- -- 3) Are new image layouts or metadata required to specify image layouts -- and layout transitions compatible with non-Vulkan APIs, or with other -- instances of the same Vulkan driver? -- -- __RESOLVED__: Separate instances of the same Vulkan driver running on -- the same GPU should have identical internal layout semantics, so -- applications have the tools they need to ensure views of images are -- consistent between the two instances. Other APIs will fall into two -- categories: Those that are Vulkan- compatible, and those that are -- Vulkan-incompatible. Vulkan-incompatible APIs will require the image to -- be in the GENERAL layout whenever they are accessing them. -- -- Note this does not attempt to address cross-device transitions, nor -- transitions to engines on the same device which are not visible within -- the Vulkan API. Both of these are beyond the scope of this extension. -- -- 4) Is a new barrier flag or operation of some type needed to prepare -- external memory for handoff to another Vulkan instance or API and\/or -- receive it from another instance or API? -- -- __RESOLVED__: Yes. Some implementations need to perform additional cache -- management when transitioning memory between address spaces, and other -- APIs, instances, or processes may operate in a separate address space. -- Options for defining this transition include: -- -- - A new structure that can be added to the @pNext@ list in -- 'Vulkan.Core10.OtherTypes.MemoryBarrier', -- 'Vulkan.Core10.OtherTypes.BufferMemoryBarrier', and -- 'Vulkan.Core10.OtherTypes.ImageMemoryBarrier'. -- -- - A new bit in 'Vulkan.Core10.Enums.AccessFlagBits.AccessFlags' that -- can be set to indicate an “external” access. -- -- - A new bit in -- 'Vulkan.Core10.Enums.DependencyFlagBits.DependencyFlags' -- -- - A new special queue family that represents an “external” queue. -- -- A new structure has the advantage that the type of external transition -- can be described in as much detail as necessary. However, there is not -- currently a known need for anything beyond differentiating between -- external and internal accesses, so this is likely an over-engineered -- solution. The access flag bit has the advantage that it can be applied -- at buffer, image, or global granularity, and semantically it maps pretty -- well to the operation being described. Additionally, the API already -- includes 'Vulkan.Core10.Enums.AccessFlagBits.ACCESS_MEMORY_READ_BIT' and -- 'Vulkan.Core10.Enums.AccessFlagBits.ACCESS_MEMORY_WRITE_BIT' which -- appear to be intended for this purpose. However, there is no obvious -- pipeline stage that would correspond to an external access, and -- therefore no clear way to use -- 'Vulkan.Core10.Enums.AccessFlagBits.ACCESS_MEMORY_READ_BIT' or -- 'Vulkan.Core10.Enums.AccessFlagBits.ACCESS_MEMORY_WRITE_BIT'. -- 'Vulkan.Core10.Enums.DependencyFlagBits.DependencyFlags' and -- 'Vulkan.Core10.Enums.PipelineStageFlagBits.PipelineStageFlags' operate -- at command granularity rather than image or buffer granularity, which -- would make an entire pipeline barrier an internal→external or -- external→internal barrier. This may not be a problem in practice, but -- seems like the wrong scope. Another downside of -- 'Vulkan.Core10.Enums.DependencyFlagBits.DependencyFlags' is that it -- lacks inherent directionality: There are not @src@ and @dst@ variants of -- it in the barrier or dependency description semantics, so two bits might -- need to be added to describe both internal→external and -- external→internal transitions. Transitioning a resource to a special -- queue family corresponds well with the operation of transitioning to a -- separate Vulkan instance, in that both operations ideally include -- scheduling a barrier on both sides of the transition: Both the releasing -- and the acquiring queue or process. Using a special queue family -- requires adding an additional reserved queue family index. Re-using -- 'Vulkan.Core10.APIConstants.QUEUE_FAMILY_IGNORED' would have left it -- unclear how to transition a concurrent usage resource from one process -- to another, since the semantics would have likely been equivalent to the -- currently-ignored transition of -- 'Vulkan.Core10.APIConstants.QUEUE_FAMILY_IGNORED' → 'Vulkan.Core10.APIConstants.QUEUE_FAMILY_IGNORED'. -- Fortunately, creating a new reserved queue family index is not invasive. -- -- Based on the above analysis, the approach of transitioning to a special -- “external” queue family was chosen. -- -- 5) Do internal driver memory arrangements and\/or other internal driver -- image properties need to be exported and imported when sharing images -- across processes or APIs. -- -- __RESOLVED__: Some vendors claim this is necessary on their -- implementations, but it was determined that the security risks of -- allowing opaque meta data to be passed from applications to the driver -- were too high. Therefore, implementations which require metadata will -- need to associate it with the objects represented by the external -- handles, and rely on the dedicated allocation mechanism to associate the -- exported and imported memory objects with a single image or buffer. -- -- 6) Most prior interoperation and cross-process sharing APIs have been -- based on image-level sharing. Should Vulkan sharing be based on -- memory-object sharing or image sharing? -- -- __RESOLVED__: These extensions have assumed memory-level sharing is the -- correct granularity. Vulkan is a lower-level API than most prior APIs, -- and as such attempts to closely align with to the underlying primitives -- of the hardware and system-level drivers it abstracts. In general, the -- resource that holds the backing store for both images and buffers of -- various types is memory. Images and buffers are merely metadata -- containing brief descriptions of the layout of bits within that memory. -- -- Because memory object-based sharing is aligned with the overall Vulkan -- API design, it exposes the full power of Vulkan on external objects. -- External memory can be used as backing for sparse images, for example, -- whereas such usage would be awkward at best with a sharing mechanism -- based on higher-level primitives such as images. Further, aligning the -- mechanism with the API in this way provides some hope of trivial -- compatibility with future API enhancements. If new objects backed by -- memory objects are added to the API, they too can be used across -- processes with minimal additions to the base external memory APIs. -- -- Earlier APIs implemented interop at a higher level, and this -- necessitated entirely separate sharing APIs for images and buffers. To -- co-exist and interoperate with those APIs, the Vulkan external sharing -- mechanism must accommodate their model. However, if it can be agreed -- that memory-based sharing is the more desirable and forward-looking -- design, legacy interoperation considerations can be considered another -- reason to favor memory-based sharing: While native and legacy driver -- primitives that may be used to implement sharing may not be as low-level -- as the API here suggests, raw memory is still the least common -- denominator among the types. Image-based sharing can be cleanly derived -- from a set of base memory- object sharing APIs with minimal effort, -- whereas image-based sharing does not generalize well to buffer or -- raw-memory sharing. Therefore, following the general Vulkan design -- principle of minimalism, it is better to expose even interopability with -- image-based native and external primitives via the memory sharing API, -- and place sufficient limits on their usage to ensure they can be used -- only as backing for equivalent Vulkan images. This provides a consistent -- API for applications regardless of which platform or external API they -- are targeting, which makes development of multi-API and multi-platform -- applications simpler. -- -- 7) Should Vulkan define a common external handle type and provide Vulkan -- functions to facilitate cross-process sharing of such handles rather -- than relying on native handles to define the external objects? -- -- __RESOLVED__: No. Cross-process sharing of resources is best left to -- native platforms. There are myriad security and extensibility issues -- with such a mechanism, and attempting to re-solve all those issues -- within Vulkan does not align with Vulkan’s purpose as a graphics API. If -- desired, such a mechanism could be built as a layer or helper library on -- top of the opaque native handle defined in this family of extensions. -- -- 8) Must implementations provide additional guarantees about state -- implicitly included in memory objects for those memory objects that may -- be exported? -- -- __RESOLVED__: Implementations must ensure that sharing memory objects -- does not transfer any information between the exporting and importing -- instances and APIs other than that required to share the data contained -- in the memory objects explicitly shared. As specific examples, data from -- previously freed memory objects that used the same underlying physical -- memory, and data from memory obects using adjacent physical memory must -- not be visible to applications importing an exported memory object. -- -- 9) Must implementations validate external handles the application -- provides as input to memory import operations? -- -- __RESOLVED__: Implementations must return an error to the application if -- the provided memory handle cannot be used to complete the requested -- import operation. However, implementations need not validate handles are -- of the exact type specified by the application. -- -- == Version History -- -- - Revision 1, 2016-10-20 (James Jones) -- -- - Initial version -- -- = See Also -- -- 'Vulkan.Core10.APIConstants.QUEUE_FAMILY_EXTERNAL_KHR', -- 'ExportMemoryAllocateInfoKHR', 'ExternalMemoryBufferCreateInfoKHR', -- 'ExternalMemoryImageCreateInfoKHR' -- -- = Document Notes -- -- For more information, see the -- <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_external_memory Vulkan Specification> -- -- This page is a generated document. Fixes and changes should be made to -- the generator scripts, not directly. module Vulkan.Extensions.VK_KHR_external_memory ( pattern STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR , pattern STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR , pattern STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR , pattern ERROR_INVALID_EXTERNAL_HANDLE_KHR , pattern QUEUE_FAMILY_EXTERNAL_KHR , ExternalMemoryImageCreateInfoKHR , ExternalMemoryBufferCreateInfoKHR , ExportMemoryAllocateInfoKHR , KHR_EXTERNAL_MEMORY_SPEC_VERSION , pattern KHR_EXTERNAL_MEMORY_SPEC_VERSION , KHR_EXTERNAL_MEMORY_EXTENSION_NAME , pattern KHR_EXTERNAL_MEMORY_EXTENSION_NAME ) where import Data.String (IsString) import Vulkan.Core11.Promoted_From_VK_KHR_external_memory (ExportMemoryAllocateInfo) import Vulkan.Core11.Promoted_From_VK_KHR_external_memory (ExternalMemoryBufferCreateInfo) import Vulkan.Core11.Promoted_From_VK_KHR_external_memory (ExternalMemoryImageCreateInfo) import Vulkan.Core10.Enums.Result (Result(ERROR_INVALID_EXTERNAL_HANDLE)) import Vulkan.Core10.APIConstants (pattern QUEUE_FAMILY_EXTERNAL) import Vulkan.Core10.Enums.StructureType (StructureType(STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO)) import Vulkan.Core10.Enums.StructureType (StructureType(STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO)) import Vulkan.Core10.Enums.StructureType (StructureType(STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO)) -- No documentation found for TopLevel "VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR" pattern $bSTRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR :: StructureType $mSTRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR :: forall r. StructureType -> (Void# -> r) -> (Void# -> r) -> r STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR = STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO -- No documentation found for TopLevel "VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR" pattern $bSTRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR :: StructureType $mSTRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR :: forall r. StructureType -> (Void# -> r) -> (Void# -> r) -> r STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR = STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO -- No documentation found for TopLevel "VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR" pattern $bSTRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR :: StructureType $mSTRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR :: forall r. StructureType -> (Void# -> r) -> (Void# -> r) -> r STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR = STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO -- No documentation found for TopLevel "VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR" pattern $bERROR_INVALID_EXTERNAL_HANDLE_KHR :: Result $mERROR_INVALID_EXTERNAL_HANDLE_KHR :: forall r. Result -> (Void# -> r) -> (Void# -> r) -> r ERROR_INVALID_EXTERNAL_HANDLE_KHR = ERROR_INVALID_EXTERNAL_HANDLE -- No documentation found for TopLevel "VK_QUEUE_FAMILY_EXTERNAL_KHR" pattern $bQUEUE_FAMILY_EXTERNAL_KHR :: Word32 $mQUEUE_FAMILY_EXTERNAL_KHR :: forall r. Word32 -> (Void# -> r) -> (Void# -> r) -> r QUEUE_FAMILY_EXTERNAL_KHR = QUEUE_FAMILY_EXTERNAL -- No documentation found for TopLevel "VkExternalMemoryImageCreateInfoKHR" type ExternalMemoryImageCreateInfoKHR = ExternalMemoryImageCreateInfo -- No documentation found for TopLevel "VkExternalMemoryBufferCreateInfoKHR" type ExternalMemoryBufferCreateInfoKHR = ExternalMemoryBufferCreateInfo -- No documentation found for TopLevel "VkExportMemoryAllocateInfoKHR" type ExportMemoryAllocateInfoKHR = ExportMemoryAllocateInfo type KHR_EXTERNAL_MEMORY_SPEC_VERSION = 1 -- No documentation found for TopLevel "VK_KHR_EXTERNAL_MEMORY_SPEC_VERSION" pattern KHR_EXTERNAL_MEMORY_SPEC_VERSION :: forall a . Integral a => a pattern $bKHR_EXTERNAL_MEMORY_SPEC_VERSION :: a $mKHR_EXTERNAL_MEMORY_SPEC_VERSION :: forall r a. Integral a => a -> (Void# -> r) -> (Void# -> r) -> r KHR_EXTERNAL_MEMORY_SPEC_VERSION = 1 type KHR_EXTERNAL_MEMORY_EXTENSION_NAME = "VK_KHR_external_memory" -- No documentation found for TopLevel "VK_KHR_EXTERNAL_MEMORY_EXTENSION_NAME" pattern KHR_EXTERNAL_MEMORY_EXTENSION_NAME :: forall a . (Eq a, IsString a) => a pattern $bKHR_EXTERNAL_MEMORY_EXTENSION_NAME :: a $mKHR_EXTERNAL_MEMORY_EXTENSION_NAME :: forall r a. (Eq a, IsString a) => a -> (Void# -> r) -> (Void# -> r) -> r KHR_EXTERNAL_MEMORY_EXTENSION_NAME = "VK_KHR_external_memory"