// Copyright 2020-2022 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_synchronization2.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2020-12-03
*Interactions and External Dependencies*::
  - Promoted to Vulkan 1.3 Core
  - Interacts with `apiext: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 etext:MEMORY_READ and etext: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 ename:VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR and
ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR layouts which are contextually
applied based on the image format.
For example, for a depth format image,
ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR is equivalent to
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR.
ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR also functionally replaces
ename: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,
`apiext:VK_KHR_device_group`, and `apiext: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 pname:oldLayout equal to pname:newLayout.
  ** E.g. the old and new layout can both be set to
     ename: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 tlink:VkPipelineStageFlags
    or elink:VkPipelineStageFlagBits parameter have had those APIs replaced
    with equivalents using tlink: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
    ename:VK_PIPELINE_STAGE_NONE_KHR and ename:VK_PIPELINE_STAGE_2_NONE_KHR
    values.
ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[]
  * slink:VkMemoryBarrier2KHR can be chained to slink:VkSubpassDependency2,
    overriding the original 32-bit stage and access masks.
endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[]

include::{generated}/interfaces/VK_KHR_synchronization2.adoc[]

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