Vulkan.Extensions.VK_KHR_external_fence_win32

Name

VK_KHR_external_fence_win32 - device extension

VK_KHR_external_fence_win32

Name String

VK_KHR_external_fence_win32

Extension Type

Device extension

Registered Extension Number

115

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_external_fence

Contact

• Jesse Hall https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_KHR_external_fence_win32:%20&body=@critsec%20

Other Extension Metadata

Last Modified Date

2017-05-08

IP Status

No known IP claims.

Contributors

• Jesse Hall, Google
• James Jones, NVIDIA
• Jeff Juliano, NVIDIA
• Cass Everitt, Oculus
• Contributors to VK_KHR_external_semaphore_win32

Description

An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from Windows handles.

New Commands

• getFenceWin32HandleKHR

• importFenceWin32HandleKHR

New Structures

• FenceGetWin32HandleInfoKHR

• ImportFenceWin32HandleInfoKHR

• Extending FenceCreateInfo:

  • ExportFenceWin32HandleInfoKHR

New Enum Constants

• KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME

• KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR
  • STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR
  • STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR

Issues

This extension borrows concepts, semantics, and language from VK_KHR_external_semaphore_win32. That extension’s issues apply equally to this extension.

1) Should D3D12 fence handle types be supported, like they are for semaphores?

RESOLVED: No. Doing so would require extending the fence signal and wait operations to provide values to signal / wait for, like D3D12FenceSubmitInfoKHR does. A D3D12 fence can be signaled by importing it into a Semaphore instead of a Fence, and applications can check status or wait on the D3D12 fence using non-Vulkan APIs. The convenience of being able to do these operations on Fence objects does not justify the extra API complexity.

Version History

• Revision 1, 2017-05-08 (Jesse Hall)

  • Initial revision

See Also

ExportFenceWin32HandleInfoKHR, FenceGetWin32HandleInfoKHR, ImportFenceWin32HandleInfoKHR, getFenceWin32HandleKHR, importFenceWin32HandleKHR

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.

Documentation

getFenceWin32HandleKHR

Arguments

:: forall io. MonadIO io

=> Device

device is the logical device that created the fence being exported.

device must be a valid Device handle

-> FenceGetWin32HandleInfoKHR

pGetWin32HandleInfo is a pointer to a FenceGetWin32HandleInfoKHR structure containing parameters of the export operation.

pGetWin32HandleInfo must be a valid pointer to a valid FenceGetWin32HandleInfoKHR structure

-> io HANDLE

vkGetFenceWin32HandleKHR - Get a Windows HANDLE for a fence

Description

For handle types defined as NT handles, the handles returned by getFenceWin32HandleKHR are owned by the application. To avoid leaking resources, the application must release ownership of them using the CloseHandle system call when they are no longer needed.

Exporting a Windows handle from a fence may have side effects depending on the transference of the specified handle type, as described in Importing Fence Payloads.

Return Codes

Success

• SUCCESS

Failure

• ERROR_TOO_MANY_OBJECTS
• ERROR_OUT_OF_HOST_MEMORY

See Also

Device, FenceGetWin32HandleInfoKHR

importFenceWin32HandleKHR

Arguments

:: forall io. MonadIO io

=> Device

device is the logical device that created the fence.

device must be a valid Device handle

-> ImportFenceWin32HandleInfoKHR

pImportFenceWin32HandleInfo is a pointer to a ImportFenceWin32HandleInfoKHR structure specifying the fence and import parameters.

pImportFenceWin32HandleInfo must be a valid pointer to a valid ImportFenceWin32HandleInfoKHR structure

-> io ()

vkImportFenceWin32HandleKHR - Import a fence from a Windows HANDLE

Description

Importing a fence payload 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 ownership using the CloseHandle system call when the handle is no longer needed.

Applications can import the same fence payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_EXTERNAL_HANDLE

See Also

Device, ImportFenceWin32HandleInfoKHR

data ImportFenceWin32HandleInfoKHR

VkImportFenceWin32HandleInfoKHR - (None)

Description

The handle types supported by handleType are:

Handle Type	Transference	Permanence Supported
EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT	Reference	Temporary,Permanent
EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT	Reference	Temporary,Permanent

Handle Types Supported by ImportFenceWin32HandleInfoKHR

Valid Usage

• handleType must be a value included in the Handle Types Supported by table

• If handleType is not EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, name must be NULL
• If handle is NULL, name must name a valid synchronization primitive of the type specified by handleType
• If 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 fence handle types compatibility
• If name is not NULL, it must obey any requirements listed for handleType in external fence handle types compatibility

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR

• pNext must be NULL
• fence must be a valid Fence handle
• flags must be a valid combination of FenceImportFlagBits values

