VK_KHR_synchronization2(3)

# VK_KHR_synchronization2(3) Manual Page

## Name

VK_KHR_synchronization2 - device extension

Loading… please wait.

## Registered Extension Number

315

## Revision

1

## Extension and Version Dependencies

- Requires support for Vulkan 1.0

- Requires `VK_KHR_get_physical_device_properties2` to be enabled for any device-level functionality

## Deprecation state

- Promoted to Vulkan 1.3

## Contact

- Tobias Hector tobski

## 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 `VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR` and `VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR` layouts which are contextually applied based on the image format. For example, for a depth format image, `VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR` is equivalent to `VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR`. `VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR` also functionally replaces `VK_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`.

  - E.g. the old and new layout can both be set to `VK_IMAGE_LAYOUT_UNDEFINED`, without discarding data in the image.

- 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 VkPipelineStageFlags or VkPipelineStageFlagBits parameter have had those APIs replaced with equivalents using VkPipelineStageFlags2KHR.

- 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 `VK_PIPELINE_STAGE_NONE_KHR` and `VK_PIPELINE_STAGE_2_NONE_KHR` values.

- VkMemoryBarrier2KHR can be chained to VkSubpassDependency2, overriding the original 32-bit stage and access masks.

## New Base Types

- `VkFlags64`

## New Commands

- vkCmdPipelineBarrier2KHR

- vkCmdResetEvent2KHR

- vkCmdSetEvent2KHR

- vkCmdWaitEvents2KHR

- vkCmdWriteTimestamp2KHR

- vkQueueSubmit2KHR

If VK_AMD_buffer_marker is supported:

- vkCmdWriteBufferMarker2AMD

If VK_NV_device_diagnostic_checkpoints is supported:

- vkGetQueueCheckpointData2NV

## New Structures

- VkBufferMemoryBarrier2KHR

- VkCommandBufferSubmitInfoKHR

- VkDependencyInfoKHR

- VkImageMemoryBarrier2KHR

- VkSemaphoreSubmitInfoKHR

- VkSubmitInfo2KHR

- Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:

  - VkPhysicalDeviceSynchronization2FeaturesKHR

- Extending VkSubpassDependency2:

  - VkMemoryBarrier2KHR

If VK_NV_device_diagnostic_checkpoints is supported:

- VkCheckpointData2NV

- Extending VkQueueFamilyProperties2:

  - VkQueueFamilyCheckpointProperties2NV

## New Enums

- VkAccessFlagBits2KHR

- VkPipelineStageFlagBits2KHR

- VkSubmitFlagBitsKHR

## New Bitmasks

- VkAccessFlags2KHR

- VkPipelineStageFlags2KHR

- VkSubmitFlagsKHR

## New Enum Constants

- `VK_KHR_SYNCHRONIZATION_2_EXTENSION_NAME`

- `VK_KHR_SYNCHRONIZATION_2_SPEC_VERSION`

- Extending VkAccessFlagBits:

  - `VK_ACCESS_NONE_KHR`

- Extending VkEventCreateFlagBits:

  - `VK_EVENT_CREATE_DEVICE_ONLY_BIT_KHR`

- Extending VkImageLayout:

  - `VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR`

  - `VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR`

- Extending VkPipelineStageFlagBits:

  - `VK_PIPELINE_STAGE_NONE_KHR`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2_KHR`

  - `VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO_KHR`

  - `VK_STRUCTURE_TYPE_DEPENDENCY_INFO_KHR`

  - `VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2_KHR`

  - `VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES_KHR`

  - `VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO_KHR`

  - `VK_STRUCTURE_TYPE_SUBMIT_INFO_2_KHR`

If VK_EXT_blend_operation_advanced is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT`

If VK_EXT_conditional_rendering is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT`

If VK_EXT_fragment_density_map is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

If VK_EXT_mesh_shader is supported:

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT`

  - `VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT`

If VK_EXT_transform_feedback is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT`

  - `VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT`

  - `VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT`

If VK_KHR_acceleration_structure is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR`

  - `VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR`

If VK_KHR_fragment_shading_rate is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

If VK_KHR_ray_tracing_pipeline is supported:

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR`

If VK_NV_device_diagnostic_checkpoints is supported:

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV`

  - `VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV`

If VK_NV_device_generated_commands is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV`

  - `VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV`

If VK_NV_mesh_shader is supported:

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV`

  - `VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV`

If VK_NV_ray_tracing is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_NV`

  - `VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_NV`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_NV`

  - `VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_NV`

If VK_NV_shading_rate_image is supported:

- Extending VkAccessFlagBits2:

  - `VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV`

- Extending VkPipelineStageFlagBits2:

  - `VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV`

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

VkAccessFlagBits2KHR, VkAccessFlags2KHR, VkBufferMemoryBarrier2KHR, VkCommandBufferSubmitInfoKHR, VkDependencyInfoKHR, `VkFlags64`, VkImageMemoryBarrier2KHR, VkMemoryBarrier2KHR, VkPhysicalDeviceSynchronization2FeaturesKHR, VkPipelineStageFlagBits2KHR, VkPipelineStageFlags2KHR, VkSemaphoreSubmitInfoKHR, VkSubmitFlagBitsKHR, VkSubmitFlagsKHR, VkSubmitInfo2KHR, vkCmdPipelineBarrier2KHR, vkCmdResetEvent2KHR, vkCmdSetEvent2KHR, vkCmdWaitEvents2KHR, vkCmdWriteTimestamp2KHR, vkQueueSubmit2KHR

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

## Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0