vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_external_semaphore_win32

Description

Name

VK_KHR_external_semaphore_win32 - device extension

VK_KHR_external_semaphore_win32

Name String
VK_KHR_external_semaphore_win32
Extension Type
Device extension
Registered Extension Number
79
Revision
1
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_external_semaphore
Contact

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 using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from Windows handles.

New Commands

New Structures

New Enum Constants

Issues

1) Do applications need to call CloseHandle() on the values returned from getSemaphoreWin32HandleKHR when handleType is EXTERNAL_SEMAPHORE_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 semaphore object will not destroy the handle or the handle’s reference to the underlying semaphore 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) Should applications be allowed to specify additional object attributes for shared handles?

RESOLVED: Yes. Applications will be allowed to provide similar attributes to those they would to any other handle creation API.

4) How do applications communicate the desired fence values to use with D3D12_FENCE-based Vulkan semaphores?

RESOLVED: There are a couple of options. The values for the signaled and reset states could be communicated up front when creating the object and remain static for the life of the Vulkan semaphore, or they could be specified using auxiliary structures when submitting semaphore signal and wait operations, similar to what is done with the keyed mutex extensions. The latter is more flexible and consistent with the keyed mutex usage, but the former is a much simpler API.

Since Vulkan tends to favor flexibility and consistency over simplicity, a new structure specifying D3D12 fence acquire and release values is added to the queueSubmit function.

Version History

  • Revision 1, 2016-10-21 (James Jones)

    • Initial revision

See Also

D3D12FenceSubmitInfoKHR, ExportSemaphoreWin32HandleInfoKHR, ImportSemaphoreWin32HandleInfoKHR, SemaphoreGetWin32HandleInfoKHR, getSemaphoreWin32HandleKHR, importSemaphoreWin32HandleKHR

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

Documentation

getSemaphoreWin32HandleKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

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

device must be a valid Device handle

-> SemaphoreGetWin32HandleInfoKHR

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

pGetWin32HandleInfo must be a valid pointer to a valid SemaphoreGetWin32HandleInfoKHR structure

-> io HANDLE 

vkGetSemaphoreWin32HandleKHR - Get a Windows HANDLE for a semaphore

Description

For handle types defined as NT handles, the handles returned by getSemaphoreWin32HandleKHR 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 semaphore may have side effects depending on the transference of the specified handle type, as described in Importing Semaphore Payloads.

Return Codes

Success
Failure

See Also

VK_KHR_external_semaphore_win32, Device, SemaphoreGetWin32HandleInfoKHR

importSemaphoreWin32HandleKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the logical device that created the semaphore.

device must be a valid Device handle

-> ImportSemaphoreWin32HandleInfoKHR

pImportSemaphoreWin32HandleInfo is a pointer to a ImportSemaphoreWin32HandleInfoKHR structure specifying the semaphore and import parameters.

pImportSemaphoreWin32HandleInfo must be a valid pointer to a valid ImportSemaphoreWin32HandleInfoKHR structure

-> io () 

vkImportSemaphoreWin32HandleKHR - Import a semaphore from a Windows HANDLE

Description

Importing a semaphore 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 semaphore 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
Failure

See Also

VK_KHR_external_semaphore_win32, Device, ImportSemaphoreWin32HandleInfoKHR

data ImportSemaphoreWin32HandleInfoKHR Source #

VkImportSemaphoreWin32HandleInfoKHR - Structure specifying Windows handle to import to a semaphore

Description

The handle types supported by handleType are:

Handle Type Transference Permanence Supported
EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITReferenceTemporary,Permanent
EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITReferenceTemporary,Permanent
EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BITReferenceTemporary,Permanent

Handle Types Supported by ImportSemaphoreWin32HandleInfoKHR

Valid Usage

Valid Usage (Implicit)

Host Synchronization

  • Host access to semaphore must be externally synchronized

See Also

VK_KHR_external_semaphore_win32, ExternalSemaphoreHandleTypeFlagBits, Semaphore, SemaphoreImportFlags, StructureType, importSemaphoreWin32HandleKHR

Constructors

ImportSemaphoreWin32HandleInfoKHR 

Fields

Instances

Instances details
Storable ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Show ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Eq ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

FromCStruct ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

ToCStruct ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Zero ImportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

