Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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
SemaphoreGetWin32HandleInfoKHR
Extending
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 #
:: 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
VK_KHR_external_semaphore_win32,
Device
, SemaphoreGetWin32HandleInfoKHR
importSemaphoreWin32HandleKHR Source #
:: 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
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_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
-
handleType
must be a value included in the Handle Types Supported by table
- If
handleType
is notEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT
orEXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT
,name
must beNULL
- If
handle
isNULL
,name
must name a valid synchronization primitive of the type specified byhandleType
- If
name
isNULL
,handle
must be a valid handle of the type specified byhandleType
- If
handle
is notNULL
,name
must beNULL
- If
handle
is notNULL
, it must obey any requirements listed forhandleType
in external semaphore handle types compatibility - If
name
is notNULL
, it must obey any requirements listed forhandleType
in external semaphore handle types compatibility - If
handleType
isEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT
orEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT
, theSemaphoreCreateInfo
::flags
field must match that of the semaphore from whichhandle
orname
was exported - If
handleType
isEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT
orEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT
, theSemaphoreTypeCreateInfo
::semaphoreType
field must match that of the semaphore from whichhandle
orname
was exported - If
flags
containsSEMAPHORE_IMPORT_TEMPORARY_BIT
, theSemaphoreTypeCreateInfo
::semaphoreType
field of the semaphore from whichhandle
orname
was exported must not beSEMAPHORE_TYPE_TIMELINE
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
pNext
must beNULL
-
semaphore
must be a validSemaphore
handle -
flags
must be a valid combination ofSemaphoreImportFlagBits
values
Host Synchronization
- Host access to
semaphore
must be externally synchronized
See Also
VK_KHR_external_semaphore_win32,
ExternalSemaphoreHandleTypeFlagBits
,
Semaphore
,
SemaphoreImportFlags
,
StructureType
,
importSemaphoreWin32HandleKHR
ImportSemaphoreWin32HandleInfoKHR | |
|
Instances
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
Valid Usage
- If
ExportSemaphoreCreateInfo
::handleTypes
does not includeEXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT
orEXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT
,ExportSemaphoreWin32HandleInfoKHR
must not be included in thepNext
chain ofSemaphoreCreateInfo
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
- If
pAttributes
is notNULL
,pAttributes
must be a valid pointer to a validSECURITY_ATTRIBUTES
value
See Also
ExportSemaphoreWin32HandleInfoKHR | |
|
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
-
waitSemaphoreValuesCount
must be the same value asSubmitInfo
::waitSemaphoreCount
, where this structure is in thepNext
chain of aSubmitInfo
structure
-
signalSemaphoreValuesCount
must be the same value asSubmitInfo
::signalSemaphoreCount
, where this structure is in thepNext
chain of aSubmitInfo
structure
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR
- If
waitSemaphoreValuesCount
is not0
, andpWaitSemaphoreValues
is notNULL
,pWaitSemaphoreValues
must be a valid pointer to an array ofwaitSemaphoreValuesCount
uint64_t
values - If
signalSemaphoreValuesCount
is not0
, andpSignalSemaphoreValues
is notNULL
,pSignalSemaphoreValues
must be a valid pointer to an array ofsignalSemaphoreValuesCount
uint64_t
values
See Also
D3D12FenceSubmitInfoKHR | |
|
Instances
Show D3D12FenceSubmitInfoKHR Source # | |
Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32 showsPrec :: Int -> D3D12FenceSubmitInfoKHR -> ShowS # show :: D3D12FenceSubmitInfoKHR -> String # showList :: [D3D12FenceSubmitInfoKHR] -> ShowS # | |
FromCStruct D3D12FenceSubmitInfoKHR Source # | |
ToCStruct D3D12FenceSubmitInfoKHR Source # | |
Defined in Vulkan.Extensions.VK_KHR_external_semaphore_win32 withCStruct :: D3D12FenceSubmitInfoKHR -> (Ptr D3D12FenceSubmitInfoKHR -> IO b) -> IO b Source # pokeCStruct :: Ptr D3D12FenceSubmitInfoKHR -> D3D12FenceSubmitInfoKHR -> IO b -> IO b Source # withZeroCStruct :: (Ptr D3D12FenceSubmitInfoKHR -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr D3D12FenceSubmitInfoKHR -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero D3D12FenceSubmitInfoKHR Source # | |
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 inExportSemaphoreCreateInfo
::handleTypes
when thesemaphore
’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 ofsemaphore
andhandleType
-
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 inExternalSemaphoreProperties
::exportFromImportedHandleTypes
forhandleType
- 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 onsemaphore
- 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 beSTRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR
-
pNext
must beNULL
-
semaphore
must be a validSemaphore
handle -
handleType
must be a validExternalSemaphoreHandleTypeFlagBits
value
See Also
VK_KHR_external_semaphore_win32,
ExternalSemaphoreHandleTypeFlagBits
,
Semaphore
,
StructureType
,
getSemaphoreWin32HandleKHR
SemaphoreGetWin32HandleInfoKHR | |
|
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 #