| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
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
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Requires
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
SemaphoreGetWin32HandleInfoKHRExtending
SemaphoreCreateInfo:Extending
SubmitInfo:
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
- getSemaphoreWin32HandleKHR :: forall io. MonadIO io => Device -> SemaphoreGetWin32HandleInfoKHR -> io HANDLE
- importSemaphoreWin32HandleKHR :: forall io. MonadIO io => Device -> ImportSemaphoreWin32HandleInfoKHR -> io ()
- data ImportSemaphoreWin32HandleInfoKHR = ImportSemaphoreWin32HandleInfoKHR {}
- data ExportSemaphoreWin32HandleInfoKHR = ExportSemaphoreWin32HandleInfoKHR {}
- data D3D12FenceSubmitInfoKHR = D3D12FenceSubmitInfoKHR {}
- data SemaphoreGetWin32HandleInfoKHR = SemaphoreGetWin32HandleInfoKHR {}
- type KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION = 1
- pattern KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION :: forall a. Integral a => a
- type KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME = "VK_KHR_external_semaphore_win32"
- pattern KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- type HANDLE = Ptr ()
- type DWORD = Word32
- type LPCWSTR = Ptr CWchar
- data SECURITY_ATTRIBUTES
Documentation
getSemaphoreWin32HandleKHR Source #
Arguments
| :: forall io. MonadIO io | |
| => Device |
|
| -> SemaphoreGetWin32HandleInfoKHR |
|
| -> 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
See Also
importSemaphoreWin32HandleKHR Source #
Arguments
| :: forall io. MonadIO io | |
| => Device |
|
| -> ImportSemaphoreWin32HandleInfoKHR |
|
| -> 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
See Also
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_BIT | Reference | Temporary,Permanent |
EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Reference | Temporary,Permanent |
EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT | Reference | Temporary,Permanent |
Handle Types Supported by ImportSemaphoreWin32HandleInfoKHR
Valid Usage
-
handleTypemust be a value included in the Handle Types Supported by table
- If
handleTypeis notEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITorEXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,namemust beNULL - If
handleisNULL,namemust name a valid synchronization primitive of the type specified byhandleType - If
nameisNULL,handlemust be a valid handle of the type specified byhandleType - If
handleis notNULL,namemust beNULL - If
handleis notNULL, it must obey any requirements listed forhandleTypein external semaphore handle types compatibility - If
nameis notNULL, it must obey any requirements listed forhandleTypein external semaphore handle types compatibility - If
handleTypeisEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITorEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, theSemaphoreCreateInfo::flagsfield must match that of the semaphore from whichhandleornamewas exported - If
handleTypeisEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITorEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, theSemaphoreTypeCreateInfo::semaphoreTypefield must match that of the semaphore from whichhandleornamewas exported - If
flagscontainsSEMAPHORE_IMPORT_TEMPORARY_BIT, theSemaphoreTypeCreateInfo::semaphoreTypefield of the semaphore from whichhandleornamewas exported must not beSEMAPHORE_TYPE_TIMELINE
Valid Usage (Implicit)
-
sTypemust beSTRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
pNextmust beNULL -
semaphoremust be a validSemaphorehandle -
flagsmust be a valid combination ofSemaphoreImportFlagBitsvalues
Host Synchronization
- Host access to
semaphoremust be externally synchronized
See Also
ExternalSemaphoreHandleTypeFlagBits,
Semaphore,
SemaphoreImportFlags,
StructureType,
importSemaphoreWin32HandleKHR
Constructors
| ImportSemaphoreWin32HandleInfoKHR | |
Fields
| |
Instances
data ExportSemaphoreWin32HandleInfoKHR Source #
VkExportSemaphoreWin32HandleInfoKHR - Structure specifying additional attributes of Windows handles exported from a semaphore
Description
If
ExportSemaphoreCreateInfo
is not present in the same pNext chain, this structure is ignored.
If
ExportSemaphoreCreateInfo
is present in the pNext chain of
SemaphoreCreateInfo with a Windows
handleType, but either ExportSemaphoreWin32HandleInfoKHR is not
present 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 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
Valid Usage
- If
ExportSemaphoreCreateInfo::handleTypesdoes not includeEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITorEXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,ExportSemaphoreWin32HandleInfoKHRmust not be included in thepNextchain ofSemaphoreCreateInfo
Valid Usage (Implicit)
-
sTypemust beSTRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
- If
pAttributesis notNULL,pAttributesmust be a valid pointer to a validSECURITY_ATTRIBUTESvalue
See Also
Constructors
| ExportSemaphoreWin32HandleInfoKHR | |
Fields
| |
Instances
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
-
waitSemaphoreValuesCountmust be the same value asSubmitInfo::waitSemaphoreCount, whereSubmitInfois in thepNextchain of thisD3D12FenceSubmitInfoKHRstructure.
-
signalSemaphoreValuesCountmust be the same value asSubmitInfo::signalSemaphoreCount, whereSubmitInfois in thepNextchain of thisD3D12FenceSubmitInfoKHRstructure.
Valid Usage (Implicit)
-
sTypemust beSTRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR
- If
waitSemaphoreValuesCountis not0, andpWaitSemaphoreValuesis notNULL,pWaitSemaphoreValuesmust be a valid pointer to an array ofwaitSemaphoreValuesCountuint64_tvalues - If
signalSemaphoreValuesCountis not0, andpSignalSemaphoreValuesis notNULL,pSignalSemaphoreValuesmust be a valid pointer to an array ofsignalSemaphoreValuesCountuint64_tvalues
See Also
Constructors
| D3D12FenceSubmitInfoKHR | |
Fields
| |
Instances
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
-
handleTypemust have been included inExportSemaphoreCreateInfo::handleTypeswhen thesemaphore’s current payload was created
- If
handleTypeis defined as an NT handle,getSemaphoreWin32HandleKHRmust be called no more than once for each valid unique combination ofsemaphoreandhandleType -
semaphoremust 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 inExternalSemaphoreProperties::exportFromImportedHandleTypesforhandleType - If
handleTyperefers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting onsemaphore - If
handleTyperefers to a handle type with copy payload transference semantics,semaphoremust be signaled, or have an associated semaphore signal operation pending execution -
handleTypemust be defined as an NT handle or a global share handle
Valid Usage (Implicit)
-
sTypemust beSTRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR
-
pNextmust beNULL -
semaphoremust be a validSemaphorehandle -
handleTypemust be a validExternalSemaphoreHandleTypeFlagBitsvalue
See Also
ExternalSemaphoreHandleTypeFlagBits,
Semaphore,
StructureType,
getSemaphoreWin32HandleKHR
Constructors
| SemaphoreGetWin32HandleInfoKHR | |
Fields
| |
Instances
pattern KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION :: forall a. Integral a => a Source #
type KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME = "VK_KHR_external_semaphore_win32" Source #
pattern KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #
data SECURITY_ATTRIBUTES Source #