data ExportSemaphoreWin32HandleInfoKHR Source #

VkExportSemaphoreWin32HandleInfoKHR - Structure specifying additional attributes of Windows handles exported from a semaphore

Description

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

If ExportSemaphoreCreateInfo is included in the pNext chain of SemaphoreCreateInfo with a Windows handleType, but either ExportSemaphoreWin32HandleInfoKHR 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_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT

The implementation must ensure the access rights allow both signal and wait operations on the semaphore.

For handles of the following types:

EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT

The access rights must be:

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

Valid Usage

Valid Usage (Implicit)

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

See Also

VK_KHR_external_semaphore_win32, StructureType

Constructors

ExportSemaphoreWin32HandleInfoKHR 

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 semaphore.

Instances

Instances details
Storable ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Show ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Eq ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

FromCStruct ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

ToCStruct ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Zero ExportSemaphoreWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

data D3D12FenceSubmitInfoKHR Source #

VkD3D12FenceSubmitInfoKHR - Structure specifying values for Direct3D 12 fence-backed semaphores

Description

If the semaphore in SubmitInfo::pWaitSemaphores or SubmitInfo::pSignalSemaphores corresponding to an entry in pWaitSemaphoreValues or pSignalSemaphoreValues respectively does not currently have a payload referring to a Direct3D 12 fence, the implementation must ignore the value in the pWaitSemaphoreValues or pSignalSemaphoreValues entry.

Note

As the introduction of the external semaphore handle type EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of timeline semaphores, support for importing semaphore payloads from external handles of that type into semaphores created (implicitly or explicitly) with a SemaphoreType of SEMAPHORE_TYPE_BINARY is preserved for backwards compatibility. However, applications should prefer importing such handle types into semaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE, and use the TimelineSemaphoreSubmitInfo structure instead of the D3D12FenceSubmitInfoKHR structure to specify the values to use when waiting for and signaling such semaphores.

Valid Usage

  • waitSemaphoreValuesCount must be the same value as SubmitInfo::waitSemaphoreCount, where this structure is in the pNext chain of a SubmitInfo structure
  • signalSemaphoreValuesCount must be the same value as SubmitInfo::signalSemaphoreCount, where this structure is in the pNext chain of a SubmitInfo structure

Valid Usage (Implicit)

  • If waitSemaphoreValuesCount is not 0, and pWaitSemaphoreValues is not NULL, pWaitSemaphoreValues must be a valid pointer to an array of waitSemaphoreValuesCount uint64_t values
  • If signalSemaphoreValuesCount is not 0, and pSignalSemaphoreValues is not NULL, pSignalSemaphoreValues must be a valid pointer to an array of signalSemaphoreValuesCount uint64_t values

See Also

VK_KHR_external_semaphore_win32, StructureType

Constructors

D3D12FenceSubmitInfoKHR 

Fields

data SemaphoreGetWin32HandleInfoKHR Source #

VkSemaphoreGetWin32HandleInfoKHR - Structure describing a Win32 handle semaphore export operation

Description

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

Valid Usage

  • handleType must have been included in ExportSemaphoreCreateInfo::handleTypes when the semaphore’s current payload was created
  • If handleType is defined as an NT handle, getSemaphoreWin32HandleKHR must be called no more than once for each valid unique combination of semaphore and handleType
  • semaphore must not currently have its payload replaced by an imported payload as described below in Importing Semaphore Payloads unless that imported payload’s handle type was included in ExternalSemaphoreProperties::exportFromImportedHandleTypes for handleType
  • If handleType refers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting on semaphore
  • If handleType refers to a handle type with copy payload transference semantics, semaphore must be signaled, or have an associated semaphore signal operation pending execution
  • handleType must be defined as an NT handle or a global share handle

Valid Usage (Implicit)

See Also

VK_KHR_external_semaphore_win32, ExternalSemaphoreHandleTypeFlagBits, Semaphore, StructureType, getSemaphoreWin32HandleKHR

Constructors

SemaphoreGetWin32HandleInfoKHR 

Fields

Instances

Instances details
Storable SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Show SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Eq SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

FromCStruct SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

ToCStruct SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

Zero SemaphoreGetWin32HandleInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32

type KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME = "VK_KHR_external_semaphore_win32" Source #

type HANDLE = Ptr () Source #