Vulkan.Extensions.VK_KHR_external_semaphore_win32

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

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_TOO_MANY_OBJECTS

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_external_semaphore_win32, Device, SemaphoreGetWin32HandleInfoKHR

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

• SUCCESS

Failure

• ERROR_INVALID_EXTERNAL_HANDLE

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_external_semaphore_win32, Device, ImportSemaphoreWin32HandleInfoKHR

VkImportSemaphoreWin32HandleInfoKHR - Structure specifying Windows handle to import to a semaphore

Description

The handle types supported by handleType are:

Handle Types Supported by ImportSemaphoreWin32HandleInfoKHR

Valid Usage

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

• If handleType is not EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_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 semaphore handle types compatibility

• If name is not NULL, it must obey any requirements listed for handleType in external semaphore handle types compatibility

• If handleType is EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the SemaphoreCreateInfo::flags field must match that of the semaphore from which handle or name was exported

• If handleType is EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the SemaphoreTypeCreateInfo::semaphoreType field must match that of the semaphore from which handle or name was exported

• If flags contains SEMAPHORE_IMPORT_TEMPORARY_BIT, the SemaphoreTypeCreateInfo::semaphoreType field of the semaphore from which handle or name was exported must not be SEMAPHORE_TYPE_TIMELINE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

• pNext must be NULL

• semaphore must be a valid Semaphore handle

• flags must be a valid combination of SemaphoreImportFlagBits values

Host Synchronization

• Host access to semaphore must be externally synchronized

See Also

VK_KHR_external_semaphore_win32, ExternalSemaphoreHandleTypeFlagBits, Semaphore, SemaphoreImportFlags, StructureType, importSemaphoreWin32HandleKHR

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

• If ExportSemaphoreCreateInfo::handleTypes does not include EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT, ExportSemaphoreWin32HandleInfoKHR must not be included in the pNext chain of SemaphoreCreateInfo

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR

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

Structure Chaining

Extends the structure

• SemaphoreCreateInfo

See Also

VK_KHR_external_semaphore_win32, StructureType

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.

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)

• sType must be STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR

• 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

Structure Chaining

Extends the structure

• SubmitInfo

See Also

VK_KHR_external_semaphore_win32, StructureType

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)

• sType must be STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR

• pNext must be NULL

• semaphore must be a valid Semaphore handle

• handleType must be a valid ExternalSemaphoreHandleTypeFlagBits value

See Also

VK_KHR_external_semaphore_win32, ExternalSemaphoreHandleTypeFlagBits, Semaphore, StructureType, getSemaphoreWin32HandleKHR