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

Vulkan.Extensions.VK_KHR_synchronization2

Description

Name

VK_KHR_synchronization2 - device extension

VK_KHR_synchronization2

Name String
VK_KHR_synchronization2
Extension Type
Device extension
Registered Extension Number
315
Revision
1
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_get_physical_device_properties2 or Version 1.1
Deprecation State
Contact

Other Extension Metadata

Last Modified Date
2020-12-03
Interactions and External Dependencies
  • Promoted to Vulkan 1.3 Core
  • Interacts with VK_KHR_create_renderpass2
Contributors
  • Tobias Hector

Description

This extension modifies the original core synchronization APIs to simplify the interface and improve usability of these APIs. It also adds new pipeline stage and access flag types that extend into the 64-bit range, as we have run out within the 32-bit range. The new flags are identical to the old values within the 32-bit range, with new stages and bits beyond that.

Pipeline stages and access flags are now specified together in memory barrier structures, making the connection between the two more obvious. Additionally, scoping the pipeline stages into the barrier structs allows the use of the MEMORY_READ and MEMORY_WRITE flags without sacrificing precision. The per-stage access flags should be used to disambiguate specific accesses in a given stage or set of stages - for instance, between uniform reads and sampling operations.

Layout transitions have been simplified as well; rather than requiring a different set of layouts for depth/stencil/color attachments, there are generic IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR and IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR layouts which are contextually applied based on the image format. For example, for a depth format image, IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR is equivalent to IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR. IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR also functionally replaces IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.

Events are now more efficient, because they include memory dependency information when you set them on the device. Previously, this information was only known when waiting on an event, so the dependencies could not be satisfied until the wait occurred. That sometimes meant stalling the pipeline when the wait occurred. The new API provides enough information for implementations to satisfy these dependencies in parallel with other tasks.

Queue submission has been changed to wrap command buffers and semaphores in extensible structures, which incorporate changes from Vulkan 1.1, VK_KHR_device_group, and VK_KHR_timeline_semaphore. This also adds a pipeline stage to the semaphore signal operation, mirroring the existing pipeline stage specification for wait operations.

Other miscellaneous changes include:

  • Events can now be specified as interacting only with the device, allowing more efficient access to the underlying object.
  • Image memory barriers that do not perform an image layout transition can be specified by setting oldLayout equal to newLayout.

  • Queue family ownership transfer parameters are simplified in some cases.
  • Where two synchronization commands need to be matched up (queue transfer operations, events), the dependency information specified in each place must now match completely for consistency.
  • Extensions with commands or functions with a PipelineStageFlags or PipelineStageFlagBits parameter have had those APIs replaced with equivalents using PipelineStageFlags2KHR.
  • The new event and barrier interfaces are now more extensible for future changes.
  • Relevant pipeline stage masks can now be specified as empty with the new PIPELINE_STAGE_NONE_KHR and PIPELINE_STAGE_2_NONE_KHR values.
  • MemoryBarrier2KHR can be chained to SubpassDependency2, overriding the original 32-bit stage and access masks.

New Base Types

New Commands

If VK_AMD_buffer_marker is supported:

If VK_NV_device_diagnostic_checkpoints is supported:

New Structures

If VK_NV_device_diagnostic_checkpoints is supported:

New Enums

New Bitmasks

New Enum Constants

If VK_EXT_blend_operation_advanced is supported:

If VK_EXT_conditional_rendering is supported:

If VK_EXT_fragment_density_map is supported:

If VK_EXT_mesh_shader is supported:

If VK_EXT_transform_feedback is supported:

If VK_KHR_acceleration_structure is supported:

If VK_KHR_fragment_shading_rate is supported:

If VK_KHR_ray_tracing_pipeline is supported:

If VK_NV_device_diagnostic_checkpoints is supported:

If VK_NV_device_generated_commands is supported:

If VK_NV_mesh_shader is supported:

If VK_NV_ray_tracing is supported:

If VK_NV_shading_rate_image is supported:

Promotion to Vulkan 1.3

Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Examples

See https://github.com/KhronosGroup/Vulkan-Docs/wiki/Synchronization-Examples

Version History

  • Revision 1, 2020-12-03 (Tobias Hector)

    • Internal revisions

See Also

AccessFlagBits2KHR, AccessFlags2KHR, BufferMemoryBarrier2KHR, CommandBufferSubmitInfoKHR, DependencyInfoKHR, Flags64, ImageMemoryBarrier2KHR, MemoryBarrier2KHR, PhysicalDeviceSynchronization2FeaturesKHR, PipelineStageFlagBits2KHR, PipelineStageFlags2KHR, SemaphoreSubmitInfoKHR, SubmitFlagBitsKHR, SubmitFlagsKHR, SubmitInfo2KHR, cmdPipelineBarrier2KHR, cmdResetEvent2KHR, cmdSetEvent2KHR, cmdWaitEvents2KHR, cmdWriteTimestamp2KHR, queueSubmit2KHR

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

cmdWriteBufferMarker2AMD Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command will be recorded.

-> PipelineStageFlags2

stage specifies the pipeline stage whose completion triggers the marker write.

-> ("dstBuffer" ::: Buffer)

dstBuffer is the buffer where the marker will be written.

-> ("dstOffset" ::: DeviceSize)