Host Synchronization

• Host access to fence must be externally synchronized

See Also

ExternalFenceHandleTypeFlagBits, Fence, FenceImportFlags, StructureType, importFenceWin32HandleKHR

Constructors

ImportFenceWin32HandleInfoKHR

Fields

• fence :: Fence

  fence is the fence into which the state will be imported.

• flags :: FenceImportFlags

  flags is a bitmask of FenceImportFlagBits specifying additional parameters for the fence payload import operation.

• handleType :: ExternalFenceHandleTypeFlagBits

  handleType is a ExternalFenceHandleTypeFlagBits value specifying the type of handle.

• 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 underlying synchronization primitive to import.

Instances

Eq ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

(==) :: ImportFenceWin32HandleInfoKHR -> ImportFenceWin32HandleInfoKHR -> Bool

(/=) :: ImportFenceWin32HandleInfoKHR -> ImportFenceWin32HandleInfoKHR -> Bool

Show ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

showsPrec :: Int -> ImportFenceWin32HandleInfoKHR -> ShowS

show :: ImportFenceWin32HandleInfoKHR -> String

showList :: [ImportFenceWin32HandleInfoKHR] -> ShowS

Storable ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

sizeOf :: ImportFenceWin32HandleInfoKHR -> Int

alignment :: ImportFenceWin32HandleInfoKHR -> Int

peekElemOff :: Ptr ImportFenceWin32HandleInfoKHR -> Int -> IO ImportFenceWin32HandleInfoKHR

pokeElemOff :: Ptr ImportFenceWin32HandleInfoKHR -> Int -> ImportFenceWin32HandleInfoKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO ImportFenceWin32HandleInfoKHR

pokeByteOff :: Ptr b -> Int -> ImportFenceWin32HandleInfoKHR -> IO ()

peek :: Ptr ImportFenceWin32HandleInfoKHR -> IO ImportFenceWin32HandleInfoKHR

poke :: Ptr ImportFenceWin32HandleInfoKHR -> ImportFenceWin32HandleInfoKHR -> IO ()

FromCStruct ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

peekCStruct :: Ptr ImportFenceWin32HandleInfoKHR -> IO ImportFenceWin32HandleInfoKHR

ToCStruct ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

withCStruct :: ImportFenceWin32HandleInfoKHR -> (Ptr ImportFenceWin32HandleInfoKHR -> IO b) -> IO b

pokeCStruct :: Ptr ImportFenceWin32HandleInfoKHR -> ImportFenceWin32HandleInfoKHR -> IO b -> IO b

withZeroCStruct :: (Ptr ImportFenceWin32HandleInfoKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImportFenceWin32HandleInfoKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

zero :: ImportFenceWin32HandleInfoKHR

data ExportFenceWin32HandleInfoKHR

VkExportFenceWin32HandleInfoKHR - Structure specifying additional attributes of Windows handles exported from a fence

Description

If ExportFenceCreateInfo is not inluded in the same pNext chain, this structure is ignored.

If ExportFenceCreateInfo is included in the pNext chain of FenceCreateInfo with a Windows handleType, but either ExportFenceWin32HandleInfoKHR is not included in the pNext chain, or if it is 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 will be

DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE

for handles of the following types:

EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT

1

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

Valid Usage

• If ExportFenceCreateInfo::handleTypes does not include EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, a ExportFenceWin32HandleInfoKHR structure must not be included in the pNext chain of FenceCreateInfo

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR

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

See Also

StructureType

Constructors

ExportFenceWin32HandleInfoKHR

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 underlying synchronization primitive referenced by NT handles exported from the created fence.

Instances

Eq ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

(==) :: ExportFenceWin32HandleInfoKHR -> ExportFenceWin32HandleInfoKHR -> Bool

(/=) :: ExportFenceWin32HandleInfoKHR -> ExportFenceWin32HandleInfoKHR -> Bool

Show ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

showsPrec :: Int -> ExportFenceWin32HandleInfoKHR -> ShowS

show :: ExportFenceWin32HandleInfoKHR -> String

showList :: [ExportFenceWin32HandleInfoKHR] -> ShowS

Storable ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

sizeOf :: ExportFenceWin32HandleInfoKHR -> Int

alignment :: ExportFenceWin32HandleInfoKHR -> Int

peekElemOff :: Ptr ExportFenceWin32HandleInfoKHR -> Int -> IO ExportFenceWin32HandleInfoKHR

pokeElemOff :: Ptr ExportFenceWin32HandleInfoKHR -> Int -> ExportFenceWin32HandleInfoKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO ExportFenceWin32HandleInfoKHR

pokeByteOff :: Ptr b -> Int -> ExportFenceWin32HandleInfoKHR -> IO ()

peek :: Ptr ExportFenceWin32HandleInfoKHR -> IO ExportFenceWin32HandleInfoKHR

poke :: Ptr ExportFenceWin32HandleInfoKHR -> ExportFenceWin32HandleInfoKHR -> IO ()

FromCStruct ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

peekCStruct :: Ptr ExportFenceWin32HandleInfoKHR -> IO ExportFenceWin32HandleInfoKHR

ToCStruct ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

withCStruct :: ExportFenceWin32HandleInfoKHR -> (Ptr ExportFenceWin32HandleInfoKHR -> IO b) -> IO b

pokeCStruct :: Ptr ExportFenceWin32HandleInfoKHR -> ExportFenceWin32HandleInfoKHR -> IO b -> IO b

withZeroCStruct :: (Ptr ExportFenceWin32HandleInfoKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr ExportFenceWin32HandleInfoKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ExportFenceWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

zero :: ExportFenceWin32HandleInfoKHR

data FenceGetWin32HandleInfoKHR

VkFenceGetWin32HandleInfoKHR - Structure describing a Win32 handle fence export operation

Description

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

Valid Usage

• handleType must have been included in ExportFenceCreateInfo::handleTypes when the fence’s current payload was created

• If handleType is defined as an NT handle, getFenceWin32HandleKHR must be called no more than once for each valid unique combination of fence and handleType
• fence must not currently have its payload replaced by an imported payload as described below in Importing Fence Payloads unless that imported payload’s handle type was included in ExternalFenceProperties::exportFromImportedHandleTypes for handleType
• If handleType refers to a handle type with copy payload transference semantics, fence must be signaled, or have an associated fence signal operation pending execution
• handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR

• pNext must be NULL
• fence must be a valid Fence handle
• handleType must be a valid ExternalFenceHandleTypeFlagBits value

See Also

ExternalFenceHandleTypeFlagBits, Fence, StructureType, getFenceWin32HandleKHR

Constructors

FenceGetWin32HandleInfoKHR

Fields

• fence :: Fence

  fence is the fence from which state will be exported.

• handleType :: ExternalFenceHandleTypeFlagBits

  handleType is a ExternalFenceHandleTypeFlagBits value specifying the type of handle requested.

Instances

Eq FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

(==) :: FenceGetWin32HandleInfoKHR -> FenceGetWin32HandleInfoKHR -> Bool

(/=) :: FenceGetWin32HandleInfoKHR -> FenceGetWin32HandleInfoKHR -> Bool

Show FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

showsPrec :: Int -> FenceGetWin32HandleInfoKHR -> ShowS

show :: FenceGetWin32HandleInfoKHR -> String

showList :: [FenceGetWin32HandleInfoKHR] -> ShowS

Storable FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

sizeOf :: FenceGetWin32HandleInfoKHR -> Int

alignment :: FenceGetWin32HandleInfoKHR -> Int

peekElemOff :: Ptr FenceGetWin32HandleInfoKHR -> Int -> IO FenceGetWin32HandleInfoKHR

pokeElemOff :: Ptr FenceGetWin32HandleInfoKHR -> Int -> FenceGetWin32HandleInfoKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO FenceGetWin32HandleInfoKHR

pokeByteOff :: Ptr b -> Int -> FenceGetWin32HandleInfoKHR -> IO ()

peek :: Ptr FenceGetWin32HandleInfoKHR -> IO FenceGetWin32HandleInfoKHR

poke :: Ptr FenceGetWin32HandleInfoKHR -> FenceGetWin32HandleInfoKHR -> IO ()

FromCStruct FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

peekCStruct :: Ptr FenceGetWin32HandleInfoKHR -> IO FenceGetWin32HandleInfoKHR

ToCStruct FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

withCStruct :: FenceGetWin32HandleInfoKHR -> (Ptr FenceGetWin32HandleInfoKHR -> IO b) -> IO b

pokeCStruct :: Ptr FenceGetWin32HandleInfoKHR -> FenceGetWin32HandleInfoKHR -> IO b -> IO b

withZeroCStruct :: (Ptr FenceGetWin32HandleInfoKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr FenceGetWin32HandleInfoKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero FenceGetWin32HandleInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_fence_win32

Methods

zero :: FenceGetWin32HandleInfoKHR

type KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION = 1

pattern KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION :: forall a. Integral a => a

type KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME = "VK_KHR_external_fence_win32"

pattern KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a

type HANDLE = Ptr ()

type DWORD = Word32

type LPCWSTR = Ptr CWchar

data SECURITY_ATTRIBUTES