Safe Haskell	Safe-Inferred
Language	Haskell2010

Vulkan.Extensions.VK_KHR_external_memory_win32

Description

Name

VK_KHR_external_memory_win32 - device extension

VK_KHR_external_memory_win32

Name String: VK_KHR_external_memory_win32

Extension Type

Device extension

Registered Extension Number

74

Revision

1

Ratification Status

Ratified

Extension and Version Dependencies

VK_KHR_external_memory

Contact

James Jones @cubanismo%0A*Here describe the issue or question you have about the VK_KHR_external_memory_win32 extension*

Other Extension Metadata

Last Modified Date: 2016-10-21

IP Status

No known IP claims.

Contributors

James Jones, NVIDIA
Jeff Juliano, NVIDIA
Carsten Rohde, NVIDIA

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 Windows handles from Vulkan memory objects and to import Vulkan memory objects from Windows handles exported from other Vulkan memory objects or from similar resources in other APIs.

New Commands

getMemoryWin32HandleKHR

getMemoryWin32HandlePropertiesKHR

New Structures

MemoryGetWin32HandleInfoKHR

MemoryWin32HandlePropertiesKHR
Extending MemoryAllocateInfo:
- ExportMemoryWin32HandleInfoKHR
- ImportMemoryWin32HandleInfoKHR

New Enum Constants

KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME

Issues

1) Do applications need to call CloseHandle() on the values returned from getMemoryWin32HandleKHR when handleType is EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?

RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.

2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?

RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.

3) How should the valid size and memory type for windows memory handles created outside of Vulkan be specified?

RESOLVED: The valid memory types are queried directly from the external handle. The size is determined by the associated image or buffer memory requirements for external handle types that require dedicated allocations, and by the size specified when creating the object from which the handle was exported for other external handle types.

Version History

Revision 1, 2016-10-21 (James Jones)
- Initial revision

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

getMemoryWin32HandleKHR :: forall io. MonadIO io => Device -> MemoryGetWin32HandleInfoKHR -> io HANDLE
getMemoryWin32HandlePropertiesKHR :: forall io. MonadIO io => Device -> ExternalMemoryHandleTypeFlagBits -> HANDLE -> io MemoryWin32HandlePropertiesKHR
data ImportMemoryWin32HandleInfoKHR = ImportMemoryWin32HandleInfoKHR {
- handleType :: ExternalMemoryHandleTypeFlagBits
- handle :: HANDLE
- name :: LPCWSTR
}
data ExportMemoryWin32HandleInfoKHR = ExportMemoryWin32HandleInfoKHR {
- attributes :: Ptr SECURITY_ATTRIBUTES
- dwAccess :: DWORD
- name :: LPCWSTR
}
data MemoryWin32HandlePropertiesKHR = MemoryWin32HandlePropertiesKHR {
- memoryTypeBits :: Word32
}
data MemoryGetWin32HandleInfoKHR = MemoryGetWin32HandleInfoKHR {
- memory :: DeviceMemory
- handleType :: ExternalMemoryHandleTypeFlagBits
}
type KHR_EXTERNAL_MEMORY_WIN32_SPEC_VERSION = 1
pattern KHR_EXTERNAL_MEMORY_WIN32_SPEC_VERSION :: forall a. Integral a => a
type KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME = "VK_KHR_external_memory_win32"
pattern KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
type LPCWSTR = Ptr CWchar
type HANDLE = Ptr ()
type DWORD = Word32
data SECURITY_ATTRIBUTES

Documentation

getMemoryWin32HandleKHR Source #

Arguments

:: forall io. MonadIO io
=> Device	`device` is the logical device that created the device memory being exported. `device` must be a valid `Device` handle
-> MemoryGetWin32HandleInfoKHR	`pGetWin32HandleInfo` is a pointer to a `MemoryGetWin32HandleInfoKHR` structure containing parameters of the export operation. `pGetWin32HandleInfo` must be a valid pointer to a valid `MemoryGetWin32HandleInfoKHR` structure
-> io HANDLE

vkGetMemoryWin32HandleKHR - Get a Windows HANDLE for a memory object

Description

For handle types defined as NT handles, the handles returned by getMemoryWin32HandleKHR are owned by the application and hold a reference to their payload. To avoid leaking resources, the application must release ownership of them using the CloseHandle system call when they are no longer needed.

Note

Non-NT handle types do not add a reference to their associated payload. If the original object owning the payload is destroyed, all resources and handles sharing that payload will become invalid.

Return Codes

Success

SUCCESS

Failure

Description

Importing memory object payloads from Windows handles does not transfer ownership of the handle to the Vulkan implementation. For handle types defined as NT handles, the application must release handle ownership using the CloseHandle system call when the handle is no longer needed. For handle types defined as NT handles, the imported memory object holds a reference to its payload.

Note

Non-NT handle import operations do not add a reference to their associated payload. If the original object owning the payload is destroyed, all resources and handles sharing that payload will become invalid.

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 DeviceMemory object.

Valid Usage

If handleType is not 0, it must be supported for import, as reported by ExternalImageFormatProperties or ExternalBufferProperties

The memory from which handle was exported, or the memory named by name must have been created on the same underlying physical device as device
If handleType is not 0, it must be defined as an NT handle or a global share handle
If handleType is not EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, name must be NULL
If handleType is not 0 and handle is NULL, name must name a valid memory resource of the type specified by handleType
If handleType is not 0 and name is NULL, handle must be a valid handle of the type specified by handleType
If handle is not NULL, name must be NULL
If handle is not NULL, it must obey any requirements listed for handleType in external memory handle types compatibility
If name is not NULL, it must obey any requirements listed for handleType in external memory handle types compatibility

Valid Usage (Implicit)

sType must be STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR

If handleType is not 0, handleType must be a valid ExternalMemoryHandleTypeFlagBits value

Description

If ExportMemoryAllocateInfo is not included in the same pNext chain, this structure is ignored.

If ExportMemoryAllocateInfo is included in the pNext chain of MemoryAllocateInfo with a Windows handleType, but either ExportMemoryWin32HandleInfoKHR is not included in the pNext chain, or it is included but pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights used depend on the handle type.

For handles of the following types:

EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT

The implementation must ensure the access rights allow read and write access to the memory.

1: https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage

If ExportMemoryAllocateInfo::handleTypes does not include EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, a ExportMemoryWin32HandleInfoKHR structure must not be included in the pNext chain of MemoryAllocateInfo

Valid Usage (Implicit)

sType must be STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR

If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

Description

The properties of the handle returned depend on the value of handleType. See ExternalMemoryHandleTypeFlagBits for a description of the properties of the defined external memory handle types.

Valid Usage

handleType must have been included in ExportMemoryAllocateInfo::handleTypes when memory was created

If handleType is defined as an NT handle, getMemoryWin32HandleKHR must be called no more than once for each valid unique combination of memory and handleType
handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

sType must be STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR

pNext must be NULL
memory must be a valid DeviceMemory handle
handleType must be a valid ExternalMemoryHandleTypeFlagBits value

Storable ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods sizeOf :: ImportMemoryWin32HandleInfoKHR -> Int # alignment :: ImportMemoryWin32HandleInfoKHR -> Int # peekElemOff :: Ptr ImportMemoryWin32HandleInfoKHR -> Int -> IO ImportMemoryWin32HandleInfoKHR # pokeElemOff :: Ptr ImportMemoryWin32HandleInfoKHR -> Int -> ImportMemoryWin32HandleInfoKHR -> IO () # peekByteOff :: Ptr b -> Int -> IO ImportMemoryWin32HandleInfoKHR # pokeByteOff :: Ptr b -> Int -> ImportMemoryWin32HandleInfoKHR -> IO () # peek :: Ptr ImportMemoryWin32HandleInfoKHR -> IO ImportMemoryWin32HandleInfoKHR # poke :: Ptr ImportMemoryWin32HandleInfoKHR -> ImportMemoryWin32HandleInfoKHR -> IO () #
Show ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods showsPrec :: Int -> ImportMemoryWin32HandleInfoKHR -> ShowS # show :: ImportMemoryWin32HandleInfoKHR -> String # showList :: [ImportMemoryWin32HandleInfoKHR] -> ShowS #
Eq ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods (==) :: ImportMemoryWin32HandleInfoKHR -> ImportMemoryWin32HandleInfoKHR -> Bool # (/=) :: ImportMemoryWin32HandleInfoKHR -> ImportMemoryWin32HandleInfoKHR -> Bool #
FromCStruct ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods peekCStruct :: Ptr ImportMemoryWin32HandleInfoKHR -> IO ImportMemoryWin32HandleInfoKHR Source #
ToCStruct ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods withCStruct :: ImportMemoryWin32HandleInfoKHR -> (Ptr ImportMemoryWin32HandleInfoKHR -> IO b) -> IO b Source # pokeCStruct :: Ptr ImportMemoryWin32HandleInfoKHR -> ImportMemoryWin32HandleInfoKHR -> IO b -> IO b Source # withZeroCStruct :: (Ptr ImportMemoryWin32HandleInfoKHR -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ImportMemoryWin32HandleInfoKHR -> IO b -> IO b Source # cStructSize :: Int Source # cStructAlignment :: Int Source #
Zero ImportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods zero :: ImportMemoryWin32HandleInfoKHR Source #

Storable ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods sizeOf :: ExportMemoryWin32HandleInfoKHR -> Int # alignment :: ExportMemoryWin32HandleInfoKHR -> Int # peekElemOff :: Ptr ExportMemoryWin32HandleInfoKHR -> Int -> IO ExportMemoryWin32HandleInfoKHR # pokeElemOff :: Ptr ExportMemoryWin32HandleInfoKHR -> Int -> ExportMemoryWin32HandleInfoKHR -> IO () # peekByteOff :: Ptr b -> Int -> IO ExportMemoryWin32HandleInfoKHR # pokeByteOff :: Ptr b -> Int -> ExportMemoryWin32HandleInfoKHR -> IO () # peek :: Ptr ExportMemoryWin32HandleInfoKHR -> IO ExportMemoryWin32HandleInfoKHR # poke :: Ptr ExportMemoryWin32HandleInfoKHR -> ExportMemoryWin32HandleInfoKHR -> IO () #
Show ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods showsPrec :: Int -> ExportMemoryWin32HandleInfoKHR -> ShowS # show :: ExportMemoryWin32HandleInfoKHR -> String # showList :: [ExportMemoryWin32HandleInfoKHR] -> ShowS #
Eq ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods (==) :: ExportMemoryWin32HandleInfoKHR -> ExportMemoryWin32HandleInfoKHR -> Bool # (/=) :: ExportMemoryWin32HandleInfoKHR -> ExportMemoryWin32HandleInfoKHR -> Bool #
FromCStruct ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods peekCStruct :: Ptr ExportMemoryWin32HandleInfoKHR -> IO ExportMemoryWin32HandleInfoKHR Source #
ToCStruct ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods withCStruct :: ExportMemoryWin32HandleInfoKHR -> (Ptr ExportMemoryWin32HandleInfoKHR -> IO b) -> IO b Source # pokeCStruct :: Ptr ExportMemoryWin32HandleInfoKHR -> ExportMemoryWin32HandleInfoKHR -> IO b -> IO b Source # withZeroCStruct :: (Ptr ExportMemoryWin32HandleInfoKHR -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr ExportMemoryWin32HandleInfoKHR -> IO b -> IO b Source # cStructSize :: Int Source # cStructAlignment :: Int Source #
Zero ExportMemoryWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods zero :: ExportMemoryWin32HandleInfoKHR Source #

Storable MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods sizeOf :: MemoryWin32HandlePropertiesKHR -> Int # alignment :: MemoryWin32HandlePropertiesKHR -> Int # peekElemOff :: Ptr MemoryWin32HandlePropertiesKHR -> Int -> IO MemoryWin32HandlePropertiesKHR # pokeElemOff :: Ptr MemoryWin32HandlePropertiesKHR -> Int -> MemoryWin32HandlePropertiesKHR -> IO () # peekByteOff :: Ptr b -> Int -> IO MemoryWin32HandlePropertiesKHR # pokeByteOff :: Ptr b -> Int -> MemoryWin32HandlePropertiesKHR -> IO () # peek :: Ptr MemoryWin32HandlePropertiesKHR -> IO MemoryWin32HandlePropertiesKHR # poke :: Ptr MemoryWin32HandlePropertiesKHR -> MemoryWin32HandlePropertiesKHR -> IO () #
Show MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods showsPrec :: Int -> MemoryWin32HandlePropertiesKHR -> ShowS # show :: MemoryWin32HandlePropertiesKHR -> String # showList :: [MemoryWin32HandlePropertiesKHR] -> ShowS #
Eq MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods (==) :: MemoryWin32HandlePropertiesKHR -> MemoryWin32HandlePropertiesKHR -> Bool # (/=) :: MemoryWin32HandlePropertiesKHR -> MemoryWin32HandlePropertiesKHR -> Bool #
FromCStruct MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods peekCStruct :: Ptr MemoryWin32HandlePropertiesKHR -> IO MemoryWin32HandlePropertiesKHR Source #
ToCStruct MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods withCStruct :: MemoryWin32HandlePropertiesKHR -> (Ptr MemoryWin32HandlePropertiesKHR -> IO b) -> IO b Source # pokeCStruct :: Ptr MemoryWin32HandlePropertiesKHR -> MemoryWin32HandlePropertiesKHR -> IO b -> IO b Source # withZeroCStruct :: (Ptr MemoryWin32HandlePropertiesKHR -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr MemoryWin32HandlePropertiesKHR -> IO b -> IO b Source # cStructSize :: Int Source # cStructAlignment :: Int Source #
Zero MemoryWin32HandlePropertiesKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods zero :: MemoryWin32HandlePropertiesKHR Source #

Storable MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods sizeOf :: MemoryGetWin32HandleInfoKHR -> Int # alignment :: MemoryGetWin32HandleInfoKHR -> Int # peekElemOff :: Ptr MemoryGetWin32HandleInfoKHR -> Int -> IO MemoryGetWin32HandleInfoKHR # pokeElemOff :: Ptr MemoryGetWin32HandleInfoKHR -> Int -> MemoryGetWin32HandleInfoKHR -> IO () # peekByteOff :: Ptr b -> Int -> IO MemoryGetWin32HandleInfoKHR # pokeByteOff :: Ptr b -> Int -> MemoryGetWin32HandleInfoKHR -> IO () # peek :: Ptr MemoryGetWin32HandleInfoKHR -> IO MemoryGetWin32HandleInfoKHR # poke :: Ptr MemoryGetWin32HandleInfoKHR -> MemoryGetWin32HandleInfoKHR -> IO () #
Show MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods showsPrec :: Int -> MemoryGetWin32HandleInfoKHR -> ShowS # show :: MemoryGetWin32HandleInfoKHR -> String # showList :: [MemoryGetWin32HandleInfoKHR] -> ShowS #
Eq MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods (==) :: MemoryGetWin32HandleInfoKHR -> MemoryGetWin32HandleInfoKHR -> Bool # (/=) :: MemoryGetWin32HandleInfoKHR -> MemoryGetWin32HandleInfoKHR -> Bool #
FromCStruct MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods peekCStruct :: Ptr MemoryGetWin32HandleInfoKHR -> IO MemoryGetWin32HandleInfoKHR Source #
ToCStruct MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods withCStruct :: MemoryGetWin32HandleInfoKHR -> (Ptr MemoryGetWin32HandleInfoKHR -> IO b) -> IO b Source # pokeCStruct :: Ptr MemoryGetWin32HandleInfoKHR -> MemoryGetWin32HandleInfoKHR -> IO b -> IO b Source # withZeroCStruct :: (Ptr MemoryGetWin32HandleInfoKHR -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr MemoryGetWin32HandleInfoKHR -> IO b -> IO b Source # cStructSize :: Int Source # cStructAlignment :: Int Source #
Zero MemoryGetWin32HandleInfoKHR Source #
Instance details Defined in Vulkan.Extensions.VK_KHR_external_memory_win32 Methods zero :: MemoryGetWin32HandleInfoKHR Source #

Name

VK_KHR_external_memory_win32

Other Extension Metadata

Description

New Commands

New Structures

New Enum Constants

Issues

Version History

See Also

Document Notes

Documentation

Description

Return Codes

See Also

Return Codes

See Also

Description

Valid Usage

Valid Usage (Implicit)

See Also

Instances

Description

Valid Usage

Valid Usage (Implicit)

See Also

Instances

Valid Usage (Implicit)

See Also

Instances

Description

Valid Usage

Valid Usage (Implicit)

See Also

Instances

:: forall io. MonadIO io
=> Device	`device` is the logical device that will be importing `handle`. `device` must be a valid `Device` handle
-> ExternalMemoryHandleTypeFlagBits	`handleType` is a `ExternalMemoryHandleTypeFlagBits` value specifying the type of the handle `handle`. `handleType` must not be one of the handle types defined as opaque `handleType` must be a valid `ExternalMemoryHandleTypeFlagBits` value
-> HANDLE	`handle` is the handle which will be imported. `handle` must point to a valid Windows memory handle
-> io MemoryWin32HandlePropertiesKHR

ImportMemoryWin32HandleInfoKHR
Fields handleType :: ExternalMemoryHandleTypeFlagBits `handleType` is a `ExternalMemoryHandleTypeFlagBits` value specifying the type of `handle` or `name`. handle :: HANDLE `handle` is `NULL` or the external handle to import. name :: LPCWSTR `name` is `NULL` or a null-terminated UTF-16 string naming the payload to import.

ExportMemoryWin32HandleInfoKHR
Fields attributes :: Ptr SECURITY_ATTRIBUTES `pAttributes` is a pointer to a Windows `SECURITY_ATTRIBUTES` structure specifying security attributes of the handle. dwAccess :: DWORD `dwAccess` is a `DWORD` specifying access rights of the handle. name :: LPCWSTR `name` is a null-terminated UTF-16 string to associate with the payload referenced by NT handles exported from the created memory.

MemoryWin32HandlePropertiesKHR
Fields memoryTypeBits :: Word32 `memoryTypeBits` is a bitmask containing one bit set for every memory type which the specified windows handle can be imported as.

MemoryGetWin32HandleInfoKHR
Fields memory :: DeviceMemory `memory` is the memory object from which the handle will be exported. handleType :: ExternalMemoryHandleTypeFlagBits `handleType` is a `ExternalMemoryHandleTypeFlagBits` value specifying the type of handle requested.