dstOffset is the byte offset into the buffer where the marker will be written.

-> ("marker" ::: Word32)

marker is the 32-bit value of the marker.

-> io () 

vkCmdWriteBufferMarker2AMD - Execute a pipelined write of a marker value into a buffer

Description

The command will write the 32-bit marker value into the buffer only after all preceding commands have finished executing up to at least the specified pipeline stage. This includes the completion of other preceding cmdWriteBufferMarker2AMD commands so long as their specified pipeline stages occur either at the same time or earlier than this command’s specified stage.

While consecutive buffer marker writes with the same stage parameter implicitly complete in submission order, memory and execution dependencies between buffer marker writes and other operations must still be explicitly ordered using synchronization commands. The access scope for buffer marker writes falls under the ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying the synchronization scope must include both stage and PIPELINE_STAGE_TRANSFER_BIT.

Note

Similar to cmdWriteTimestamp2, if an implementation is unable to write a marker at any specific pipeline stage, it may instead do so at any logically later stage.

Note

Implementations may only support a limited number of pipelined marker write operations in flight at a given time. Thus an excessive number of marker write operations may degrade command execution performance.

Valid Usage

Valid Usage (Implicit)

  • stage must be a valid combination of PipelineStageFlagBits2 values
  • dstBuffer must be a valid Buffer handle
  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
  • This command must only be called outside of a video coding scope
  • Both of commandBuffer, and dstBuffer must have been created, allocated, or retrieved from the same Device

Host Synchronization

  • Host access to commandBuffer must be externally synchronized
  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary Secondary Both Outside Transfer Graphics ComputeAction

See Also

VK_AMD_buffer_marker, VK_KHR_synchronization2, Buffer, CommandBuffer, DeviceSize, PipelineStageFlags2

getQueueCheckpointData2NV Source #

Arguments

:: forall io. MonadIO io 
=> Queue

queue is the Queue object the caller would like to retrieve checkpoint data for

-> io ("checkpointData" ::: Vector CheckpointData2NV) 

vkGetQueueCheckpointData2NV - Retrieve diagnostic checkpoint data

Description

If pCheckpointData is NULL, then the number of checkpoint markers available is returned in pCheckpointDataCount. Otherwise, pCheckpointDataCount must point to a variable set by the user to the number of elements in the pCheckpointData array, and on return the variable is overwritten with the number of structures actually written to pCheckpointData.

If pCheckpointDataCount is less than the number of checkpoint markers available, at most pCheckpointDataCount structures will be written.

Valid Usage

  • The device that queue belongs to must be in the lost state

Valid Usage (Implicit)

  • queue must be a valid Queue handle
  • pCheckpointDataCount must be a valid pointer to a uint32_t value
  • If the value referenced by pCheckpointDataCount is not 0, and pCheckpointData is not NULL, pCheckpointData must be a valid pointer to an array of pCheckpointDataCount CheckpointData2NV structures

See Also

VK_KHR_synchronization2, VK_NV_device_diagnostic_checkpoints, CheckpointData2NV, Queue

cmdWaitEvents2KHR :: MonadIO io => CommandBuffer -> ("events" ::: Vector Event) -> ("dependencyInfos" ::: Vector DependencyInfo) -> io () Source #

queueSubmit2KHR :: MonadIO io => Queue -> ("submits" ::: Vector (SomeStruct SubmitInfo2)) -> Fence -> io () Source #

data QueueFamilyCheckpointProperties2NV Source #

VkQueueFamilyCheckpointProperties2NV - Return structure for queue family checkpoint information query

Description

Additional queue family information can be queried by setting QueueFamilyProperties2::pNext to point to a QueueFamilyCheckpointProperties2NV structure.

Valid Usage (Implicit)

See Also

VK_KHR_synchronization2, VK_NV_device_diagnostic_checkpoints, PipelineStageFlags2, StructureType

Constructors

QueueFamilyCheckpointProperties2NV 

Fields

Instances

Instances details
Storable QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

Show QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

Eq QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

FromCStruct QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

ToCStruct QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

Zero QueueFamilyCheckpointProperties2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

data CheckpointData2NV Source #

VkCheckpointData2NV - Return structure for command buffer checkpoint data

Valid Usage (Implicit)

The stages at which a checkpoint marker can be executed are implementation-defined and can be queried by calling getPhysicalDeviceQueueFamilyProperties2.

See Also

VK_KHR_synchronization2, VK_NV_device_diagnostic_checkpoints, PipelineStageFlags2, StructureType, getQueueCheckpointData2NV

Constructors

CheckpointData2NV 

Fields

  • stage :: PipelineStageFlags2

    stage indicates a single pipeline stage which the checkpoint marker data refers to.

  • checkpointMarker :: Ptr ()

    pCheckpointMarker contains the value of the last checkpoint marker executed in the stage that stage refers to.

Instances

Instances details
Storable CheckpointData2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

Show CheckpointData2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

FromCStruct CheckpointData2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

ToCStruct CheckpointData2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

Zero CheckpointData2NV Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_synchronization2

type KHR_SYNCHRONIZATION_2_EXTENSION_NAME = "VK_KHR_synchronization2" Source #

pattern KHR_SYNCHRONIZATION_2_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #