1// Copyright 2015-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[synchronization]] 6= Synchronization and Cache Control 7 8Synchronization of access to resources is primarily the responsibility of 9the application in Vulkan. 10The order of execution of commands with respect to the host and other 11commands on the device has few implicit guarantees, and needs to be 12explicitly specified. 13Memory caches and other optimizations are also explicitly managed, requiring 14that the flow of data through the system is largely under application 15control. 16 17Whilst some implicit guarantees exist between commands, five explicit 18synchronization mechanisms are exposed by Vulkan: 19 20<<synchronization-fences,Fences>>:: 21 Fences can: be used to communicate to the host that execution of some 22 task on the device has completed. 23 24<<synchronization-semaphores,Semaphores>>:: 25 Semaphores can: be used to control resource access across multiple 26 queues. 27 28<<synchronization-events,Events>>:: 29 Events provide a fine-grained synchronization primitive which can: be 30 signaled either within a command buffer or by the host, and can: be 31 waited upon within a command buffer or queried on the host. 32 33<<synchronization-pipeline-barriers,Pipeline Barriers>>:: 34 Pipeline barriers also provide synchronization control within a command 35 buffer, but at a single point, rather than with separate signal and wait 36 operations. 37 38<<renderpass,Render Passes>>:: 39 Render passes provide a useful synchronization framework for most 40 rendering tasks, built upon the concepts in this chapter. 41 Many cases that would otherwise need an application to use other 42 synchronization primitives can: be expressed more efficiently as part of 43 a render pass. 44 45 46[[synchronization-dependencies]] 47== Execution and Memory Dependencies 48 49An _operation_ is an arbitrary amount of work to be executed on the host, a 50device, or an external entity such as a presentation engine. 51Synchronization commands introduce explicit _execution dependencies_, and 52_memory dependencies_ between two sets of operations defined by the 53command's two _synchronization scopes_. 54 55[[synchronization-dependencies-scopes]] 56The synchronization scopes define which other operations a synchronization 57command is able to create execution dependencies with. 58Any type of operation that is not in a synchronization command's 59synchronization scopes will not be included in the resulting dependency. 60For example, for many synchronization commands, the synchronization scopes 61can: be limited to just operations executing in specific 62<<synchronization-pipeline-stages,pipeline stages>>, which allows other 63pipeline stages to be excluded from a dependency. 64Other scoping options are possible, depending on the particular command. 65 66[[synchronization-dependencies-execution]] 67An _execution dependency_ is a guarantee that for two sets of operations, 68the first set must: _happen-before_ the second set. 69If an operation happens-before another operation, then the first operation 70must: complete before the second operation is initiated. 71More precisely: 72 73 * Let *Ops~1~* and *Ops~2~* be separate sets of operations. 74 * Let *Sync* be a synchronization command. 75 * Let *Scope~1st~* and *Scope~2nd~* be the synchronization scopes of 76 *Sync*. 77 * Let *ScopedOps~1~* be the intersection of sets *Ops~1~* and 78 *Scope~1st~*. 79 * Let *ScopedOps~2~* be the intersection of sets *Ops~2~* and 80 *Scope~2nd~*. 81 * Submitting *Ops~1~*, *Sync* and *Ops~2~* for execution, in that order, 82 will result in execution dependency *ExeDep* between *ScopedOps~1~* and 83 *ScopedOps~2~*. 84 * Execution dependency *ExeDep* guarantees that *ScopedOps~1~* 85 happen-before *ScopedOps~2~*. 86 87[[synchronization-dependencies-chains]] 88An _execution dependency chain_ is a sequence of execution dependencies that 89form a happens-before relation between the first dependency's *ScopedOps~1~* 90and the final dependency's *ScopedOps~2~*. 91For each consecutive pair of execution dependencies, a chain exists if the 92intersection of *Scope~2nd~* in the first dependency and *Scope~1st~* in the 93second dependency is not an empty set. 94The formation of a single execution dependency from an execution dependency 95chain can be described by substituting the following in the description of 96execution dependencies: 97 98 * Let *Sync* be a set of synchronization commands that generate an 99 execution dependency chain. 100 * Let *Scope~1st~* be the first synchronization scope of the first command 101 in *Sync*. 102 * Let *Scope~2nd~* be the second synchronization scope of the last command 103 in *Sync*. 104 105Execution dependencies alone are not sufficient to guarantee that values 106resulting from writes in one set of operations can: be read from another set 107of operations. 108 109[[synchronization-dependencies-available-and-visible]] 110Three additional types of operations are used to control memory access. 111_Availability operations_ cause the values generated by specified memory 112write accesses to become _available_ to a memory domain for future access. 113Any available value remains available until a subsequent write to the same 114memory location occurs (whether it is made available or not) or the memory 115is freed. 116_Memory domain operations_ cause writes that are available to a source 117memory domain to become available to a destination memory domain (an example 118of this is making writes available to the host domain available to the 119device domain). 120_Visibility operations_ cause values available to a memory domain to become 121_visible_ to specified memory accesses. 122 123ifdef::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 124Availability, visibility, memory domains, and memory domain operations are 125formally defined in the <<memory-model-availability-visibility,Availability 126and Visibility>> section of the <<memory-model,Memory Model>> chapter. 127Which API operations perform each of these operations is defined in 128<<memory-model-vulkan-availability-visibility,Availability, Visibility, and 129Domain Operations>>. 130endif::VK_VERSION_1_2,VK_KHR_vulkan_memory_model[] 131 132[[synchronization-dependencies-memory]] 133A _memory dependency_ is an execution dependency which includes availability 134and visibility operations such that: 135 136 * The first set of operations happens-before the availability operation. 137 * The availability operation happens-before the visibility operation. 138 * The visibility operation happens-before the second set of operations. 139 140Once written values are made visible to a particular type of memory access, 141they can: be read or written by that type of memory access. 142Most synchronization commands in Vulkan define a memory dependency. 143 144[[synchronization-dependencies-access-scopes]] 145The specific memory accesses that are made available and visible are defined 146by the _access scopes_ of a memory dependency. 147Any type of access that is in a memory dependency's first access scope and 148occurs in *ScopedOps~1~* is made available. 149Any type of access that is in a memory dependency's second access scope and 150occurs in *ScopedOps~2~* has any available writes made visible to it. 151Any type of operation that is not in a synchronization command's access 152scopes will not be included in the resulting dependency. 153 154A memory dependency enforces availability and visibility of memory accesses 155and execution order between two sets of operations. 156Adding to the description of <<synchronization-dependencies-chains, 157execution dependency chains>>: 158 159 * Let *MemOps~1~* be the set of memory accesses performed by 160 *ScopedOps~1~*. 161 * Let *MemOps~2~* be the set of memory accesses performed by 162 *ScopedOps~2~*. 163 * Let *AccessScope~1st~* be the first access scope of the first command in 164 the *Sync* chain. 165 * Let *AccessScope~2nd~* be the second access scope of the last command in 166 the *Sync* chain. 167 * Let *ScopedMemOps~1~* be the intersection of sets *MemOps~1~* and 168 *AccessScope~1st~*. 169 * Let *ScopedMemOps~2~* be the intersection of sets *MemOps~2~* and 170 *AccessScope~2nd~*. 171 * Submitting *Ops~1~*, *Sync*, and *Ops~2~* for execution, in that order, 172 will result in a memory dependency *MemDep* between *ScopedOps~1~* and 173 *ScopedOps~2~*. 174 * Memory dependency *MemDep* guarantees that: 175 ** Memory writes in *ScopedMemOps~1~* are made available. 176 ** Available memory writes, including those from *ScopedMemOps~1~*, are 177 made visible to *ScopedMemOps~2~*. 178 179[NOTE] 180.Note 181==== 182Execution and memory dependencies are used to solve data hazards, i.e. to 183ensure that read and write operations occur in a well-defined order. 184Write-after-read hazards can be solved with just an execution dependency, 185but read-after-write and write-after-write hazards need appropriate memory 186dependencies to be included between them. 187If an application does not include dependencies to solve these hazards, the 188results and execution orders of memory accesses are undefined:. 189==== 190 191 192[[synchronization-image-layout-transitions]] 193=== Image Layout Transitions 194 195Image subresources can: be transitioned from one <<resources-image-layouts, 196layout>> to another as part of a <<synchronization-dependencies-memory, 197memory dependency>> (e.g. by using an 198<<synchronization-image-memory-barriers,image memory barrier>>). 199When a layout transition is specified in a memory dependency, it 200happens-after the availability operations in the memory dependency, and 201happens-before the visibility operations. 202Image layout transitions may: perform read and write accesses on all memory 203bound to the image subresource range, so applications must: ensure that all 204memory writes have been made 205<<synchronization-dependencies-available-and-visible, available>> before a 206layout transition is executed. 207Available memory is automatically made visible to a layout transition, and 208writes performed by a layout transition are automatically made available. 209 210Layout transitions always apply to a particular image subresource range, and 211specify both an old layout and new layout. 212The old layout must: either be ename:VK_IMAGE_LAYOUT_UNDEFINED, or match the 213current layout of the image subresource range. 214If the old layout matches the current layout of the image subresource range, 215the transition preserves the contents of that range. 216If the old layout is ename:VK_IMAGE_LAYOUT_UNDEFINED, the contents of that 217range may: be discarded. 218 219ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 220As image layout transitions may: perform read and write accesses on the 221memory bound to the image, if the image subresource affected by the layout 222transition is bound to peer memory for any device in the current device mask 223then the memory heap the bound memory comes from must: support the 224ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT and 225ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT capabilities as returned by 226flink:vkGetDeviceGroupPeerMemoryFeatures. 227endif::VK_VERSION_1_1,VK_KHR_device_group[] 228 229[NOTE] 230.Note 231==== 232Applications must: ensure that layout transitions happen-after all 233operations accessing the image with the old layout, and happen-before any 234operations that will access the image with the new layout. 235Layout transitions are potentially read/write operations, so not defining 236appropriate memory dependencies to guarantee this will result in a data 237race. 238==== 239 240Image layout transitions interact with <<resources-memory-aliasing,memory 241aliasing>>. 242 243 244[[synchronization-image-barrier-layout-transition-order]] 245Layout transitions that are performed via image memory barriers execute in 246their entirety in <<synchronization-submission-order, submission order>>, 247relative to other image layout transitions submitted to the same queue, 248including those performed by <<renderpass, render passes>>. 249In effect there is an implicit execution dependency from each such layout 250transition to all layout transitions previously submitted to the same queue. 251 252ifdef::VK_EXT_sample_locations[] 253 254The image layout of each image subresource of a depth/stencil image created 255with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is 256dependent on the last sample locations used to render to the image 257subresource as a depth/stencil attachment, thus when the pname:image member 258of an <<synchronization-image-memory-barriers, image memory barrier>> is an 259image created with this flag the application can: chain a 260slink:VkSampleLocationsInfoEXT structure to the pname:pNext chain of 261ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 262slink:VkImageMemoryBarrier2 or 263endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 264slink:VkImageMemoryBarrier to specify the sample locations to use during any 265image layout transition. 266 267If the sname:VkSampleLocationsInfoEXT structure does not match the sample 268location state last used to render to the image subresource range specified 269by pname:subresourceRange, or if no sname:VkSampleLocationsInfoEXT structure 270is present, then the contents of the given image subresource range becomes 271undefined: as if pname:oldLayout would equal 272ename:VK_IMAGE_LAYOUT_UNDEFINED. 273 274endif::VK_EXT_sample_locations[] 275 276 277[[synchronization-pipeline-stages]] 278=== Pipeline Stages 279 280The work performed by an <<fundamentals-queueoperation-command-types, action 281or synchronization command>> consists of multiple operations, which are 282performed as a sequence of logically independent steps known as _pipeline 283stages_. 284The exact pipeline stages executed depend on the particular command that is 285used, and current command buffer state when the command was recorded. 286<<drawing,Drawing commands>>, <<dispatch,dispatching commands>>, 287<<copies,copy commands>>, <<clears,clear commands>>, and <<synchronization, 288synchronization commands>> all execute in different sets of 289<<VkPipelineStageFlagBits,pipeline stages>>. 290<<synchronization, Synchronization commands>> do not execute in a defined 291pipeline stage. 292 293[NOTE] 294.Note 295==== 296Operations performed by synchronization commands (e.g. 297<<synchronization-dependencies-available-and-visible, availability and 298visibility operations>>) are not executed by a defined pipeline stage. 299However other commands can still synchronize with them by using the 300<<synchronization-dependencies-scopes, synchronization scopes>> to create a 301<<synchronization-dependencies-chains, dependency chain>>. 302==== 303 304Execution of operations across pipeline stages must: adhere to 305<<synchronization-implicit, implicit ordering guarantees>>, particularly 306including <<synchronization-pipeline-stages-order, pipeline stage order>>. 307Otherwise, execution across pipeline stages may: overlap or execute out of 308order with regards to other stages, unless otherwise enforced by an 309execution dependency. 310 311Several of the synchronization commands include pipeline stage parameters, 312restricting the <<synchronization-dependencies-scopes, synchronization 313scopes>> for that command to just those stages. 314This allows fine grained control over the exact execution dependencies and 315accesses performed by action commands. 316Implementations should: use these pipeline stages to avoid unnecessary 317stalls or cache flushing. 318 319ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 320[open,refpage='VkPipelineStageFlagBits2',desc='Pipeline stage flags for VkPipelineStageFlags2',type='enums',alias='VkPipelineStageFlagBits2KHR'] 321-- 322Bits which can: be set in a tlink:VkPipelineStageFlags2 mask, specifying 323stages of execution, are: 324 325ifdef::editing-notes[] 326[NOTE] 327.editing-note 328==== 329The many places pipeline stage flags are used are not currently listed here. 330==== 331endif::editing-notes[] 332 333include::{generated}/api/enums/VkPipelineStageFlagBits2.adoc[] 334 335ifdef::VK_KHR_synchronization2[] 336or the equivalent 337 338include::{generated}/api/enums/VkPipelineStageFlagBits2KHR.adoc[] 339endif::VK_KHR_synchronization2[] 340 341 * ename:VK_PIPELINE_STAGE_2_NONE specifies no stages of execution. 342 * ename:VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT specifies the stage of the 343 pipeline where indirect command parameters are consumed. 344ifdef::VK_NV_device_generated_commands[] 345 This stage also includes reading commands written by 346 flink:vkCmdPreprocessGeneratedCommandsNV. 347endif::VK_NV_device_generated_commands[] 348ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 349 * ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT specifies the task shader 350 stage. 351 * ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT specifies the mesh shader 352 stage. 353endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 354 * ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT specifies the stage of the 355 pipeline where index buffers are consumed. 356 * ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT specifies the stage 357 of the pipeline where vertex buffers are consumed. 358 * ename:VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT is equivalent to the logical 359 OR of: 360 ** ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT 361 ** ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT 362 * ename:VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT specifies the vertex shader 363 stage. 364 * ename:VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT specifies the 365 tessellation control shader stage. 366 * ename:VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT specifies 367 the tessellation evaluation shader stage. 368 * ename:VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT specifies the geometry 369 shader stage. 370 * ename:VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT is equivalent to 371 specifying all supported 372 <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 373 stages>>: 374 ** ename:VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT 375 ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT 376 ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT 377 ** ename:VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT 378ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 379 ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT 380 ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT 381endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 382 * ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT specifies the fragment 383 shader stage. 384 * ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT specifies the stage 385 of the pipeline where early fragment tests (depth and stencil tests 386 before fragment shading) are performed. 387 This stage also includes <<renderpass-load-store-ops, subpass load 388 operations>> for framebuffer attachments with a depth/stencil format. 389 * ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT specifies the stage of 390 the pipeline where late fragment tests (depth and stencil tests after 391 fragment shading) are performed. 392 This stage also includes <<renderpass-load-store-ops, subpass store 393 operations>> for framebuffer attachments with a depth/stencil format. 394 * ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT specifies the 395 stage of the pipeline after blending where the final color values are 396 output from the pipeline. 397 This stage also includes <<renderpass-load-store-ops, subpass load and 398 store operations>>, multisample resolve operations for framebuffer 399 attachments with a color 400ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 401 or depth/stencil 402endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 403 format, and flink:vkCmdClearAttachments. 404 * ename:VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT specifies the compute 405 shader stage. 406 * ename:VK_PIPELINE_STAGE_2_HOST_BIT specifies a pseudo-stage indicating 407 execution on the host of reads/writes of device memory. 408 This stage is not invoked by any commands recorded in a command buffer. 409 * ename:VK_PIPELINE_STAGE_2_COPY_BIT specifies the execution of all 410 <<copies,copy commands>>, including flink:vkCmdCopyQueryPoolResults. 411 * ename:VK_PIPELINE_STAGE_2_BLIT_BIT specifies the execution of 412 flink:vkCmdBlitImage. 413 * ename:VK_PIPELINE_STAGE_2_RESOLVE_BIT specifies the execution of 414 flink:vkCmdResolveImage. 415 * ename:VK_PIPELINE_STAGE_2_CLEAR_BIT specifies the execution of 416 <<clears,clear commands>>, with the exception of 417 flink:vkCmdClearAttachments. 418 * ename:VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT is equivalent to specifying 419 all of: 420 ** ename:VK_PIPELINE_STAGE_2_COPY_BIT 421 ** ename:VK_PIPELINE_STAGE_2_BLIT_BIT 422 ** ename:VK_PIPELINE_STAGE_2_RESOLVE_BIT 423 ** ename:VK_PIPELINE_STAGE_2_CLEAR_BIT 424ifdef::VK_KHR_ray_tracing_maintenance1[] 425 ** ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 426endif::VK_KHR_ray_tracing_maintenance1[] 427ifdef::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 428 * ename:VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR specifies the 429 execution of the ray tracing shader stages. 430endif::VK_KHR_ray_tracing_pipeline,VK_NV_ray_tracing[] 431ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 432 * ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR specifies 433 the execution of <<acceleration-structure, acceleration structure 434 commands>>. 435ifdef::VK_KHR_ray_tracing_maintenance1[] 436 * ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR specifies 437 the execution of <<acceleration-structure-copying, acceleration 438 structure copy commands>>. 439endif::VK_KHR_ray_tracing_maintenance1[] 440endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 441 * ename:VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT specifies the execution of 442 all graphics pipeline stages, and is equivalent to the logical OR of: 443 ** ename:VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT 444ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 445 ** ename:VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT 446 ** ename:VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT 447endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 448 ** ename:VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT 449 ** ename:VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT 450 ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT 451 ** ename:VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT 452 ** ename:VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT 453 ** ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT 454 ** ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT 455 ** ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT 456 ** ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT 457ifdef::VK_EXT_conditional_rendering[] 458 ** ename:VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT 459endif::VK_EXT_conditional_rendering[] 460ifdef::VK_EXT_transform_feedback[] 461 ** ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT 462endif::VK_EXT_transform_feedback[] 463ifdef::VK_NV_shading_rate_image[] 464 ** ename:VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV 465endif::VK_NV_shading_rate_image[] 466ifdef::VK_EXT_fragment_density_map[] 467 ** ename:VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT 468endif::VK_EXT_fragment_density_map[] 469ifdef::VK_HUAWEI_invocation_mask[] 470 ** ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI 471endif::VK_HUAWEI_invocation_mask[] 472 * ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT specifies all operations 473 performed by all commands supported on the queue it is used with. 474ifdef::VK_EXT_conditional_rendering[] 475 * ename:VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT specifies the 476 stage of the pipeline where the predicate of conditional rendering is 477 consumed. 478endif::VK_EXT_conditional_rendering[] 479ifdef::VK_EXT_transform_feedback[] 480 * ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT specifies the stage 481 of the pipeline where vertex attribute output values are written to the 482 transform feedback buffers. 483endif::VK_EXT_transform_feedback[] 484ifdef::VK_NV_device_generated_commands[] 485 * ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV specifies the stage 486 of the pipeline where device-side generation of commands via 487 flink:vkCmdPreprocessGeneratedCommandsNV is handled. 488endif::VK_NV_device_generated_commands[] 489ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 490 * ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 491 specifies the stage of the pipeline where the 492ifdef::VK_KHR_fragment_shading_rate[] 493 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 494 attachment>> 495endif::VK_KHR_fragment_shading_rate[] 496ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] 497ifdef::VK_NV_shading_rate_image[] 498 <<primsrast-shading-rate-image, shading rate image>> 499endif::VK_NV_shading_rate_image[] 500 is read to determine the fragment shading rate for portions of a 501 rasterized primitive. 502endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 503ifdef::VK_EXT_fragment_density_map[] 504 * ename:VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT specifies the 505 stage of the pipeline where the fragment density map is read to 506 <<fragmentdensitymapops,generate the fragment areas>>. 507endif::VK_EXT_fragment_density_map[] 508ifdef::VK_HUAWEI_invocation_mask[] 509 * ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI specifies the stage 510 of the pipeline where the invocation mask image is read by the 511 implementation to optimize the ray dispatch. 512endif::VK_HUAWEI_invocation_mask[] 513ifdef::VK_KHR_video_decode_queue[] 514 * ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR specifies the execution 515 of <<video-decode-operations, video decode operations>>. 516endif::VK_KHR_video_decode_queue[] 517ifdef::VK_KHR_video_encode_queue[] 518 * ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR specifies the execution 519 of <<video-encode-operations, video encode operations>>. 520endif::VK_KHR_video_encode_queue[] 521ifdef::VK_NV_optical_flow[] 522 * ename:VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV specifies the stage of the 523 pipeline where <<opticalflow-operations, optical flow operation>> are 524 performed. 525endif::VK_NV_optical_flow[] 526ifdef::VK_HUAWEI_subpass_shading[] 527 * ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI specifies the 528 subpass shading shader stage. 529endif::VK_HUAWEI_subpass_shading[] 530ifdef::VK_EXT_opacity_micromap[] 531 * ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT specifies the execution 532 of <<micromap, micromap commands>>. 533endif::VK_EXT_opacity_micromap[] 534 * ename:VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT is equivalent to 535 ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT with tlink:VkAccessFlags2 set 536 to `0` when specified in the second synchronization scope, but 537 equivalent to ename:VK_PIPELINE_STAGE_2_NONE in the first scope. 538 * ename:VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT is equivalent to 539 ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT with tlink:VkAccessFlags2 set 540 to `0` when specified in the first synchronization scope, but equivalent 541 to ename:VK_PIPELINE_STAGE_2_NONE in the second scope. 542 543[NOTE] 544.Note 545==== 546The etext:TOP and etext:BOTTOM pipeline stages are deprecated, and 547applications should prefer ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT and 548ename:VK_PIPELINE_STAGE_2_NONE. 549==== 550 551[NOTE] 552.Note 553==== 554The tname:VkPipelineStageFlags2 bitmask goes beyond the 31 individual bit 555flags allowable within a C99 enum, which is how 556elink:VkPipelineStageFlagBits is defined. 557The first 31 values are common to both, and are interchangeable. 558==== 559-- 560 561[open,refpage='VkPipelineStageFlags2',desc='64-bit mask of pipeline stage flags',type='flags',alias='VkPipelineStageFlags2KHR'] 562-- 563tname:VkPipelineStageFlags2 is a bitmask type for setting a mask of zero or 564more elink:VkPipelineStageFlagBits2 flags: 565 566include::{generated}/api/flags/VkPipelineStageFlags2.adoc[] 567 568ifdef::VK_KHR_synchronization2[] 569or the equivalent 570 571include::{generated}/api/flags/VkPipelineStageFlags2KHR.adoc[] 572endif::VK_KHR_synchronization2[] 573-- 574endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 575 576[open,refpage='VkPipelineStageFlagBits',desc='Bitmask specifying pipeline stages',type='enums'] 577-- 578Bits which can: be set in a tlink:VkPipelineStageFlags mask, specifying 579stages of execution, are: 580 581include::{generated}/api/enums/VkPipelineStageFlagBits.adoc[] 582 583ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 584These values all have the same meaning as the equivalently named values for 585tlink:VkPipelineStageFlags2. 586endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 587 588ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 589 * ename:VK_PIPELINE_STAGE_NONE specifies no stages of execution. 590endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 591 * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT specifies the stage of the 592 pipeline where stext:VkDrawIndirect* / stext:VkDispatchIndirect* / 593 stext:VkTraceRaysIndirect* data structures are consumed. 594ifdef::VK_NV_device_generated_commands[] 595 This stage also includes reading commands written by 596 flink:vkCmdExecuteGeneratedCommandsNV. 597endif::VK_NV_device_generated_commands[] 598ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 599 * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT specifies the task shader 600 stage. 601 * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT specifies the mesh shader 602 stage. 603endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 604 * ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT specifies the stage of the 605 pipeline where vertex and index buffers are consumed. 606 * ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT specifies the vertex shader 607 stage. 608 * ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT specifies the 609 tessellation control shader stage. 610 * ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT specifies the 611 tessellation evaluation shader stage. 612 * ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT specifies the geometry 613 shader stage. 614 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT specifies the fragment 615 shader stage. 616 * ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT specifies the stage of 617 the pipeline where early fragment tests (depth and stencil tests before 618 fragment shading) are performed. 619 This stage also includes <<renderpass-load-store-ops, subpass load 620 operations>> for framebuffer attachments with a depth/stencil format. 621 * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT specifies the stage of 622 the pipeline where late fragment tests (depth and stencil tests after 623 fragment shading) are performed. 624 This stage also includes <<renderpass-load-store-ops, subpass store 625 operations>> for framebuffer attachments with a depth/stencil format. 626 * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT specifies the stage 627 of the pipeline after blending where the final color values are output 628 from the pipeline. 629 This stage also includes <<renderpass-load-store-ops, subpass load and 630 store operations>>, multisample resolve operations for framebuffer 631 attachments with a color 632ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 633 or depth/stencil 634endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 635 format, and flink:vkCmdClearAttachments. 636 * ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT specifies the execution of a 637 compute shader. 638 * [[synchronization-pipeline-stages-transfer]] 639 ename:VK_PIPELINE_STAGE_TRANSFER_BIT specifies the following commands: 640 ** All <<copies,copy commands>>, including flink:vkCmdCopyQueryPoolResults 641ifndef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 642 ** flink:vkCmdBlitImage 643 ** flink:vkCmdResolveImage 644endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 645ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[] 646 ** flink:vkCmdBlitImage2 and flink:vkCmdBlitImage 647 ** flink:vkCmdResolveImage2 and flink:vkCmdResolveImage 648endif::VK_VERSION_1_3,VK_KHR_copy_commands2[] 649 ** All <<clears,clear commands>>, with the exception of 650 flink:vkCmdClearAttachments 651 * ename:VK_PIPELINE_STAGE_HOST_BIT specifies a pseudo-stage indicating 652 execution on the host of reads/writes of device memory. 653 This stage is not invoked by any commands recorded in a command buffer. 654ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 655 * ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR specifies 656 the execution of 657ifdef::VK_NV_ray_tracing[] 658 flink:vkCmdBuildAccelerationStructureNV, 659 flink:vkCmdCopyAccelerationStructureNV, 660 flink:vkCmdWriteAccelerationStructuresPropertiesNV 661endif::VK_NV_ray_tracing[] 662ifdef::VK_NV_ray_tracing+VK_KHR_acceleration_structure[,] 663ifdef::VK_KHR_acceleration_structure[] 664 flink:vkCmdBuildAccelerationStructuresKHR, 665 flink:vkCmdBuildAccelerationStructuresIndirectKHR, 666 flink:vkCmdCopyAccelerationStructureKHR, 667 flink:vkCmdCopyAccelerationStructureToMemoryKHR, 668 flink:vkCmdCopyMemoryToAccelerationStructureKHR, and 669 flink:vkCmdWriteAccelerationStructuresPropertiesKHR. 670endif::VK_KHR_acceleration_structure[] 671endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 672ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 673 * ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR specifies the 674 execution of the ray tracing shader stages, via 675ifdef::VK_NV_ray_tracing[flink:vkCmdTraceRaysNV] 676ifdef::VK_NV_ray_tracing+VK_KHR_ray_tracing_pipeline[,] 677ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCmdTraceRaysKHR, or flink:vkCmdTraceRaysIndirectKHR] 678endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 679 * ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all 680 graphics pipeline stages, and is equivalent to the logical OR of: 681 ** ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 682ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 683 ** ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT 684 ** ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT 685endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 686 ** ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 687 ** ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT 688 ** ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT 689 ** ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 690 ** ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 691 ** ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 692 ** ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT 693 ** ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 694 ** ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 695ifdef::VK_EXT_conditional_rendering[] 696 ** ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT 697endif::VK_EXT_conditional_rendering[] 698ifdef::VK_EXT_transform_feedback[] 699 ** ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT 700endif::VK_EXT_transform_feedback[] 701ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 702 ** ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 703endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 704ifdef::VK_EXT_fragment_density_map[] 705 ** ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 706endif::VK_EXT_fragment_density_map[] 707 * ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT specifies all operations 708 performed by all commands supported on the queue it is used with. 709ifdef::VK_EXT_conditional_rendering[] 710 * ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT specifies the 711 stage of the pipeline where the predicate of conditional rendering is 712 consumed. 713endif::VK_EXT_conditional_rendering[] 714ifdef::VK_EXT_transform_feedback[] 715 * ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT specifies the stage 716 of the pipeline where vertex attribute output values are written to the 717 transform feedback buffers. 718endif::VK_EXT_transform_feedback[] 719ifdef::VK_NV_device_generated_commands[] 720 * ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV specifies the stage of 721 the pipeline where device-side preprocessing for generated commands via 722 flink:vkCmdPreprocessGeneratedCommandsNV is handled. 723endif::VK_NV_device_generated_commands[] 724ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 725 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 726 specifies the stage of the pipeline where the 727ifdef::VK_KHR_fragment_shading_rate[] 728 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 729 attachment>> 730endif::VK_KHR_fragment_shading_rate[] 731ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] 732ifdef::VK_NV_shading_rate_image[] 733 <<primsrast-shading-rate-image, shading rate image>> 734endif::VK_NV_shading_rate_image[] 735 is read to determine the fragment shading rate for portions of a 736 rasterized primitive. 737endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 738ifdef::VK_EXT_fragment_density_map[] 739 * ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT specifies the 740 stage of the pipeline where the fragment density map is read to 741 <<fragmentdensitymapops,generate the fragment areas>>. 742endif::VK_EXT_fragment_density_map[] 743 * ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT is equivalent to 744 ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT with tlink:VkAccessFlags set to 745 `0` when specified in the second synchronization scope, but specifies no 746 stage of execution when specified in the first scope. 747 * ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT is equivalent to 748 ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT with tlink:VkAccessFlags set to 749 `0` when specified in the first synchronization scope, but specifies no 750 stage of execution when specified in the second scope. 751-- 752 753[open,refpage='VkPipelineStageFlags',desc='Bitmask of VkPipelineStageFlagBits',type='flags'] 754-- 755include::{generated}/api/flags/VkPipelineStageFlags.adoc[] 756 757tname:VkPipelineStageFlags is a bitmask type for setting a mask of zero or 758more elink:VkPipelineStageFlagBits. 759-- 760 761[[synchronization-pipeline-stages-masks]] 762If a synchronization command includes a source stage mask, its first 763<<synchronization-dependencies-scopes, synchronization scope>> only includes 764execution of the pipeline stages specified in that mask, and its first 765<<synchronization-dependencies-access-scopes, access scope>> only includes 766memory accesses performed by pipeline stages specified in that mask. 767 768If a synchronization command includes a destination stage mask, its second 769<<synchronization-dependencies-scopes, synchronization scope>> only includes 770execution of the pipeline stages specified in that mask, and its second 771<<synchronization-dependencies-access-scopes, access scope>> only includes 772memory access performed by pipeline stages specified in that mask. 773 774[NOTE] 775.Note 776==== 777Including a particular pipeline stage in the first 778<<synchronization-dependencies-scopes, synchronization scope>> of a command 779implicitly includes <<synchronization-pipeline-stages-order, logically 780earlier>> pipeline stages in the synchronization scope. 781Similarly, the second <<synchronization-dependencies-scopes, synchronization 782scope>> includes <<synchronization-pipeline-stages-order, logically later>> 783pipeline stages. 784 785However, note that <<synchronization-dependencies-access-scopes, access 786scopes>> are not affected in this way - only the precise stages specified 787are considered part of each access scope. 788==== 789 790Certain pipeline stages are only available on queues that support a 791particular set of operations. 792The following table lists, for each pipeline stage flag, which queue 793capability flag must: be supported by the queue. 794When multiple flags are enumerated in the second column of the table, it 795means that the pipeline stage is supported on the queue if it supports any 796of the listed capability flags. 797For further details on queue capabilities see 798<<devsandqueues-physical-device-enumeration,Physical Device Enumeration>> 799and <<devsandqueues-queues,Queues>>. 800 801[[synchronization-pipeline-stages-supported]] 802.Supported pipeline stage flags 803[cols="70%,30%",options="header"] 804|==== 805|Pipeline stage flag | Required queue capability flag 806ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 807|ename:VK_PIPELINE_STAGE_NONE | None required 808endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 809|ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT | ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT 810|ename:VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT + 811ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 812 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT + 813 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT + 814endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 815 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT + 816 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT + 817 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT + 818 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 819 | ename:VK_QUEUE_GRAPHICS_BIT 820|ename:VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT + 821 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT + 822 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT 823 | ename:VK_QUEUE_GRAPHICS_BIT 824|ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT 825|ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | ename:VK_QUEUE_GRAPHICS_BIT 826|ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT | ename:VK_QUEUE_GRAPHICS_BIT 827|ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT | ename:VK_QUEUE_GRAPHICS_BIT 828|ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT | ename:VK_QUEUE_COMPUTE_BIT 829|ename:VK_PIPELINE_STAGE_HOST_BIT | None required 830|ename:VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT + 831 (ename:VK_PIPELINE_STAGE_TRANSFER_BIT) + 832 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_COPY_BIT + 833 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_BLIT_BIT + 834 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_RESOLVE_BIT + 835 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_CLEAR_BIT + 836 {nbsp} {nbsp} {nbsp} ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 837 | ename:VK_QUEUE_GRAPHICS_BIT, ename:VK_QUEUE_COMPUTE_BIT or ename:VK_QUEUE_TRANSFER_BIT 838ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 839|ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR | ename:VK_QUEUE_COMPUTE_BIT 840endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 841ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 842|ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR | ename:VK_QUEUE_COMPUTE_BIT 843endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 844|ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT | ename:VK_QUEUE_GRAPHICS_BIT 845|ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT | None required 846ifdef::VK_EXT_conditional_rendering[] 847|ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT | ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT 848endif::VK_EXT_conditional_rendering[] 849ifdef::VK_EXT_transform_feedback[] 850|ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT | ename:VK_QUEUE_GRAPHICS_BIT 851endif::VK_EXT_transform_feedback[] 852ifdef::VK_NV_device_generated_commands[] 853|ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV | ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT 854endif::VK_NV_device_generated_commands[] 855ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 856|ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR | ename:VK_QUEUE_GRAPHICS_BIT 857endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 858ifdef::VK_EXT_fragment_density_map[] 859|ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT | ename:VK_QUEUE_GRAPHICS_BIT 860endif::VK_EXT_fragment_density_map[] 861ifdef::VK_HUAWEI_invocation_mask[] 862|ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI | ename:VK_QUEUE_GRAPHICS_BIT 863endif::VK_HUAWEI_invocation_mask[] 864ifdef::VK_KHR_video_decode_queue[] 865|ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR | ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR 866endif::VK_KHR_video_decode_queue[] 867ifdef::VK_KHR_video_encode_queue[] 868|ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR | ename:VK_QUEUE_VIDEO_ENCODE_BIT_KHR 869endif::VK_KHR_video_encode_queue[] 870ifdef::VK_NV_optical_flow[] 871|ename:VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV | ename:VK_QUEUE_OPTICAL_FLOW_BIT_NV 872endif::VK_NV_optical_flow[] 873ifdef::VK_HUAWEI_subpass_shading[] 874|ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI | ename:VK_QUEUE_GRAPHICS_BIT 875endif::VK_HUAWEI_subpass_shading[] 876ifdef::VK_EXT_opacity_micromap[] 877|ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT | ename:VK_QUEUE_COMPUTE_BIT 878endif::VK_EXT_opacity_micromap[] 879|ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT | None required 880|ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT | None required 881|==== 882 883[[synchronization-pipeline-stages-order]] 884Pipeline stages that execute as a result of a command logically complete 885execution in a specific order, such that completion of a logically later 886pipeline stage must: not happen-before completion of a logically earlier 887stage. 888This means that including any stage in the source stage mask for a 889particular synchronization command also implies that any logically earlier 890stages are included in *Scope~1st~* for that command. 891 892Similarly, initiation of a logically earlier pipeline stage must: not 893happen-after initiation of a logically later pipeline stage. 894Including any given stage in the destination stage mask for a particular 895synchronization command also implies that any logically later stages are 896included in *Scope~2nd~* for that command. 897 898[NOTE] 899.Note 900==== 901Implementations may: not support synchronization at every pipeline stage for 902every synchronization operation. 903If a pipeline stage that an implementation does not support synchronization 904for appears in a source stage mask, it may: substitute any logically later 905stage in its place for the first synchronization scope. 906If a pipeline stage that an implementation does not support synchronization 907for appears in a destination stage mask, it may: substitute any logically 908earlier stage in its place for the second synchronization scope. 909 910For example, if an implementation is unable to signal an event immediately 911after vertex shader execution is complete, it may: instead signal the event 912after color attachment output has completed. 913 914If an implementation makes such a substitution, it must: not affect the 915semantics of execution or memory dependencies or image and buffer memory 916barriers. 917==== 918 919[[synchronization-pipeline-stages-types]][[synchronization-pipeline-graphics]] 920<<pipelines-graphics, Graphics pipelines>> are executable on queues 921supporting ename:VK_QUEUE_GRAPHICS_BIT. 922Stages executed by graphics pipelines can: only be specified in commands 923recorded for queues supporting ename:VK_QUEUE_GRAPHICS_BIT. 924 925The graphics 926ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 927primitive 928endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 929pipeline executes the following stages, with the logical ordering of the 930stages matching the order specified here: 931 932 * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 933ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 934 * ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT 935 * ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT 936endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 937ifndef::VK_VERSION_1_3,VK_KHR_synchronization2[] 938 * ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 939endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 940 * ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT 941 * ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT 942 * ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 943 * ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 944ifdef::VK_EXT_transform_feedback[] 945 * ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT 946endif::VK_EXT_transform_feedback[] 947ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 948 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 949endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 950 * ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT 951 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 952 * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 953 * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 954 955ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 956The graphics mesh pipeline executes the following stages, with the logical 957ordering of the stages matching the order specified here: 958 959 * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 960 * ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT 961 * ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT 962ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 963 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 964endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 965 * ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT 966 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 967 * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 968 * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 969endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 970 971For the compute pipeline, the following stages occur in this order: 972 973 * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 974 * ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT 975 976ifdef::VK_HUAWEI_subpass_shading[] 977For the subpass shading pipeline, the following stages occur in this order: 978 979 * ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI 980endif::VK_HUAWEI_subpass_shading[] 981 982ifdef::VK_EXT_fragment_density_map[] 983For graphics pipeline commands executing in a render pass with a fragment 984density map attachment, the following pipeline stage where the fragment 985density map read happens has no particular order relative to the other 986stages, except that it is logically earlier than 987ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT: 988 989 * ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 990 * ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT 991endif::VK_EXT_fragment_density_map[] 992 993ifdef::VK_EXT_conditional_rendering[] 994The conditional rendering stage is formally part of both the graphics, and 995the compute pipeline. 996The pipeline stage where the predicate read happens has unspecified order 997relative to other stages of these pipelines: 998 999 * ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT 1000endif::VK_EXT_conditional_rendering[] 1001 1002For the transfer pipeline, the following stages occur in this order: 1003 1004 * ename:VK_PIPELINE_STAGE_TRANSFER_BIT 1005 1006For host operations, only one pipeline stage occurs, so no order is 1007guaranteed: 1008 1009 * ename:VK_PIPELINE_STAGE_HOST_BIT 1010 1011ifdef::VK_NV_device_generated_commands[] 1012For the command preprocessing pipeline, the following stages occur in this 1013order: 1014 1015 * ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV 1016endif::VK_NV_device_generated_commands[] 1017 1018ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1019For acceleration structure operations, only one pipeline stage occurs, so no 1020order is guaranteed: 1021 1022 * ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1023 1024endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1025 1026ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1027For the ray tracing pipeline, the following stages occur in this order: 1028 1029 * ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 1030 * ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR 1031 1032endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1033 1034 1035[[synchronization-access-types]] 1036=== Access Types 1037 1038Memory in Vulkan can: be accessed from within shader invocations and via 1039some fixed-function stages of the pipeline. 1040The _access type_ is a function of the <<descriptorsets, descriptor type>> 1041used, or how a fixed-function stage accesses memory. 1042 1043[[synchronization-access-masks]] 1044Some synchronization commands take sets of access types as parameters to 1045define the <<synchronization-dependencies-access-scopes, access scopes>> of 1046a memory dependency. 1047If a synchronization command includes a _source access mask_, its first 1048<<synchronization-dependencies-access-scopes, access scope>> only includes 1049accesses via the access types specified in that mask. 1050Similarly, if a synchronization command includes a _destination access 1051mask_, its second <<synchronization-dependencies-access-scopes, access 1052scope>> only includes accesses via the access types specified in that mask. 1053 1054ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1055[open,refpage='VkAccessFlagBits2',desc='Access flags for VkAccessFlags2',type='enums',alias='VkAccessFlagBits2KHR'] 1056-- 1057Bits which can: be set in the pname:srcAccessMask and pname:dstAccessMask 1058members of slink:VkMemoryBarrier2KHR, slink:VkImageMemoryBarrier2KHR, and 1059slink:VkBufferMemoryBarrier2KHR, specifying access behavior, are: 1060 1061include::{generated}/api/enums/VkAccessFlagBits2.adoc[] 1062 1063ifdef::VK_KHR_synchronization2[] 1064or the equivalent 1065 1066include::{generated}/api/enums/VkAccessFlagBits2KHR.adoc[] 1067endif::VK_KHR_synchronization2[] 1068 1069 * ename:VK_ACCESS_2_NONE specifies no accesses. 1070 * ename:VK_ACCESS_2_MEMORY_READ_BIT specifies all read accesses. 1071 It is always valid in any access mask, and is treated as equivalent to 1072 setting all etext:READ access flags that are valid where it is used. 1073 * ename:VK_ACCESS_2_MEMORY_WRITE_BIT specifies all write accesses. 1074 It is always valid in any access mask, and is treated as equivalent to 1075 setting all etext:WRITE access flags that are valid where it is used. 1076 * ename:VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT specifies read access to 1077 command data read from indirect buffers as part of an indirect 1078ifdef::VK_KHR_acceleration_structure[build,] 1079ifdef::VK_KHR_ray_tracing_pipeline[trace,] 1080 drawing or dispatch command. 1081 Such access occurs in the ename:VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT 1082 pipeline stage. 1083 * ename:VK_ACCESS_2_INDEX_READ_BIT specifies read access to an index 1084 buffer as part of an indexed drawing command, bound by 1085 flink:vkCmdBindIndexBuffer. 1086 Such access occurs in the ename:VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT 1087 pipeline stage. 1088 * ename:VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT specifies read access to a 1089 vertex buffer as part of a drawing command, bound by 1090 flink:vkCmdBindVertexBuffers. 1091 Such access occurs in the 1092 ename:VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT pipeline stage. 1093 * ename:VK_ACCESS_2_UNIFORM_READ_BIT specifies read access to a 1094 <<descriptorsets-uniformbuffer, uniform buffer>> in any shader pipeline 1095 stage. 1096 * ename:VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT specifies read access to an 1097 <<renderpass, input attachment>> within a render pass during 1098ifdef::VK_HUAWEI_subpass_shading[] 1099 subpass shading or 1100endif::VK_HUAWEI_subpass_shading[] 1101 fragment shading. 1102 Such access occurs in the 1103ifdef::VK_HUAWEI_subpass_shading[] 1104 ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI or 1105endif::VK_HUAWEI_subpass_shading[] 1106 ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT pipeline stage. 1107 * ename:VK_ACCESS_2_SHADER_SAMPLED_READ_BIT specifies read access to a 1108 <<descriptorsets-uniformtexelbuffer, uniform texel buffer>> or 1109 <<descriptorsets-sampledimage, sampled image>> in any shader pipeline 1110 stage. 1111 * ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT specifies read access to a 1112 <<descriptorsets-storagebuffer, storage buffer>>, 1113ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_buffer_device_address[] 1114 <<descriptorsets-physical-storage-buffer, physical storage buffer>>, 1115endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_buffer_device_address[] 1116 <<descriptorsets-storagetexelbuffer, storage texel buffer>>, or 1117 <<descriptorsets-storageimage, storage image>> in any shader pipeline 1118 stage. 1119ifdef::VK_KHR_ray_tracing_maintenance1+VK_KHR_ray_tracing_pipeline[] 1120 * ename:VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR specifies read 1121 access to a <<shader-binding-table, shader binding table>> in any shader 1122 pipeline stage. 1123endif::VK_KHR_ray_tracing_maintenance1+VK_KHR_ray_tracing_pipeline[] 1124 * ename:VK_ACCESS_2_SHADER_READ_BIT 1125ifndef::VK_KHR_ray_tracing_maintenance1[] 1126ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1127 specifies read access to a <<shader-binding-table, shader binding 1128 table>> in any shader pipeline. 1129 In addition, it 1130endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1131endif::VK_KHR_ray_tracing_maintenance1[] 1132 is equivalent to the logical OR of: 1133 ** ename:VK_ACCESS_2_UNIFORM_READ_BIT 1134 ** ename:VK_ACCESS_2_SHADER_SAMPLED_READ_BIT 1135 ** ename:VK_ACCESS_2_SHADER_STORAGE_READ_BIT 1136ifdef::VK_KHR_ray_tracing_maintenance1+VK_KHR_ray_tracing_pipeline[] 1137 ** ename:VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR 1138endif::VK_KHR_ray_tracing_maintenance1+VK_KHR_ray_tracing_pipeline[] 1139 * ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT specifies write access to a 1140 <<descriptorsets-storagebuffer, storage buffer>>, 1141ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_buffer_device_address[] 1142 <<descriptorsets-physical-storage-buffer, physical storage buffer>>, 1143endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_buffer_device_address[] 1144 <<descriptorsets-storagetexelbuffer, storage texel buffer>>, or 1145 <<descriptorsets-storageimage, storage image>> in any shader pipeline 1146 stage. 1147 * ename:VK_ACCESS_2_SHADER_WRITE_BIT is equivalent to 1148 ename:VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT. 1149 * ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT specifies read access to a 1150 <<renderpass, color attachment>>, such as via <<framebuffer-blending, 1151 blending>>, <<framebuffer-logicop, logic operations>>, or via certain 1152 <<renderpass-load-store-ops, subpass load operations>>. 1153ifdef::VK_EXT_blend_operation_advanced[] 1154 It does not include <<framebuffer-blend-advanced, advanced blend 1155 operations>>. 1156endif::VK_EXT_blend_operation_advanced[] 1157 Such access occurs in the 1158 ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1159 * ename:VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a 1160ifndef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1161 <<renderpass, color or resolve attachment>> 1162endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1163ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1164 <<renderpass, color, resolve, or depth/stencil resolve attachment>> 1165endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1166 during a <<renderpass, render pass>> or via certain 1167 <<renderpass-load-store-ops, subpass load and store operations>>. 1168 Such access occurs in the 1169 ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1170 * ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT specifies read 1171 access to a <<renderpass, depth/stencil attachment>>, via 1172 <<fragops-ds-state, depth or stencil operations>> or via certain 1173 <<renderpass-load-store-ops, subpass load operations>>. 1174 Such access occurs in the 1175 ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT or 1176 ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT pipeline stages. 1177 * ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT specifies write 1178 access to a <<renderpass, depth/stencil attachment>>, via 1179 <<fragops-ds-state, depth or stencil operations>> or via certain 1180 <<renderpass-load-store-ops, subpass load and store operations>>. 1181 Such access occurs in the 1182 ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT or 1183 ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT pipeline stages. 1184 * ename:VK_ACCESS_2_TRANSFER_READ_BIT specifies read access to an image or 1185 buffer in a <<copies, copy>> operation. 1186 Such access occurs in the ename:VK_PIPELINE_STAGE_2_COPY_BIT, 1187 ename:VK_PIPELINE_STAGE_2_BLIT_BIT, or 1188 ename:VK_PIPELINE_STAGE_2_RESOLVE_BIT pipeline stages. 1189 * ename:VK_ACCESS_2_TRANSFER_WRITE_BIT specifies write access to an image 1190 or buffer in a <<clears, clear>> or <<copies, copy>> operation. 1191 Such access occurs in the ename:VK_PIPELINE_STAGE_2_COPY_BIT, 1192 ename:VK_PIPELINE_STAGE_2_BLIT_BIT, ename:VK_PIPELINE_STAGE_2_CLEAR_BIT, 1193 or ename:VK_PIPELINE_STAGE_2_RESOLVE_BIT pipeline stages. 1194 * ename:VK_ACCESS_2_HOST_READ_BIT specifies read access by a host 1195 operation. 1196 Accesses of this type are not performed through a resource, but directly 1197 on memory. 1198 Such access occurs in the ename:VK_PIPELINE_STAGE_2_HOST_BIT pipeline 1199 stage. 1200 * ename:VK_ACCESS_2_HOST_WRITE_BIT specifies write access by a host 1201 operation. 1202 Accesses of this type are not performed through a resource, but directly 1203 on memory. 1204 Such access occurs in the ename:VK_PIPELINE_STAGE_2_HOST_BIT pipeline 1205 stage. 1206ifdef::VK_EXT_conditional_rendering[] 1207 * ename:VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT specifies read 1208 access to a predicate as part of conditional rendering. 1209 Such access occurs in the 1210 ename:VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT pipeline stage. 1211endif::VK_EXT_conditional_rendering[] 1212ifdef::VK_EXT_transform_feedback[] 1213 * ename:VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT specifies write 1214 access to a transform feedback buffer made when transform feedback is 1215 active. 1216 Such access occurs in the 1217 ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1218 * ename:VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT specifies read 1219 access to a transform feedback counter buffer which is read when 1220 flink:vkCmdBeginTransformFeedbackEXT executes. 1221 Such access occurs in the 1222 ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1223 * ename:VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT specifies 1224 write access to a transform feedback counter buffer which is written 1225 when flink:vkCmdEndTransformFeedbackEXT executes. 1226 Such access occurs in the 1227 ename:VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1228endif::VK_EXT_transform_feedback[] 1229ifdef::VK_NV_device_generated_commands[] 1230 * ename:VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV specifies reads from 1231 buffer inputs to flink:vkCmdPreprocessGeneratedCommandsNV. 1232 Such access occurs in the 1233 ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV pipeline stage. 1234 * ename:VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV specifies writes to 1235 the target command buffer preprocess outputs. 1236 Such access occurs in the 1237 ename:VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV pipeline stage. 1238endif::VK_NV_device_generated_commands[] 1239ifdef::VK_EXT_blend_operation_advanced[] 1240 * ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies 1241 read access to <<renderpass, color attachments>>, including 1242 <<framebuffer-blend-advanced,advanced blend operations>>. 1243 Such access occurs in the 1244 ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1245endif::VK_EXT_blend_operation_advanced[] 1246ifdef::VK_HUAWEI_invocation_mask[] 1247 * ename:VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI specifies read access 1248 to a invocation mask image in the 1249 ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI pipeline stage. 1250endif::VK_HUAWEI_invocation_mask[] 1251ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 1252 * ename:VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR specifies read 1253 access to an acceleration structure as part of a trace, build, or copy 1254 command, or to an <<acceleration-structure-scratch, acceleration 1255 structure scratch buffer>> as part of a build command. 1256 Such access occurs in the 1257ifdef::VK_KHR_ray_tracing_pipeline[] 1258 ename:VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR pipeline stage or 1259endif::VK_KHR_ray_tracing_pipeline[] 1260 ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline 1261 stage. 1262 * ename:VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR specifies write 1263 access to an acceleration structure or <<acceleration-structure-scratch, 1264 acceleration structure scratch buffer>> as part of a build or copy 1265 command. 1266 Such access occurs in the 1267 ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline 1268 stage. 1269endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 1270ifdef::VK_EXT_fragment_density_map[] 1271 * ename:VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT specifies read 1272 access to a <<renderpass-fragmentdensitymapattachment, fragment density 1273 map attachment>> during dynamic <<fragmentdensitymapops, fragment 1274 density map operations>>. 1275 Such access occurs in the 1276 ename:VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT pipeline 1277 stage. 1278endif::VK_EXT_fragment_density_map[] 1279ifdef::VK_KHR_fragment_shading_rate[] 1280 * ename:VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR 1281 specifies read access to a fragment shading rate attachment during 1282 rasterization. 1283 Such access occurs in the 1284 ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 1285 pipeline stage. 1286endif::VK_KHR_fragment_shading_rate[] 1287ifdef::VK_NV_shading_rate_image[] 1288 * ename:VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV specifies read access 1289 to a shading rate image during rasterization. 1290 Such access occurs in the 1291 ename:VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV pipeline stage. 1292ifdef::VK_KHR_fragment_shading_rate[] 1293 It is equivalent to 1294 ename:VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR. 1295endif::VK_KHR_fragment_shading_rate[] 1296endif::VK_NV_shading_rate_image[] 1297ifdef::VK_KHR_video_decode_queue[] 1298 * ename:VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR specifies read access to an 1299 image or buffer resource in a <<video-decode-operations, video decode 1300 operation>>. 1301 Such access occurs in the ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR 1302 pipeline stage. 1303 * ename:VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR specifies write access to 1304 an image or buffer resource in a <<video-decode-operations, video decode 1305 operation>>. 1306 Such access occurs in the ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR 1307 pipeline stage. 1308endif::VK_KHR_video_decode_queue[] 1309ifdef::VK_KHR_video_encode_queue[] 1310 * ename:VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR specifies read access to an 1311 image or buffer resource in a <<video-encode-operations, video encode 1312 operation>>. 1313 Such access occurs in the ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR 1314 pipeline stage. 1315 * ename:VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR specifies write access to 1316 an image or buffer resource in a <<video-encode-operations, video encode 1317 operation>>. 1318 Such access occurs in the ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR 1319 pipeline stage. 1320endif::VK_KHR_video_encode_queue[] 1321ifdef::VK_EXT_descriptor_buffer[] 1322 * ename:VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT specifies read access 1323 to a <<descriptorbuffers, descriptor buffer>> in any shader pipeline 1324 stage. 1325endif::VK_EXT_descriptor_buffer[] 1326ifdef::VK_NV_optical_flow[] 1327 * ename:VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV specifies read access to an 1328 image or buffer resource as part of a <<opticalflow-operations, optical 1329 flow operation>>. 1330 Such access occurs in the ename:VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV 1331 pipeline stage. 1332 * ename:VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV specifies write access to an 1333 image or buffer resource as part of a <<opticalflow-operations, optical 1334 flow operation>>. 1335 Such access occurs in the ename:VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV 1336 pipeline stage. 1337endif::VK_NV_optical_flow[] 1338ifdef::VK_EXT_opacity_micromap[] 1339 * ename:VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT specifies write access to a 1340 micromap object. 1341 Such access occurs in the 1342 ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage. 1343 * ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT specifies read access to a 1344 micromap object. 1345 Such access occurs in the 1346 ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT and 1347 ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline 1348 stages. 1349endif::VK_EXT_opacity_micromap[] 1350 1351[NOTE] 1352.Note 1353==== 1354In situations where an application wishes to select all access types for a 1355given set of pipeline stages, ename:VK_ACCESS_2_MEMORY_READ_BIT or 1356ename:VK_ACCESS_2_MEMORY_WRITE_BIT can be used. 1357This is particularly useful when specifying stages that only have a single 1358access type. 1359==== 1360 1361[NOTE] 1362.Note 1363==== 1364The tname:VkAccessFlags2 bitmask goes beyond the 31 individual bit flags 1365allowable within a C99 enum, which is how elink:VkAccessFlagBits is defined. 1366The first 31 values are common to both, and are interchangeable. 1367==== 1368-- 1369 1370[open,refpage='VkAccessFlags2',desc='64-bit mask of access flags',type='flags',alias='VkAccessFlags2KHR'] 1371-- 1372tname:VkAccessFlags2 is a bitmask type for setting a mask of zero or more 1373elink:VkAccessFlagBits2: 1374 1375include::{generated}/api/flags/VkAccessFlags2.adoc[] 1376 1377ifdef::VK_KHR_synchronization2[] 1378or the equivalent 1379 1380include::{generated}/api/flags/VkAccessFlags2KHR.adoc[] 1381endif::VK_KHR_synchronization2[] 1382-- 1383endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1384 1385[open,refpage='VkAccessFlagBits',desc='Bitmask specifying memory access types that will participate in a memory dependency',type='enums'] 1386-- 1387Bits which can: be set in the pname:srcAccessMask and pname:dstAccessMask 1388members of slink:VkSubpassDependency, 1389ifdef::VK_KHR_synchronization2[slink:VkSubpassDependency2,] 1390slink:VkMemoryBarrier, slink:VkBufferMemoryBarrier, and 1391slink:VkImageMemoryBarrier, specifying access behavior, are: 1392 1393include::{generated}/api/enums/VkAccessFlagBits.adoc[] 1394 1395ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1396These values all have the same meaning as the equivalently named values for 1397tlink:VkAccessFlags2. 1398 1399 * ename:VK_ACCESS_NONE specifies no accesses. 1400endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1401 * ename:VK_ACCESS_MEMORY_READ_BIT specifies all read accesses. 1402 It is always valid in any access mask, and is treated as equivalent to 1403 setting all etext:READ access flags that are valid where it is used. 1404 * ename:VK_ACCESS_MEMORY_WRITE_BIT specifies all write accesses. 1405 It is always valid in any access mask, and is treated as equivalent to 1406 setting all etext:WRITE access flags that are valid where it is used. 1407 * ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT specifies read access to 1408 indirect command data read as part of an indirect 1409ifdef::VK_KHR_acceleration_structure[build,] 1410ifdef::VK_KHR_ray_tracing_pipeline[trace,] 1411 drawing or dispatching command. 1412 Such access occurs in the ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 1413 pipeline stage. 1414 * ename:VK_ACCESS_INDEX_READ_BIT specifies read access to an index buffer 1415 as part of an indexed drawing command, bound by 1416 flink:vkCmdBindIndexBuffer. 1417 Such access occurs in the ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 1418 pipeline stage. 1419 * ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT specifies read access to a 1420 vertex buffer as part of a drawing command, bound by 1421 flink:vkCmdBindVertexBuffers. 1422 Such access occurs in the ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 1423 pipeline stage. 1424 * ename:VK_ACCESS_UNIFORM_READ_BIT specifies read access to a 1425 <<descriptorsets-uniformbuffer, uniform buffer>> in any shader pipeline 1426 stage. 1427 * ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT specifies read access to an 1428 <<renderpass, input attachment>> within a render pass during 1429ifdef::VK_HUAWEI_subpass_shading[] 1430 subpass shading or 1431endif::VK_HUAWEI_subpass_shading[] 1432 fragment shading. 1433 Such access occurs in the 1434ifdef::VK_HUAWEI_subpass_shading[] 1435 ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI or 1436endif::VK_HUAWEI_subpass_shading[] 1437 ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage. 1438 * ename:VK_ACCESS_SHADER_READ_BIT specifies read access to a 1439 <<descriptorsets-uniformbuffer, uniform buffer>>, 1440 <<descriptorsets-uniformtexelbuffer, uniform texel buffer>>, 1441 <<descriptorsets-sampledimage, sampled image>>, 1442 <<descriptorsets-storagebuffer, storage buffer>>, 1443ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1444 <<descriptorsets-physical-storage-buffer, physical storage buffer>>, 1445endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1446ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1447 <<shader-binding-table, shader binding table>>, 1448endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1449 <<descriptorsets-storagetexelbuffer, storage texel buffer>>, or 1450 <<descriptorsets-storageimage, storage image>> in any shader pipeline 1451 stage. 1452 * ename:VK_ACCESS_SHADER_WRITE_BIT specifies write access to a 1453 <<descriptorsets-storagebuffer, storage buffer>>, 1454ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1455 <<descriptorsets-physical-storage-buffer, physical storage buffer>>, 1456endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1457 <<descriptorsets-storagetexelbuffer, storage texel buffer>>, or 1458 <<descriptorsets-storageimage, storage image>> in any shader pipeline 1459 stage. 1460 * ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT specifies read access to a 1461 <<renderpass, color attachment>>, such as via <<framebuffer-blending, 1462 blending>>, <<framebuffer-logicop, logic operations>>, or via certain 1463 <<renderpass-load-store-ops, subpass load operations>>. 1464ifdef::VK_EXT_blend_operation_advanced[] 1465 It does not include <<framebuffer-blend-advanced, advanced blend 1466 operations>>. 1467 Such access occurs in the 1468 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1469endif::VK_EXT_blend_operation_advanced[] 1470 * ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a 1471ifndef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1472 <<renderpass, color or resolve attachment>> 1473endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1474ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1475 <<renderpass, color, resolve, or depth/stencil resolve attachment>> 1476endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1477 during a <<renderpass, render pass>> or via certain 1478 <<renderpass-load-store-ops, subpass load and store operations>>. 1479 Such access occurs in the 1480 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1481 * ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT specifies read access 1482 to a <<renderpass, depth/stencil attachment>>, via <<fragops-ds-state, 1483 depth or stencil operations>> or via certain 1484 <<renderpass-load-store-ops, subpass load operations>>. 1485 Such access occurs in the 1486 ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT or 1487 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages. 1488 * ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT specifies write 1489 access to a <<renderpass, depth/stencil attachment>>, via 1490 <<fragops-ds-state, depth or stencil operations>> or via certain 1491 <<renderpass-load-store-ops, subpass load and store operations>>. 1492 Such access occurs in the 1493 ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT or 1494 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages. 1495 * ename:VK_ACCESS_TRANSFER_READ_BIT specifies read access to an image or 1496 buffer in a <<copies, copy>> operation. 1497ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1498 Such access occurs in the ename:VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT 1499 pipeline stage. 1500endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1501 * ename:VK_ACCESS_TRANSFER_WRITE_BIT specifies write access to an image or 1502 buffer in a <<clears, clear>> or <<copies, copy>> operation. 1503ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1504 Such access occurs in the ename:VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT 1505 pipeline stage. 1506endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1507 * ename:VK_ACCESS_HOST_READ_BIT specifies read access by a host operation. 1508 Accesses of this type are not performed through a resource, but directly 1509 on memory. 1510 Such access occurs in the ename:VK_PIPELINE_STAGE_HOST_BIT pipeline 1511 stage. 1512 * ename:VK_ACCESS_HOST_WRITE_BIT specifies write access by a host 1513 operation. 1514 Accesses of this type are not performed through a resource, but directly 1515 on memory. 1516 Such access occurs in the ename:VK_PIPELINE_STAGE_HOST_BIT pipeline 1517 stage. 1518ifdef::VK_EXT_conditional_rendering[] 1519 * ename:VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT specifies read access 1520 to a predicate as part of conditional rendering. 1521 Such access occurs in the 1522 ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT pipeline stage. 1523endif::VK_EXT_conditional_rendering[] 1524ifdef::VK_EXT_transform_feedback[] 1525 * ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT specifies write access 1526 to a transform feedback buffer made when transform feedback is active. 1527 Such access occurs in the 1528 ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1529 * ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT specifies read 1530 access to a transform feedback counter buffer which is read when 1531 fname:vkCmdBeginTransformFeedbackEXT executes. 1532 Such access occurs in the 1533 ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1534 * ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT specifies write 1535 access to a transform feedback counter buffer which is written when 1536 fname:vkCmdEndTransformFeedbackEXT executes. 1537 Such access occurs in the 1538 ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT pipeline stage. 1539endif::VK_EXT_transform_feedback[] 1540ifdef::VK_NV_device_generated_commands[] 1541 * ename:VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV specifies reads from 1542 buffer inputs to flink:vkCmdPreprocessGeneratedCommandsNV. 1543 Such access occurs in the 1544 ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV pipeline stage. 1545 * ename:VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV specifies writes to the 1546 target command buffer:VkBuffer preprocess outputs in 1547 flink:vkCmdPreprocessGeneratedCommandsNV. 1548 Such access occurs in the 1549 ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV pipeline stage. 1550endif::VK_NV_device_generated_commands[] 1551ifdef::VK_EXT_blend_operation_advanced[] 1552 * ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT specifies read 1553 access to <<renderpass, color attachments>>, including 1554 <<framebuffer-blend-advanced,advanced blend operations>>. 1555 Such access occurs in the 1556 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1557endif::VK_EXT_blend_operation_advanced[] 1558ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 1559ifdef::VK_HUAWEI_invocation_mask[] 1560 * ename:VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI specifies read access 1561 to a invocation mask image in the 1562 ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI pipeline stage. 1563endif::VK_HUAWEI_invocation_mask[] 1564 * ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR specifies read 1565 access to an acceleration structure as part of a trace, build, or copy 1566 command, or to an <<acceleration-structure-scratch, acceleration 1567 structure scratch buffer>> as part of a build command. 1568 Such access occurs in the 1569ifdef::VK_KHR_ray_tracing_pipeline[] 1570 ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR pipeline stage or 1571endif::VK_KHR_ray_tracing_pipeline[] 1572 ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline 1573 stage. 1574 * ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR specifies write 1575 access to an acceleration structure or <<acceleration-structure-scratch, 1576 acceleration structure scratch buffer>> as part of a build or copy 1577 command. 1578 Such access occurs in the 1579 ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline 1580 stage. 1581endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 1582ifdef::VK_EXT_fragment_density_map[] 1583 * ename:VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT specifies read access 1584 to a <<renderpass-fragmentdensitymapattachment, fragment density map 1585 attachment>> during dynamic <<fragmentdensitymapops, fragment density 1586 map operations>> Such access occurs in the 1587 ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT pipeline stage. 1588endif::VK_EXT_fragment_density_map[] 1589ifdef::VK_KHR_fragment_shading_rate[] 1590 * ename:VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR specifies 1591 read access to a fragment shading rate attachment during rasterization. 1592 Such access occurs in the 1593 ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 1594 pipeline stage. 1595endif::VK_KHR_fragment_shading_rate[] 1596ifdef::VK_NV_shading_rate_image[] 1597 * ename:VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV specifies read access to 1598 a shading rate image during rasterization. 1599 Such access occurs in the 1600 ename:VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV pipeline stage. 1601ifdef::VK_KHR_fragment_shading_rate[] 1602 It is equivalent to 1603 ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR. 1604endif::VK_KHR_fragment_shading_rate[] 1605endif::VK_NV_shading_rate_image[] 1606 1607Certain access types are only performed by a subset of pipeline stages. 1608Any synchronization command that takes both stage masks and access masks 1609uses both to define the <<synchronization-dependencies-access-scopes, access 1610scopes>> - only the specified access types performed by the specified stages 1611are included in the access scope. 1612An application must: not specify an access flag in a synchronization command 1613if it does not include a pipeline stage in the corresponding stage mask that 1614is able to perform accesses of that type. 1615The following table lists, for each access flag, which pipeline stages can: 1616perform that type of access. 1617 1618[[synchronization-access-types-supported]] 1619.Supported access types 1620[cols="50,50",options="header"] 1621|==== 1622|Access flag | Supported pipeline stages 1623|ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT | ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 1624ifdef::VK_KHR_acceleration_structure[] 1625, ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1626endif::VK_KHR_acceleration_structure[] 1627|ename:VK_ACCESS_INDEX_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 1628|ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT 1629 1630|ename:VK_ACCESS_UNIFORM_READ_BIT | 1631ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1632 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, 1633endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1634ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1635 ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, 1636endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1637 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT 1638 1639|ename:VK_ACCESS_SHADER_READ_BIT | 1640ifdef::VK_KHR_acceleration_structure[] 1641 ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR, 1642endif::VK_KHR_acceleration_structure[] 1643ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1644 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, 1645endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1646ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1647 ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, 1648endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1649ifdef::VK_EXT_opacity_micromap[] 1650 ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT, 1651endif::VK_EXT_opacity_micromap[] 1652 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT 1653 1654|ename:VK_ACCESS_SHADER_WRITE_BIT | 1655ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1656 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, 1657endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1658ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1659 ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, 1660endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 1661 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT 1662 1663|ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | 1664ifdef::VK_HUAWEI_subpass_shading[] 1665 ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI, or 1666endif::VK_HUAWEI_subpass_shading[] 1667 ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 1668|ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 1669|ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 1670|ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT, or ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 1671|ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT | ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT, or ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 1672|ename:VK_ACCESS_TRANSFER_READ_BIT | ename:VK_PIPELINE_STAGE_TRANSFER_BIT 1673ifdef::VK_KHR_acceleration_structure[or ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR] 1674|ename:VK_ACCESS_TRANSFER_WRITE_BIT | ename:VK_PIPELINE_STAGE_TRANSFER_BIT 1675ifdef::VK_KHR_acceleration_structure[or ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR] 1676|ename:VK_ACCESS_HOST_READ_BIT | ename:VK_PIPELINE_STAGE_HOST_BIT 1677|ename:VK_ACCESS_HOST_WRITE_BIT | ename:VK_PIPELINE_STAGE_HOST_BIT 1678|ename:VK_ACCESS_MEMORY_READ_BIT | Any 1679|ename:VK_ACCESS_MEMORY_WRITE_BIT | Any 1680ifdef::VK_EXT_blend_operation_advanced[] 1681|ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT | ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 1682endif::VK_EXT_blend_operation_advanced[] 1683ifdef::VK_NV_device_generated_commands[] 1684|ename:VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV | ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV 1685|ename:VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV | ename:VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV 1686endif::VK_NV_device_generated_commands[] 1687ifdef::VK_EXT_conditional_rendering[] 1688|ename:VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT | ename:VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT 1689endif::VK_EXT_conditional_rendering[] 1690ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1691|ename:VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR | ename:VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 1692endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1693ifdef::VK_HUAWEI_invocation_mask[] 1694|ename:VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI | ename:VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI 1695endif::VK_HUAWEI_invocation_mask[] 1696ifdef::VK_EXT_transform_feedback[] 1697|ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT | ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT 1698|ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT | ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT 1699|ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT | ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT, ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT 1700endif::VK_EXT_transform_feedback[] 1701ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1702|ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | 1703ifdef::VK_KHR_ray_query[] 1704ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1705 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT, ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT, 1706endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[] 1707 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT, 1708endif::VK_KHR_ray_query[] 1709ifdef::VK_KHR_ray_tracing_pipeline[] 1710ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR, 1711endif::VK_KHR_ray_tracing_pipeline[] 1712ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 1713 or 1714endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 1715ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1716|ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR | ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1717endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1718ifdef::VK_EXT_fragment_density_map[] 1719|ename:VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT | ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 1720endif::VK_EXT_fragment_density_map[] 1721ifdef::VK_KHR_video_decode_queue[] 1722|ename:VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR | ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR 1723|ename:VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR | ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR 1724endif::VK_KHR_video_decode_queue[] 1725ifdef::VK_KHR_video_encode_queue[] 1726|ename:VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR | ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR 1727|ename:VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR | ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR 1728endif::VK_KHR_video_encode_queue[] 1729|==== 1730-- 1731 1732[open,refpage='VkAccessFlags',desc='Bitmask of VkAccessFlagBits',type='flags'] 1733-- 1734include::{generated}/api/flags/VkAccessFlags.adoc[] 1735 1736tname:VkAccessFlags is a bitmask type for setting a mask of zero or more 1737elink:VkAccessFlagBits. 1738-- 1739 1740 1741[[synchronization-host-access-types]] 1742If a memory object does not have the 1743ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property, then 1744flink:vkFlushMappedMemoryRanges must: be called in order to guarantee that 1745writes to the memory object from the host are made available to the host 1746domain, where they can: be further made available to the device domain via a 1747domain operation. 1748Similarly, flink:vkInvalidateMappedMemoryRanges must: be called to guarantee 1749that writes which are available to the host domain are made visible to host 1750operations. 1751 1752If the memory object does have the 1753ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property flag, writes to the 1754memory object from the host are automatically made available to the host 1755domain. 1756Similarly, writes made available to the host domain are automatically made 1757visible to the host. 1758 1759[NOTE] 1760.Note 1761==== 1762<<devsandqueues-submission, Queue submission commands>> automatically 1763perform a <<synchronization-submission-host-writes,domain operation from 1764host to device>> for all writes performed before the command executes, so in 1765most cases an explicit memory barrier is not needed for this case. 1766In the few circumstances where a submit does not occur between the host 1767write and the device read access, writes can: be made available by using an 1768explicit memory barrier. 1769==== 1770 1771 1772[[synchronization-framebuffer-regions]] 1773=== Framebuffer Region Dependencies 1774 1775<<synchronization-pipeline-stages, Pipeline stages>> that operate on, or 1776with respect to, the framebuffer are collectively the _framebuffer-space_ 1777pipeline stages. 1778These stages are: 1779 1780 * ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 1781 * ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT 1782 * ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT 1783 * ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 1784 1785For these pipeline stages, an execution or memory dependency from the first 1786set of operations to the second set can: either be a single 1787_framebuffer-global_ dependency, or split into multiple _framebuffer-local_ 1788dependencies. 1789A dependency with non-framebuffer-space pipeline stages is neither 1790framebuffer-global nor framebuffer-local. 1791 1792ifndef::VK_QCOM_render_pass_shader_resolve,VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1793A _framebuffer region_ is a set of sample (x, y, layer, sample) coordinates 1794that is a subset of the entire framebuffer. 1795endif::VK_QCOM_render_pass_shader_resolve,VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1796ifdef::VK_QCOM_render_pass_shader_resolve,VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1797A _framebuffer region_ is a subset of the entire framebuffer, and can: 1798either be: 1799 1800 * A _sample region_, which is set of sample (x, y, layer, sample) 1801 coordinates that is a subset of the entire framebuffer, or 1802 * A _fragment region_, which is a set of fragment (x, y, layer) 1803 coordinates that is a subset of the entire framebuffer. 1804endif::VK_QCOM_render_pass_shader_resolve,VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1805 1806Both <<synchronization-dependencies-scopes, synchronization scopes>> of a 1807framebuffer-local dependency include only the operations performed within 1808corresponding framebuffer regions (as defined below). 1809No ordering guarantees are made between different framebuffer regions for a 1810framebuffer-local dependency. 1811 1812Both <<synchronization-dependencies-scopes, synchronization scopes>> of a 1813framebuffer-global dependency include operations on all framebuffer-regions. 1814 1815If the first synchronization scope includes operations on pixels/fragments 1816with N samples and the second synchronization scope includes operations on 1817pixels/fragments with M samples, where N does not equal M, then a 1818framebuffer region containing all samples at a given (x, y, layer) 1819coordinate in the first synchronization scope corresponds to a region 1820containing all samples at the same coordinate in the second synchronization 1821scope. 1822ifndef::VK_QCOM_render_pass_shader_resolve[] 1823In other words, it is a pixel granularity dependency. 1824endif::VK_QCOM_render_pass_shader_resolve[] 1825ifdef::VK_QCOM_render_pass_shader_resolve[] 1826In other words, the framebuffer region is a fragment region and it is a 1827pixel granularity dependency. 1828endif::VK_QCOM_render_pass_shader_resolve[] 1829If N equals M, 1830ifdef::VK_QCOM_render_pass_shader_resolve[] 1831and if the sname:VkSubpassDescription::pname:flags does not specify the 1832ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM flag, 1833endif::VK_QCOM_render_pass_shader_resolve[] 1834then a framebuffer region containing a single (x, y, layer, sample) 1835coordinate in the first synchronization scope corresponds to a region 1836containing the same sample at the same coordinate in the second 1837synchronization scope. 1838ifndef::VK_QCOM_render_pass_shader_resolve[] 1839In other words, it is a sample granularity dependency. 1840endif::VK_QCOM_render_pass_shader_resolve[] 1841ifdef::VK_QCOM_render_pass_shader_resolve[] 1842In other words, the framebuffer region is a sample region and it is a sample 1843granularity dependency. 1844endif::VK_QCOM_render_pass_shader_resolve[] 1845 1846ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1847If the pipeline performing the operation was created with 1848ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT, 1849ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT, 1850or 1851ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT, 1852the framebuffer region is a fragment region and it is a pixel granularity 1853dependency. 1854endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1855 1856[NOTE] 1857.Note 1858==== 1859Since fragment shader invocations are not specified to run in any particular 1860groupings, the size of a framebuffer region is implementation-dependent, not 1861known to the application, and must: be assumed to be no larger than 1862specified above. 1863==== 1864 1865[NOTE] 1866.Note 1867==== 1868Practically, the pixel vs. sample granularity dependency means that if an 1869input attachment has a different number of samples than the pipeline's 1870pname:rasterizationSamples, then a fragment can: access any sample in the 1871input attachment's pixel even if it only uses framebuffer-local 1872dependencies. 1873If the input attachment has the same number of samples, then the fragment 1874can: only access the covered samples in its input code:SampleMask (i.e. the 1875fragment operations happen-after a framebuffer-local dependency for each 1876sample the fragment covers). 1877To access samples that are not covered, 1878ifdef::VK_QCOM_render_pass_shader_resolve[] 1879either the sname:VkSubpassDescription::pname:flags 1880ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM flag is required, or 1881endif::VK_QCOM_render_pass_shader_resolve[] 1882a framebuffer-global dependency is required. 1883==== 1884 1885If a synchronization command includes a pname:dependencyFlags parameter, and 1886specifies the ename:VK_DEPENDENCY_BY_REGION_BIT flag, then it defines 1887framebuffer-local dependencies for the framebuffer-space pipeline stages in 1888that synchronization command, for all framebuffer regions. 1889If no pname:dependencyFlags parameter is included, or the 1890ename:VK_DEPENDENCY_BY_REGION_BIT flag is not specified, then a 1891framebuffer-global dependency is specified for those stages. 1892The ename:VK_DEPENDENCY_BY_REGION_BIT flag does not affect the dependencies 1893between non-framebuffer-space pipeline stages, nor does it affect the 1894dependencies between framebuffer-space and non-framebuffer-space pipeline 1895stages. 1896 1897[NOTE] 1898.Note 1899==== 1900Framebuffer-local dependencies are more efficient for most architectures; 1901particularly tile-based architectures - which can keep framebuffer-regions 1902entirely in on-chip registers and thus avoid external bandwidth across such 1903a dependency. 1904Including a framebuffer-global dependency in your rendering will usually 1905force all implementations to flush data to memory, or to a higher level 1906cache, breaking any potential locality optimizations. 1907==== 1908 1909 1910ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1911[[synchronization-view-local-dependencies]] 1912=== View-Local Dependencies 1913 1914In a render pass instance that has <<renderpass-multiview,multiview>> 1915enabled, dependencies can: be either view-local or view-global. 1916 1917A view-local dependency only includes operations from a single 1918<<renderpass-multiview-view-local,source view>> from the source subpass in 1919the first synchronization scope, and only includes operations from a single 1920<<renderpass-multiview-view-local,destination view>> from the destination 1921subpass in the second synchronization scope. 1922A view-global dependency includes all views in the view mask of the source 1923and destination subpasses in the corresponding synchronization scopes. 1924 1925If a synchronization command includes a pname:dependencyFlags parameter and 1926specifies the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT flag, then it defines 1927view-local dependencies for that synchronization command, for all views. 1928If no pname:dependencyFlags parameter is included or the 1929ename:VK_DEPENDENCY_VIEW_LOCAL_BIT flag is not specified, then a view-global 1930dependency is specified. 1931endif::VK_VERSION_1_1,VK_KHR_multiview[] 1932 1933 1934ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1935[[synchronization-device-local-dependencies]] 1936=== Device-Local Dependencies 1937 1938Dependencies can: be either device-local or non-device-local. 1939A device-local dependency acts as multiple separate dependencies, one for 1940each physical device that executes the synchronization command, where each 1941dependency only includes operations from that physical device in both 1942synchronization scopes. 1943A non-device-local dependency is a single dependency where both 1944synchronization scopes include operations from all physical devices that 1945participate in the synchronization command. 1946For subpass dependencies, all physical devices in the 1947slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask participate in the 1948dependency, and for pipeline barriers all physical devices that are set in 1949the command buffer's current device mask participate in the dependency. 1950 1951If a synchronization command includes a pname:dependencyFlags parameter and 1952specifies the ename:VK_DEPENDENCY_DEVICE_GROUP_BIT flag, then it defines a 1953non-device-local dependency for that synchronization command. 1954If no pname:dependencyFlags parameter is included or the 1955ename:VK_DEPENDENCY_DEVICE_GROUP_BIT flag is not specified, then it defines 1956device-local dependencies for that synchronization command, for all 1957participating physical devices. 1958 1959Semaphore and event dependencies are device-local and only execute on the 1960one physical device that performs the dependency. 1961endif::VK_VERSION_1_1,VK_KHR_device_group[] 1962 1963 1964[[synchronization-implicit]] 1965== Implicit Synchronization Guarantees 1966 1967A small number of implicit ordering guarantees are provided by Vulkan, 1968ensuring that the order in which commands are submitted is meaningful, and 1969avoiding unnecessary complexity in common operations. 1970 1971[[synchronization-submission-order]] 1972_Submission order_ is a fundamental ordering in Vulkan, giving meaning to 1973the order in which <<fundamentals-queueoperation-command-types, action and 1974synchronization commands>> are recorded and submitted to a single queue. 1975Explicit and implicit ordering guarantees between commands in Vulkan all 1976work on the premise that this ordering is meaningful. 1977This order does not itself define any execution or memory dependencies; 1978synchronization commands and other orderings within the API use this 1979ordering to define their scopes. 1980 1981Submission order for any given set of commands is based on the order in 1982which they were recorded to command buffers and then submitted. 1983This order is determined as follows: 1984 1985 . The initial order is determined by the order in which 1986 flink:vkQueueSubmit 1987ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1988 and flink:vkQueueSubmit2 1989endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1990 commands are executed on the host, for a single queue, from first to 1991 last. 1992 . The order in which slink:VkSubmitInfo structures are specified in the 1993 pname:pSubmits parameter of flink:vkQueueSubmit, 1994ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1995 or in which slink:VkSubmitInfo2 structures are specified in the 1996 pname:pSubmits parameter of flink:vkQueueSubmit2, 1997endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1998 from lowest index to highest. 1999 . The order in which command buffers are specified in the 2000 pname:pCommandBuffers member of slink:VkSubmitInfo 2001ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2002 or slink:VkSubmitInfo2 2003endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2004 from lowest index to highest. 2005 . The order in which commands were recorded to a command buffer on the 2006 host, from first to last: 2007 ** For commands recorded outside a render pass, this includes all other 2008 commands recorded outside a render pass, including 2009 flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands; it 2010 does not directly include commands inside a render pass. 2011 ** For commands recorded inside a render pass, this includes all other 2012 commands recorded inside the same subpass, including the 2013 flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that 2014 delimit the same render pass instance; it does not include commands 2015 recorded to other subpasses. 2016<<fundamentals-queueoperation-command-types, State commands>> do not execute 2017any operations on the device, instead they set the state of the command 2018buffer when they execute on the host, in the order that they are recorded. 2019<<fundamentals-queueoperation-command-types, Action commands>> consume the 2020current state of the command buffer when they are recorded, and will execute 2021state changes on the device as required to match the recorded state. 2022 2023<<drawing-primitive-order, The order of primitives passing through the 2024graphics pipeline>> and 2025<<synchronization-image-barrier-layout-transition-order, image layout 2026transitions as part of an image memory barrier>> provide additional 2027guarantees based on submission order. 2028 2029Execution of <<synchronization-pipeline-stages-order, pipeline stages>> 2030within a given command also has a loose ordering, dependent only on a single 2031command. 2032 2033[[synchronization-signal-operation-order]] 2034_Signal operation order_ is a fundamental ordering in Vulkan, giving meaning 2035to the order in which semaphore and fence signal operations occur when 2036submitted to a single queue. 2037The signal operation order for queue operations is determined as follows: 2038 2039 . The initial order is determined by the order in which 2040 flink:vkQueueSubmit 2041ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2042 and flink:vkQueueSubmit2 2043endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2044 commands are executed on the host, for a single queue, from first to 2045 last. 2046 . The order in which slink:VkSubmitInfo structures are specified in the 2047 pname:pSubmits parameter of flink:vkQueueSubmit, 2048ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2049 or in which slink:VkSubmitInfo2 structures are specified in the 2050 pname:pSubmits parameter of flink:vkQueueSubmit2, 2051endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2052 from lowest index to highest. 2053 . The fence signal operation defined by the pname:fence parameter of a 2054 flink:vkQueueSubmit, 2055ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2056 flink:vkQueueSubmit2, 2057endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2058 or flink:vkQueueBindSparse command is ordered after all semaphore signal 2059 operations defined by that command. 2060 2061Semaphore signal operations defined by a single slink:VkSubmitInfo, 2062ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2063slink:VkSubmitInfo2, 2064endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2065or slink:VkBindSparseInfo structure are unordered with respect to other 2066semaphore signal operations defined within the same structure. 2067 2068ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2069The flink:vkSignalSemaphore command does not execute on a queue but instead 2070performs the signal operation from the host. 2071The semaphore signal operation defined by executing a 2072flink:vkSignalSemaphore command happens-after the flink:vkSignalSemaphore 2073command is invoked and happens-before the command returns. 2074 2075[NOTE] 2076.Note 2077==== 2078When signaling timeline semaphores, it is the responsibility of the 2079application to ensure that they are ordered such that the semaphore value is 2080strictly increasing. 2081Because the first synchronization scope for a semaphore signal operation 2082contains all semaphore signal operations which occur earlier in submission 2083order, all semaphore signal operations contained in any given batch are 2084guaranteed to happen-after all semaphore signal operations contained in any 2085previous batches. 2086However, no ordering guarantee is provided between the semaphore signal 2087operations defined within a single batch. 2088This, combined with the requirement that timeline semaphore values strictly 2089increase, means that it is invalid to signal the same timeline semaphore 2090twice within a single batch. 2091 2092If an application wishes to ensure that some semaphore signal operation 2093happens-after some other semaphore signal operation, it can submit a 2094separate batch containing only semaphore signal operations, which will 2095happen-after the semaphore signal operations in any earlier batches. 2096 2097When signaling a semaphore from the host, the only ordering guarantee is 2098that the signal operation happens-after when flink:vkSignalSemaphore is 2099called and happens-before it returns. 2100Therefore, it is invalid to call fname:vkSignalSemaphore while there are any 2101outstanding signal operations on that semaphore from any queue submissions 2102unless those queue submissions have some dependency which ensures that they 2103happen-after the host signal operation. 2104One example of this would be if the pending signal operation is, itself, 2105waiting on the same semaphore at a lower value and the call to 2106fname:vkSignalSemaphore signals that lower value. 2107Furthermore, if there are two or more processes or threads signaling the 2108same timeline semaphore from the host, the application must ensure that the 2109fname:vkSignalSemaphore with the lower semaphore value returns before 2110fname:vkSignalSemaphore is called with the higher value. 2111==== 2112endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2113 2114 2115[[synchronization-fences]] 2116== Fences 2117 2118[open,refpage='VkFence',desc='Opaque handle to a fence object',type='handles'] 2119-- 2120Fences are a synchronization primitive that can: be used to insert a 2121dependency from a queue to the host. 2122Fences have two states - signaled and unsignaled. 2123A fence can: be signaled as part of the execution of a 2124<<devsandqueues-submission, queue submission>> command. 2125Fences can: be unsignaled on the host with flink:vkResetFences. 2126Fences can: be waited on by the host with the flink:vkWaitForFences command, 2127and the current state can: be queried with flink:vkGetFenceStatus. 2128 2129ifdef::VK_VERSION_1_1,VK_KHR_external_fence[] 2130[[synchronization-fences-payloads]] 2131The internal data of a fence may: include a reference to any resources and 2132pending work associated with signal or unsignal operations performed on that 2133fence object, collectively referred to as the fence's _payload_. 2134Mechanisms to import and export that internal data to and from fences are 2135provided <<VkExportFenceCreateInfo, below>>. 2136These mechanisms indirectly enable applications to share fence state between 2137two or more fences and other synchronization primitives across process and 2138API boundaries. 2139 2140endif::VK_VERSION_1_1,VK_KHR_external_fence[] 2141 2142Fences are represented by sname:VkFence handles: 2143 2144include::{generated}/api/handles/VkFence.adoc[] 2145-- 2146 2147[open,refpage='vkCreateFence',desc='Create a new fence object',type='protos'] 2148-- 2149To create a fence, call: 2150 2151include::{generated}/api/protos/vkCreateFence.adoc[] 2152 2153 * pname:device is the logical device that creates the fence. 2154 * pname:pCreateInfo is a pointer to a slink:VkFenceCreateInfo structure 2155 containing information about how the fence is to be created. 2156 * pname:pAllocator controls host memory allocation as described in the 2157 <<memory-allocation, Memory Allocation>> chapter. 2158 * pname:pFence is a pointer to a handle in which the resulting fence 2159 object is returned. 2160 2161include::{generated}/validity/protos/vkCreateFence.adoc[] 2162-- 2163 2164[open,refpage='VkFenceCreateInfo',desc='Structure specifying parameters of a newly created fence',type='structs'] 2165-- 2166The sname:VkFenceCreateInfo structure is defined as: 2167 2168include::{generated}/api/structs/VkFenceCreateInfo.adoc[] 2169 2170 * pname:sType is the type of this structure. 2171 * pname:pNext is `NULL` or a pointer to a structure extending this 2172 structure. 2173 * pname:flags is a bitmask of elink:VkFenceCreateFlagBits specifying the 2174 initial state and behavior of the fence. 2175 2176include::{generated}/validity/structs/VkFenceCreateInfo.adoc[] 2177-- 2178 2179[open,refpage='VkFenceCreateFlagBits',desc='Bitmask specifying initial state and behavior of a fence',type='enums'] 2180-- 2181include::{generated}/api/enums/VkFenceCreateFlagBits.adoc[] 2182 2183 * ename:VK_FENCE_CREATE_SIGNALED_BIT specifies that the fence object is 2184 created in the signaled state. 2185 Otherwise, it is created in the unsignaled state. 2186-- 2187 2188[open,refpage='VkFenceCreateFlags',desc='Bitmask of VkFenceCreateFlagBits',type='flags'] 2189-- 2190include::{generated}/api/flags/VkFenceCreateFlags.adoc[] 2191 2192tname:VkFenceCreateFlags is a bitmask type for setting a mask of zero or 2193more elink:VkFenceCreateFlagBits. 2194-- 2195 2196ifdef::VK_VERSION_1_1,VK_KHR_external_fence[] 2197[open,refpage='VkExportFenceCreateInfo',desc='Structure specifying handle types that can be exported from a fence',type='structs'] 2198-- 2199To create a fence whose payload can: be exported to external handles, add a 2200slink:VkExportFenceCreateInfo structure to the pname:pNext chain of the 2201slink:VkFenceCreateInfo structure. 2202The sname:VkExportFenceCreateInfo structure is defined as: 2203 2204include::{generated}/api/structs/VkExportFenceCreateInfo.adoc[] 2205 2206ifdef::VK_KHR_external_fence[] 2207or the equivalent 2208 2209include::{generated}/api/structs/VkExportFenceCreateInfoKHR.adoc[] 2210endif::VK_KHR_external_fence[] 2211 2212 * pname:sType is the type of this structure. 2213 * pname:pNext is `NULL` or a pointer to a structure extending this 2214 structure. 2215 * pname:handleTypes is a bitmask of 2216 elink:VkExternalFenceHandleTypeFlagBits specifying one or more fence 2217 handle types the application can: export from the resulting fence. 2218 The application can: request multiple handle types for the same fence. 2219 2220.Valid Usage 2221**** 2222 * [[VUID-VkExportFenceCreateInfo-handleTypes-01446]] 2223 The bits in pname:handleTypes must: be supported and compatible, as 2224 reported by slink:VkExternalFenceProperties 2225**** 2226 2227include::{generated}/validity/structs/VkExportFenceCreateInfo.adoc[] 2228-- 2229endif::VK_VERSION_1_1,VK_KHR_external_fence[] 2230 2231ifdef::VK_KHR_external_fence_win32[] 2232[open,refpage='VkExportFenceWin32HandleInfoKHR',desc='Structure specifying additional attributes of Windows handles exported from a fence',type='structs'] 2233-- 2234To specify additional attributes of NT handles exported from a fence, add a 2235slink:VkExportFenceWin32HandleInfoKHR structure to the pname:pNext chain of 2236the slink:VkFenceCreateInfo structure. 2237The sname:VkExportFenceWin32HandleInfoKHR structure is defined as: 2238 2239include::{generated}/api/structs/VkExportFenceWin32HandleInfoKHR.adoc[] 2240 2241 * pname:sType is the type of this structure. 2242 * pname:pNext is `NULL` or a pointer to a structure extending this 2243 structure. 2244 * pname:pAttributes is a pointer to a Windows code:SECURITY_ATTRIBUTES 2245 structure specifying security attributes of the handle. 2246 * pname:dwAccess is a code:DWORD specifying access rights of the handle. 2247 * pname:name is a null-terminated UTF-16 string to associate with the 2248 underlying synchronization primitive referenced by NT handles exported 2249 from the created fence. 2250 2251If slink:VkExportFenceCreateInfo is not included in the same pname:pNext 2252chain, this structure is ignored. 2253 2254If slink:VkExportFenceCreateInfo is included in the pname:pNext chain of 2255slink:VkFenceCreateInfo with a Windows pname:handleType, but either 2256sname:VkExportFenceWin32HandleInfoKHR is not included in the pname:pNext 2257chain, or if it is but pname:pAttributes is set to `NULL`, default security 2258descriptor values will be used, and child processes created by the 2259application will not inherit the handle, as described in the MSDN 2260documentation for "`Synchronization Object Security and Access Rights`"^1^. 2261Further, if the structure is not present, the access rights will be 2262 2263code:DXGI_SHARED_RESOURCE_READ | code:DXGI_SHARED_RESOURCE_WRITE 2264 2265for handles of the following types: 2266 2267ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT 2268 22691:: 2270 https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights 2271 2272.Valid Usage 2273**** 2274 * [[VUID-VkExportFenceWin32HandleInfoKHR-handleTypes-01447]] 2275 If slink:VkExportFenceCreateInfo::pname:handleTypes does not include 2276 ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, a 2277 sname:VkExportFenceWin32HandleInfoKHR structure must: not be included in 2278 the pname:pNext chain of slink:VkFenceCreateInfo 2279**** 2280 2281include::{generated}/validity/structs/VkExportFenceWin32HandleInfoKHR.adoc[] 2282-- 2283 2284[open,refpage='vkGetFenceWin32HandleKHR',desc='Get a Windows HANDLE for a fence',type='protos'] 2285-- 2286To export a Windows handle representing the state of a fence, call: 2287 2288include::{generated}/api/protos/vkGetFenceWin32HandleKHR.adoc[] 2289 2290 * pname:device is the logical device that created the fence being 2291 exported. 2292 * pname:pGetWin32HandleInfo is a pointer to a 2293 slink:VkFenceGetWin32HandleInfoKHR structure containing parameters of 2294 the export operation. 2295 * pname:pHandle will return the Windows handle representing the fence 2296 state. 2297 2298For handle types defined as NT handles, the handles returned by 2299fname:vkGetFenceWin32HandleKHR are owned by the application. 2300To avoid leaking resources, the application must: release ownership of them 2301using the code:CloseHandle system call when they are no longer needed. 2302 2303Exporting a Windows handle from a fence may: have side effects depending on 2304the transference of the specified handle type, as described in 2305<<synchronization-fences-importing,Importing Fence Payloads>>. 2306 2307include::{generated}/validity/protos/vkGetFenceWin32HandleKHR.adoc[] 2308-- 2309 2310[open,refpage='VkFenceGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle fence export operation',type='structs'] 2311-- 2312The sname:VkFenceGetWin32HandleInfoKHR structure is defined as: 2313 2314include::{generated}/api/structs/VkFenceGetWin32HandleInfoKHR.adoc[] 2315 2316 * pname:sType is the type of this structure. 2317 * pname:pNext is `NULL` or a pointer to a structure extending this 2318 structure. 2319 * pname:fence is the fence from which state will be exported. 2320 * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value 2321 specifying the type of handle requested. 2322 2323The properties of the handle returned depend on the value of 2324pname:handleType. 2325See elink:VkExternalFenceHandleTypeFlagBits for a description of the 2326properties of the defined external fence handle types. 2327 2328.Valid Usage 2329**** 2330 * [[VUID-VkFenceGetWin32HandleInfoKHR-handleType-01448]] 2331 pname:handleType must: have been included in 2332 slink:VkExportFenceCreateInfo::pname:handleTypes when the pname:fence's 2333 current payload was created 2334 * [[VUID-VkFenceGetWin32HandleInfoKHR-handleType-01449]] 2335 If pname:handleType is defined as an NT handle, 2336 flink:vkGetFenceWin32HandleKHR must: be called no more than once for 2337 each valid unique combination of pname:fence and pname:handleType 2338 * [[VUID-VkFenceGetWin32HandleInfoKHR-fence-01450]] 2339 pname:fence must: not currently have its payload replaced by an imported 2340 payload as described below in 2341 <<synchronization-fences-importing,Importing Fence Payloads>> unless 2342 that imported payload's handle type was included in 2343 slink:VkExternalFenceProperties::pname:exportFromImportedHandleTypes for 2344 pname:handleType 2345 * [[VUID-VkFenceGetWin32HandleInfoKHR-handleType-01451]] 2346 If pname:handleType refers to a handle type with copy payload 2347 transference semantics, pname:fence must: be signaled, or have an 2348 associated <<synchronization-fences-signaling,fence signal operation>> 2349 pending execution 2350 * [[VUID-VkFenceGetWin32HandleInfoKHR-handleType-01452]] 2351 pname:handleType must: be defined as an NT handle or a global share 2352 handle 2353**** 2354 2355include::{generated}/validity/structs/VkFenceGetWin32HandleInfoKHR.adoc[] 2356-- 2357endif::VK_KHR_external_fence_win32[] 2358 2359ifdef::VK_KHR_external_fence_fd[] 2360[open,refpage='vkGetFenceFdKHR',desc='Get a POSIX file descriptor handle for a fence',type='protos'] 2361-- 2362To export a POSIX file descriptor representing the payload of a fence, call: 2363 2364include::{generated}/api/protos/vkGetFenceFdKHR.adoc[] 2365 2366 * pname:device is the logical device that created the fence being 2367 exported. 2368 * pname:pGetFdInfo is a pointer to a slink:VkFenceGetFdInfoKHR structure 2369 containing parameters of the export operation. 2370 * pname:pFd will return the file descriptor representing the fence 2371 payload. 2372 2373Each call to fname:vkGetFenceFdKHR must: create a new file descriptor and 2374transfer ownership of it to the application. 2375To avoid leaking resources, the application must: release ownership of the 2376file descriptor when it is no longer needed. 2377 2378[NOTE] 2379.Note 2380==== 2381Ownership can be released in many ways. 2382For example, the application can call code:close() on the file descriptor, 2383or transfer ownership back to Vulkan by using the file descriptor to import 2384a fence payload. 2385==== 2386 2387If pname:pGetFdInfo->handleType is 2388ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT and the fence is signaled at 2389the time fname:vkGetFenceFdKHR is called, pname:pFd may: return the value 2390`-1` instead of a valid file descriptor. 2391 2392Where supported by the operating system, the implementation must: set the 2393file descriptor to be closed automatically when an code:execve system call 2394is made. 2395 2396Exporting a file descriptor from a fence may: have side effects depending on 2397the transference of the specified handle type, as described in 2398<<synchronization-fences-importing,Importing Fence State>>. 2399 2400include::{generated}/validity/protos/vkGetFenceFdKHR.adoc[] 2401-- 2402 2403[open,refpage='VkFenceGetFdInfoKHR',desc='Structure describing a POSIX FD fence export operation',type='structs'] 2404-- 2405The sname:VkFenceGetFdInfoKHR structure is defined as: 2406 2407include::{generated}/api/structs/VkFenceGetFdInfoKHR.adoc[] 2408 2409 * pname:sType is the type of this structure. 2410 * pname:pNext is `NULL` or a pointer to a structure extending this 2411 structure. 2412 * pname:fence is the fence from which state will be exported. 2413 * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value 2414 specifying the type of handle requested. 2415 2416The properties of the file descriptor returned depend on the value of 2417pname:handleType. 2418See elink:VkExternalFenceHandleTypeFlagBits for a description of the 2419properties of the defined external fence handle types. 2420 2421.Valid Usage 2422**** 2423 * [[VUID-VkFenceGetFdInfoKHR-handleType-01453]] 2424 pname:handleType must: have been included in 2425 slink:VkExportFenceCreateInfo::pname:handleTypes when pname:fence's 2426 current payload was created 2427 * [[VUID-VkFenceGetFdInfoKHR-handleType-01454]] 2428 If pname:handleType refers to a handle type with copy payload 2429 transference semantics, pname:fence must: be signaled, or have an 2430 associated <<synchronization-fences-signaling,fence signal operation>> 2431 pending execution 2432 * [[VUID-VkFenceGetFdInfoKHR-fence-01455]] 2433 pname:fence must: not currently have its payload replaced by an imported 2434 payload as described below in 2435 <<synchronization-fences-importing,Importing Fence Payloads>> unless 2436 that imported payload's handle type was included in 2437 slink:VkExternalFenceProperties::pname:exportFromImportedHandleTypes for 2438 pname:handleType 2439 * [[VUID-VkFenceGetFdInfoKHR-handleType-01456]] 2440 pname:handleType must: be defined as a POSIX file descriptor handle 2441**** 2442 2443include::{generated}/validity/structs/VkFenceGetFdInfoKHR.adoc[] 2444-- 2445endif::VK_KHR_external_fence_fd[] 2446 2447[open,refpage='vkDestroyFence',desc='Destroy a fence object',type='protos'] 2448-- 2449To destroy a fence, call: 2450 2451include::{generated}/api/protos/vkDestroyFence.adoc[] 2452 2453 * pname:device is the logical device that destroys the fence. 2454 * pname:fence is the handle of the fence to destroy. 2455 * pname:pAllocator controls host memory allocation as described in the 2456 <<memory-allocation, Memory Allocation>> chapter. 2457 2458.Valid Usage 2459**** 2460 * [[VUID-vkDestroyFence-fence-01120]] 2461 All <<devsandqueues-submission, queue submission>> commands that refer 2462 to pname:fence must: have completed execution 2463 * [[VUID-vkDestroyFence-fence-01121]] 2464 If sname:VkAllocationCallbacks were provided when pname:fence was 2465 created, a compatible set of callbacks must: be provided here 2466 * [[VUID-vkDestroyFence-fence-01122]] 2467 If no sname:VkAllocationCallbacks were provided when pname:fence was 2468 created, pname:pAllocator must: be `NULL` 2469**** 2470 2471include::{generated}/validity/protos/vkDestroyFence.adoc[] 2472-- 2473 2474[open,refpage='vkGetFenceStatus',desc='Return the status of a fence',type='protos'] 2475-- 2476To query the status of a fence from the host, call: 2477 2478include::{generated}/api/protos/vkGetFenceStatus.adoc[] 2479 2480 * pname:device is the logical device that owns the fence. 2481 * pname:fence is the handle of the fence to query. 2482 2483Upon success, fname:vkGetFenceStatus returns the status of the fence object, 2484with the following return codes: 2485 2486.Fence Object Status Codes 2487[width="80%",options="header"] 2488|==== 2489| Status | Meaning 2490| ename:VK_SUCCESS | The fence specified by pname:fence is signaled. 2491| ename:VK_NOT_READY | The fence specified by pname:fence is unsignaled. 2492| ename:VK_ERROR_DEVICE_LOST | The device has been lost. See <<devsandqueues-lost-device,Lost Device>>. 2493|==== 2494 2495If a <<devsandqueues-submission, queue submission>> command is pending 2496execution, then the value returned by this command may: immediately be out 2497of date. 2498 2499If the device has been lost (see <<devsandqueues-lost-device,Lost Device>>), 2500fname:vkGetFenceStatus may: return any of the above status codes. 2501If the device has been lost and fname:vkGetFenceStatus is called repeatedly, 2502it will eventually return either ename:VK_SUCCESS or 2503ename:VK_ERROR_DEVICE_LOST. 2504 2505include::{generated}/validity/protos/vkGetFenceStatus.adoc[] 2506-- 2507 2508[[synchronization-fences-unsignaling]] 2509[open,refpage='vkResetFences',desc='Resets one or more fence objects',type='protos'] 2510-- 2511To set the state of fences to unsignaled from the host, call: 2512 2513include::{generated}/api/protos/vkResetFences.adoc[] 2514 2515 * pname:device is the logical device that owns the fences. 2516 * pname:fenceCount is the number of fences to reset. 2517 * pname:pFences is a pointer to an array of fence handles to reset. 2518 2519ifdef::VK_VERSION_1_1,VK_KHR_external_fence[] 2520 2521If any member of pname:pFences currently has its 2522<<synchronization-fences-importing, payload imported>> with temporary 2523permanence, that fence's prior permanent payload is first restored. 2524The remaining operations described therefore operate on the restored 2525payload. 2526 2527endif::VK_VERSION_1_1,VK_KHR_external_fence[] 2528 2529When flink:vkResetFences is executed on the host, it defines a _fence 2530unsignal operation_ for each fence, which resets the fence to the unsignaled 2531state. 2532 2533If any member of pname:pFences is already in the unsignaled state when 2534flink:vkResetFences is executed, then flink:vkResetFences has no effect on 2535that fence. 2536 2537.Valid Usage 2538**** 2539 * [[VUID-vkResetFences-pFences-01123]] 2540 Each element of pname:pFences must: not be currently associated with any 2541 queue command that has not yet completed execution on that queue 2542**** 2543 2544include::{generated}/validity/protos/vkResetFences.adoc[] 2545-- 2546 2547[[synchronization-fences-signaling]] 2548When a fence is submitted to a queue as part of a 2549<<devsandqueues-submission, queue submission>> command, it defines a memory 2550dependency on the batches that were submitted as part of that command, and 2551defines a _fence signal operation_ which sets the fence to the signaled 2552state. 2553 2554The first <<synchronization-dependencies-scopes, synchronization scope>> 2555includes every batch submitted in the same <<devsandqueues-submission, queue 2556submission>> command. 2557Fence signal operations that are defined by flink:vkQueueSubmit 2558ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2559or flink:vkQueueSubmit2 2560endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2561additionally include in the first synchronization scope all commands that 2562occur earlier in <<synchronization-submission-order,submission order>>. 2563Fence signal operations that are defined by flink:vkQueueSubmit 2564ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 2565, flink:vkQueueSubmit2 2566endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2567or flink:vkQueueBindSparse additionally include in the first synchronization 2568scope any semaphore and fence signal operations that occur earlier in 2569<<synchronization-signal-operation-order,signal operation order>>. 2570 2571The second <<synchronization-dependencies-scopes, synchronization scope>> 2572only includes the fence signal operation. 2573 2574The first <<synchronization-dependencies-access-scopes, access scope>> 2575includes all memory access performed by the device. 2576 2577The second <<synchronization-dependencies-access-scopes, access scope>> is 2578empty. 2579 2580[open,refpage='vkWaitForFences',desc='Wait for one or more fences to become signaled',type='protos'] 2581-- 2582To wait for one or more fences to enter the signaled state on the host, 2583call: 2584 2585include::{generated}/api/protos/vkWaitForFences.adoc[] 2586 2587 * pname:device is the logical device that owns the fences. 2588 * pname:fenceCount is the number of fences to wait on. 2589 * pname:pFences is a pointer to an array of pname:fenceCount fence 2590 handles. 2591 * pname:waitAll is the condition that must: be satisfied to successfully 2592 unblock the wait. 2593 If pname:waitAll is ename:VK_TRUE, then the condition is that all fences 2594 in pname:pFences are signaled. 2595 Otherwise, the condition is that at least one fence in pname:pFences is 2596 signaled. 2597 * pname:timeout is the timeout period in units of nanoseconds. 2598 pname:timeout is adjusted to the closest value allowed by the 2599 implementation-dependent timeout accuracy, which may: be substantially 2600 longer than one nanosecond, and may: be longer than the requested 2601 period. 2602 2603If the condition is satisfied when fname:vkWaitForFences is called, then 2604fname:vkWaitForFences returns immediately. 2605If the condition is not satisfied at the time fname:vkWaitForFences is 2606called, then fname:vkWaitForFences will block and wait until the condition 2607is satisfied or the pname:timeout has expired, whichever is sooner. 2608 2609If pname:timeout is zero, then fname:vkWaitForFences does not wait, but 2610simply returns the current state of the fences. 2611ename:VK_TIMEOUT will be returned in this case if the condition is not 2612satisfied, even though no actual wait was performed. 2613 2614If the condition is satisfied before the pname:timeout has expired, 2615fname:vkWaitForFences returns ename:VK_SUCCESS. 2616Otherwise, fname:vkWaitForFences returns ename:VK_TIMEOUT after the 2617pname:timeout has expired. 2618 2619If device loss occurs (see <<devsandqueues-lost-device,Lost Device>>) before 2620the timeout has expired, fname:vkWaitForFences must: return in finite time 2621with either ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. 2622 2623[NOTE] 2624.Note 2625==== 2626While we guarantee that fname:vkWaitForFences must: return in finite time, 2627no guarantees are made that it returns immediately upon device loss. 2628However, the client can reasonably expect that the delay will be on the 2629order of seconds and that calling fname:vkWaitForFences will not result in a 2630permanently (or seemingly permanently) dead process. 2631==== 2632 2633include::{generated}/validity/protos/vkWaitForFences.adoc[] 2634-- 2635 2636[[synchronization-fences-waiting]] 2637An execution dependency is defined by waiting for a fence to become 2638signaled, either via flink:vkWaitForFences or by polling on 2639flink:vkGetFenceStatus. 2640 2641The first <<synchronization-dependencies-scopes, synchronization scope>> 2642includes only the fence signal operation. 2643 2644The second <<synchronization-dependencies-scopes, synchronization scope>> 2645includes the host operations of flink:vkWaitForFences or 2646flink:vkGetFenceStatus indicating that the fence has become signaled. 2647 2648[NOTE] 2649.Note 2650==== 2651Signaling a fence and waiting on the host does not guarantee that the 2652results of memory accesses will be visible to the host, as the access scope 2653of a memory dependency defined by a fence only includes device access. 2654A <<synchronization-memory-barriers, memory barrier>> or other memory 2655dependency must: be used to guarantee this. 2656See the description of <<synchronization-host-access-types, host access 2657types>> for more information. 2658==== 2659 2660ifdef::VK_EXT_display_control[] 2661include::{chapters}/VK_EXT_display_control/fence_events.adoc[] 2662endif::VK_EXT_display_control[] 2663 2664 2665ifdef::VK_VERSION_1_1,VK_KHR_external_fence[] 2666[[synchronization-fences-importing]] 2667=== Importing Fence Payloads 2668 2669Applications can: import a fence payload into an existing fence using an 2670external fence handle. 2671The effects of the import operation will be either temporary or permanent, 2672as specified by the application. 2673If the import is temporary, the fence will be _restored_ to its permanent 2674state the next time that fence is passed to flink:vkResetFences. 2675 2676[NOTE] 2677.Note 2678==== 2679Restoring a fence to its prior permanent payload is a distinct operation 2680from resetting a fence payload. 2681See flink:vkResetFences for more detail. 2682==== 2683 2684Performing a subsequent temporary import on a fence before resetting it has 2685no effect on this requirement; the next unsignal of the fence must: still 2686restore its last permanent state. 2687A permanent payload import behaves as if the target fence was destroyed, and 2688a new fence was created with the same handle but the imported payload. 2689Because importing a fence payload temporarily or permanently detaches the 2690existing payload from a fence, similar usage restrictions to those applied 2691to fname:vkDestroyFence are applied to any command that imports a fence 2692payload. 2693Which of these import types is used is referred to as the import operation's 2694_permanence_. 2695Each handle type supports either one or both types of permanence. 2696 2697The implementation must: perform the import operation by either referencing 2698or copying the payload referred to by the specified external fence handle, 2699depending on the handle's type. 2700The import method used is referred to as the handle type's _transference_. 2701When using handle types with reference transference, importing a payload to 2702a fence adds the fence to the set of all fences sharing that payload. 2703This set includes the fence from which the payload was exported. 2704Fence signaling, waiting, and resetting operations performed on any fence in 2705the set must: behave as if the set were a single fence. 2706Importing a payload using handle types with copy transference creates a 2707duplicate copy of the payload at the time of import, but makes no further 2708reference to it. 2709Fence signaling, waiting, and resetting operations performed on the target 2710of copy imports must: not affect any other fence or payload. 2711 2712Export operations have the same transference as the specified handle type's 2713import operations. 2714Additionally, exporting a fence payload to a handle with copy transference 2715has the same side effects on the source fence's payload as executing a fence 2716reset operation. 2717If the fence was using a temporarily imported payload, the fence's prior 2718permanent payload will be restored. 2719 2720ifdef::VK_KHR_external_fence_win32,VK_KHR_external_fence_fd[] 2721[NOTE] 2722.Note 2723==== 2724The 2725ifdef::VK_KHR_external_fence_win32+VK_KHR_external_fence_fd[tables] 2726ifndef::VK_KHR_external_fence_win32+VK_KHR_external_fence_fd[table] 2727ifdef::VK_KHR_external_fence_win32[] 2728<<synchronization-fence-handletypes-win32,Handle Types Supported by 2729sname:VkImportFenceWin32HandleInfoKHR>> 2730endif::VK_KHR_external_fence_win32[] 2731ifdef::VK_KHR_external_fence_win32+VK_KHR_external_fence_fd[and] 2732ifdef::VK_KHR_external_fence_fd[] 2733<<synchronization-fence-handletypes-fd,Handle Types Supported by 2734sname:VkImportFenceFdInfoKHR>> 2735endif::VK_KHR_external_fence_fd[] 2736ifdef::VK_KHR_external_fence_win32+VK_KHR_external_fence_fd[define] 2737ifndef::VK_KHR_external_fence_win32+VK_KHR_external_fence_fd[defines] 2738the permanence and transference of each handle type. 2739==== 2740endif::VK_KHR_external_fence_win32,VK_KHR_external_fence_fd[] 2741 2742<<fundamentals-threadingbehavior,External synchronization>> allows 2743implementations to modify an object's internal state, i.e. payload, without 2744internal synchronization. 2745However, for fences sharing a payload across processes, satisfying the 2746external synchronization requirements of sname:VkFence parameters as if all 2747fences in the set were the same object is sometimes infeasible. 2748Satisfying valid usage constraints on the state of a fence would similarly 2749require impractical coordination or levels of trust between processes. 2750Therefore, these constraints only apply to a specific fence handle, not to 2751its payload. 2752For distinct fence objects which share a payload: 2753 2754 * If multiple commands which queue a signal operation, or which unsignal a 2755 fence, are called concurrently, behavior will be as if the commands were 2756 called in an arbitrary sequential order. 2757 * If a queue submission command is called with a fence that is sharing a 2758 payload, and the payload is already associated with another queue 2759 command that has not yet completed execution, either one or both of the 2760 commands will cause the fence to become signaled when they complete 2761 execution. 2762 * If a fence payload is reset while it is associated with a queue command 2763 that has not yet completed execution, the payload will become 2764 unsignaled, but may: become signaled again when the command completes 2765 execution. 2766 * In the preceding cases, any of the devices associated with the fences 2767 sharing the payload may: be lost, or any of the queue submission or 2768 fence reset commands may: return ename:VK_ERROR_INITIALIZATION_FAILED. 2769 2770Other than these non-deterministic results, behavior is well defined. 2771In particular: 2772 2773 * The implementation must: not crash or enter an internally inconsistent 2774 state where future valid Vulkan commands might cause undefined: results, 2775 * Timeouts on future wait commands on fences sharing the payload must: be 2776 effective. 2777 2778[NOTE] 2779.Note 2780==== 2781These rules allow processes to synchronize access to shared memory without 2782trusting each other. 2783However, such processes must still be cautious not to use the shared fence 2784for more than synchronizing access to the shared memory. 2785For example, a process should not use a fence with shared payload to tell 2786when commands it submitted to a queue have completed and objects used by 2787those commands may be destroyed, since the other process can accidentally or 2788maliciously cause the fence to signal before the commands actually complete. 2789==== 2790 2791When a fence is using an imported payload, its 2792slink:VkExportFenceCreateInfo::pname:handleTypes value is specified when 2793creating the fence from which the payload was exported, rather than 2794specified when creating the fence. 2795Additionally, 2796slink:VkExternalFenceProperties::pname:exportFromImportedHandleTypes 2797restricts which handle types can: be exported from such a fence based on the 2798specific handle type used to import the current payload. 2799ifdef::VK_KHR_swapchain[] 2800Passing a fence to flink:vkAcquireNextImageKHR is equivalent to temporarily 2801importing a fence payload to that fence. 2802 2803[NOTE] 2804.Note 2805==== 2806Because the exportable handle types of an imported fence correspond to its 2807current imported payload, and flink:vkAcquireNextImageKHR behaves the same 2808as a temporary import operation for which the source fence is opaque to the 2809application, applications have no way of determining whether any external 2810handle types can: be exported from a fence in this state. 2811Therefore, applications must: not attempt to export handles from fences 2812using a temporarily imported payload from flink:vkAcquireNextImageKHR. 2813==== 2814endif::VK_KHR_swapchain[] 2815 2816When importing a fence payload, it is the responsibility of the application 2817to ensure the external handles meet all valid usage requirements. 2818However, implementations must: perform sufficient validation of external 2819handles to ensure that the operation results in a valid fence which will not 2820cause program termination, device loss, queue stalls, host thread stalls, or 2821corruption of other resources when used as allowed according to its import 2822parameters. 2823If the external handle provided does not meet these requirements, the 2824implementation must: fail the fence payload import operation with the error 2825code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. 2826endif::VK_VERSION_1_1,VK_KHR_external_fence[] 2827 2828ifdef::VK_KHR_external_fence_win32[] 2829[open,refpage='vkImportFenceWin32HandleKHR',desc='Import a fence from a Windows HANDLE',type='protos'] 2830-- 2831To import a fence payload from a Windows handle, call: 2832 2833include::{generated}/api/protos/vkImportFenceWin32HandleKHR.adoc[] 2834 2835 * pname:device is the logical device that created the fence. 2836 * pname:pImportFenceWin32HandleInfo is a pointer to a 2837 slink:VkImportFenceWin32HandleInfoKHR structure specifying the fence and 2838 import parameters. 2839 2840Importing a fence payload from Windows handles does not transfer ownership 2841of the handle to the Vulkan implementation. 2842For handle types defined as NT handles, the application must: release 2843ownership using the code:CloseHandle system call when the handle is no 2844longer needed. 2845 2846Applications can: import the same fence payload into multiple instances of 2847Vulkan, into the same instance from which it was exported, and multiple 2848times into a given Vulkan instance. 2849 2850.Valid Usage 2851**** 2852 * [[VUID-vkImportFenceWin32HandleKHR-fence-04448]] 2853 pname:fence must: not be associated with any queue command that has not 2854 yet completed execution on that queue 2855**** 2856 2857include::{generated}/validity/protos/vkImportFenceWin32HandleKHR.adoc[] 2858-- 2859 2860[open,refpage='VkImportFenceWin32HandleInfoKHR',desc='(None)',type='structs'] 2861-- 2862The sname:VkImportFenceWin32HandleInfoKHR structure is defined as: 2863 2864include::{generated}/api/structs/VkImportFenceWin32HandleInfoKHR.adoc[] 2865 2866 * pname:sType is the type of this structure. 2867 * pname:pNext is `NULL` or a pointer to a structure extending this 2868 structure. 2869 * pname:fence is the fence into which the state will be imported. 2870 * pname:flags is a bitmask of elink:VkFenceImportFlagBits specifying 2871 additional parameters for the fence payload import operation. 2872 * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value 2873 specifying the type of pname:handle. 2874 * pname:handle is `NULL` or the external handle to import. 2875 * pname:name is `NULL` or a null-terminated UTF-16 string naming the 2876 underlying synchronization primitive to import. 2877 2878The handle types supported by pname:handleType are: 2879 2880[[synchronization-fence-handletypes-win32]] 2881.Handle Types Supported by sname:VkImportFenceWin32HandleInfoKHR 2882[width="80%",options="header"] 2883|==== 2884| Handle Type | Transference | Permanence Supported 2885| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Reference | Temporary,Permanent 2886| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Reference | Temporary,Permanent 2887|==== 2888 2889.Valid Usage 2890**** 2891 * [[VUID-VkImportFenceWin32HandleInfoKHR-handleType-01457]] 2892 pname:handleType must: be a value included in the 2893 <<synchronization-fence-handletypes-win32, Handle Types Supported by 2894 sname:VkImportFenceWin32HandleInfoKHR>> table 2895 * [[VUID-VkImportFenceWin32HandleInfoKHR-handleType-01459]] 2896 If pname:handleType is not 2897 ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT, pname:name must: 2898 be `NULL` 2899 * [[VUID-VkImportFenceWin32HandleInfoKHR-handleType-01460]] 2900 If pname:handle is `NULL`, pname:name must: name a valid synchronization 2901 primitive of the type specified by pname:handleType 2902 * [[VUID-VkImportFenceWin32HandleInfoKHR-handleType-01461]] 2903 If pname:name is `NULL`, pname:handle must: be a valid handle of the 2904 type specified by pname:handleType 2905 * [[VUID-VkImportFenceWin32HandleInfoKHR-handle-01462]] 2906 If pname:handle is not `NULL`, pname:name must: be `NULL` 2907 * [[VUID-VkImportFenceWin32HandleInfoKHR-handle-01539]] 2908 If pname:handle is not `NULL`, it must: obey any requirements listed for 2909 pname:handleType in <<external-fence-handle-types-compatibility,external 2910 fence handle types compatibility>> 2911 * [[VUID-VkImportFenceWin32HandleInfoKHR-name-01540]] 2912 If pname:name is not `NULL`, it must: obey any requirements listed for 2913 pname:handleType in <<external-fence-handle-types-compatibility,external 2914 fence handle types compatibility>> 2915**** 2916 2917include::{generated}/validity/structs/VkImportFenceWin32HandleInfoKHR.adoc[] 2918-- 2919endif::VK_KHR_external_fence_win32[] 2920 2921ifdef::VK_KHR_external_fence_fd[] 2922[open,refpage='vkImportFenceFdKHR',desc='Import a fence from a POSIX file descriptor',type='protos'] 2923-- 2924To import a fence payload from a POSIX file descriptor, call: 2925 2926include::{generated}/api/protos/vkImportFenceFdKHR.adoc[] 2927 2928 * pname:device is the logical device that created the fence. 2929 * pname:pImportFenceFdInfo is a pointer to a slink:VkImportFenceFdInfoKHR 2930 structure specifying the fence and import parameters. 2931 2932Importing a fence payload from a file descriptor transfers ownership of the 2933file descriptor from the application to the Vulkan implementation. 2934The application must: not perform any operations on the file descriptor 2935after a successful import. 2936 2937Applications can: import the same fence payload into multiple instances of 2938Vulkan, into the same instance from which it was exported, and multiple 2939times into a given Vulkan instance. 2940 2941.Valid Usage 2942**** 2943 * [[VUID-vkImportFenceFdKHR-fence-01463]] 2944 pname:fence must: not be associated with any queue command that has not 2945 yet completed execution on that queue 2946**** 2947 2948include::{generated}/validity/protos/vkImportFenceFdKHR.adoc[] 2949-- 2950 2951[open,refpage='VkImportFenceFdInfoKHR',desc='(None)',type='structs'] 2952-- 2953The sname:VkImportFenceFdInfoKHR structure is defined as: 2954 2955include::{generated}/api/structs/VkImportFenceFdInfoKHR.adoc[] 2956 2957 * pname:sType is the type of this structure. 2958 * pname:pNext is `NULL` or a pointer to a structure extending this 2959 structure. 2960 * pname:fence is the fence into which the payload will be imported. 2961 * pname:flags is a bitmask of elink:VkFenceImportFlagBits specifying 2962 additional parameters for the fence payload import operation. 2963 * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value 2964 specifying the type of pname:fd. 2965 * pname:fd is the external handle to import. 2966 2967The handle types supported by pname:handleType are: 2968 2969[[synchronization-fence-handletypes-fd]] 2970.Handle Types Supported by sname:VkImportFenceFdInfoKHR 2971[width="80%",options="header"] 2972|==== 2973| Handle Type | Transference | Permanence Supported 2974| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT | Reference | Temporary,Permanent 2975| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT | Copy | Temporary 2976|==== 2977 2978.Valid Usage 2979**** 2980 * [[VUID-VkImportFenceFdInfoKHR-handleType-01464]] 2981 pname:handleType must: be a value included in the 2982 <<synchronization-fence-handletypes-fd, Handle Types Supported by 2983 sname:VkImportFenceFdInfoKHR>> table 2984 * [[VUID-VkImportFenceFdInfoKHR-fd-01541]] 2985 pname:fd must: obey any requirements listed for pname:handleType in 2986 <<external-fence-handle-types-compatibility,external fence handle types 2987 compatibility>> 2988 * [[VUID-VkImportFenceFdInfoKHR-handleType-07306]] 2989 If pname:handleType refers to a handle type with copy payload 2990 transference semantics, pname:flags must: contain 2991 ename:VK_FENCE_IMPORT_TEMPORARY_BIT 2992**** 2993 2994If pname:handleType is ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT, the 2995special value `-1` for pname:fd is treated like a valid sync file descriptor 2996referring to an object that has already signaled. 2997The import operation will succeed and the sname:VkFence will have a 2998temporarily imported payload as if a valid file descriptor had been 2999provided. 3000 3001[NOTE] 3002.Note 3003==== 3004This special behavior for importing an invalid sync file descriptor allows 3005easier interoperability with other system APIs which use the convention that 3006an invalid sync file descriptor represents work that has already completed 3007and does not need to be waited for. 3008It is consistent with the option for implementations to return a `-1` file 3009descriptor when exporting a ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT 3010from a sname:VkFence which is signaled. 3011==== 3012 3013include::{generated}/validity/structs/VkImportFenceFdInfoKHR.adoc[] 3014-- 3015endif::VK_KHR_external_fence_fd[] 3016 3017ifdef::VK_VERSION_1_1,VK_KHR_external_fence[] 3018ifdef::VK_KHR_external_fence_win32,VK_KHR_external_fence_fd[] 3019[open,refpage='VkFenceImportFlagBits',desc='Bitmask specifying additional parameters of fence payload import',type='enums'] 3020-- 3021Bits which can: be set in 3022 3023ifdef::VK_KHR_external_fence_win32[] 3024 * slink:VkImportFenceWin32HandleInfoKHR::pname:flags 3025endif::VK_KHR_external_fence_win32[] 3026ifdef::VK_KHR_external_fence_fd[] 3027 * slink:VkImportFenceFdInfoKHR::pname:flags 3028endif::VK_KHR_external_fence_fd[] 3029 3030specifying additional parameters of a fence import operation are: 3031 3032include::{generated}/api/enums/VkFenceImportFlagBits.adoc[] 3033 3034ifdef::VK_KHR_external_fence[] 3035or the equivalent 3036 3037include::{generated}/api/enums/VkFenceImportFlagBitsKHR.adoc[] 3038endif::VK_KHR_external_fence[] 3039 3040 * ename:VK_FENCE_IMPORT_TEMPORARY_BIT specifies that the fence payload 3041 will be imported only temporarily, as described in 3042 <<synchronization-fences-importing,Importing Fence Payloads>>, 3043 regardless of the permanence of pname:handleType. 3044-- 3045 3046[open,refpage='VkFenceImportFlags',desc='Bitmask of VkFenceImportFlagBits',type='flags'] 3047-- 3048include::{generated}/api/flags/VkFenceImportFlags.adoc[] 3049 3050ifdef::VK_KHR_external_fence[] 3051or the equivalent 3052 3053include::{generated}/api/flags/VkFenceImportFlagsKHR.adoc[] 3054endif::VK_KHR_external_fence[] 3055 3056tname:VkFenceImportFlags is a bitmask type for setting a mask of zero or 3057more elink:VkFenceImportFlagBits. 3058-- 3059endif::VK_KHR_external_fence_win32,VK_KHR_external_fence_fd[] 3060endif::VK_VERSION_1_1,VK_KHR_external_fence[] 3061 3062 3063[[synchronization-semaphores]] 3064== Semaphores 3065 3066[open,refpage='VkSemaphore',desc='Opaque handle to a semaphore object',type='handles'] 3067-- 3068Semaphores are a synchronization primitive that can: be used to insert a 3069dependency 3070ifndef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3071between queue operations. 3072Semaphores have two states - signaled and unsignaled. 3073endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3074ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3075between queue operations or between a queue operation and the host. 3076<<glossary, Binary semaphores>> have two states - signaled and unsignaled. 3077<<glossary, Timeline semaphores>> have a strictly increasing 64-bit unsigned 3078integer payload and are signaled with respect to a particular reference 3079value. 3080endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3081A semaphore can: be signaled after execution of a queue operation is 3082completed, and a queue operation can: wait for a semaphore to become 3083signaled before it begins execution. 3084ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3085A timeline semaphore can: additionally be signaled from the host with the 3086flink:vkSignalSemaphore command and waited on from the host with the 3087flink:vkWaitSemaphores command. 3088endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3089 3090ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 3091[[synchronization-semaphores-payloads]] 3092The internal data of a semaphore may: include a reference to any resources 3093and pending work associated with signal or unsignal operations performed on 3094that semaphore object, collectively referred to as the semaphore's 3095_payload_. 3096Mechanisms to import and export that internal data to and from semaphores 3097are provided <<VkExportSemaphoreCreateInfo, below>>. 3098These mechanisms indirectly enable applications to share semaphore state 3099between two or more semaphores and other synchronization primitives across 3100process and API boundaries. 3101 3102endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 3103 3104Semaphores are represented by sname:VkSemaphore handles: 3105 3106include::{generated}/api/handles/VkSemaphore.adoc[] 3107-- 3108 3109[open,refpage='vkCreateSemaphore',desc='Create a new queue semaphore object',type='protos'] 3110-- 3111To create a semaphore, call: 3112 3113include::{generated}/api/protos/vkCreateSemaphore.adoc[] 3114 3115 * pname:device is the logical device that creates the semaphore. 3116 * pname:pCreateInfo is a pointer to a slink:VkSemaphoreCreateInfo 3117 structure containing information about how the semaphore is to be 3118 created. 3119 * pname:pAllocator controls host memory allocation as described in the 3120 <<memory-allocation, Memory Allocation>> chapter. 3121 * pname:pSemaphore is a pointer to a handle in which the resulting 3122 semaphore object is returned. 3123 3124ifndef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3125This command creates a _binary semaphore_ that has a boolean payload 3126indicating whether the semaphore is currently signaled or unsignaled. 3127When created, the semaphore is in the unsignaled state. 3128endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3129 3130include::{generated}/validity/protos/vkCreateSemaphore.adoc[] 3131-- 3132 3133[open,refpage='VkSemaphoreCreateInfo',desc='Structure specifying parameters of a newly created semaphore',type='structs'] 3134-- 3135The sname:VkSemaphoreCreateInfo structure is defined as: 3136 3137include::{generated}/api/structs/VkSemaphoreCreateInfo.adoc[] 3138 3139 * pname:sType is the type of this structure. 3140 * pname:pNext is `NULL` or a pointer to a structure extending this 3141 structure. 3142 * pname:flags is reserved for future use. 3143 3144ifdef::VK_EXT_metal_objects[] 3145.Valid Usage 3146**** 3147 * [[VUID-VkSemaphoreCreateInfo-pNext-06789]] 3148 If the pname:pNext chain includes a 3149 slink:VkExportMetalObjectCreateInfoEXT structure, its 3150 pname:exportObjectType member must: be 3151 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT 3152**** 3153endif::VK_EXT_metal_objects[] 3154 3155include::{generated}/validity/structs/VkSemaphoreCreateInfo.adoc[] 3156-- 3157 3158[open,refpage='VkSemaphoreCreateFlags',desc='Reserved for future use',type='flags'] 3159-- 3160include::{generated}/api/flags/VkSemaphoreCreateFlags.adoc[] 3161 3162tname:VkSemaphoreCreateFlags is a bitmask type for setting a mask, but is 3163currently reserved for future use. 3164-- 3165 3166ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3167[open,refpage='VkSemaphoreTypeCreateInfo',desc='Structure specifying the type of a newly created semaphore',type='structs',alias='VkSemaphoreTypeCreateInfoKHR'] 3168-- 3169The sname:VkSemaphoreTypeCreateInfo structure is defined as: 3170 3171include::{generated}/api/structs/VkSemaphoreTypeCreateInfo.adoc[] 3172 3173ifdef::VK_KHR_timeline_semaphore[] 3174or the equivalent 3175 3176include::{generated}/api/structs/VkSemaphoreTypeCreateInfoKHR.adoc[] 3177endif::VK_KHR_timeline_semaphore[] 3178 3179 * pname:sType is the type of this structure. 3180 * pname:pNext is `NULL` or a pointer to a structure extending this 3181 structure. 3182 * pname:semaphoreType is a elink:VkSemaphoreType value specifying the type 3183 of the semaphore. 3184 * pname:initialValue is the initial payload value if pname:semaphoreType 3185 is ename:VK_SEMAPHORE_TYPE_TIMELINE. 3186 3187To create a semaphore of a specific type, add a 3188sname:VkSemaphoreTypeCreateInfo structure to the 3189slink:VkSemaphoreCreateInfo::pname:pNext chain. 3190 3191If no sname:VkSemaphoreTypeCreateInfo structure is included in the 3192pname:pNext chain of slink:VkSemaphoreCreateInfo, then the created semaphore 3193will have a default elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY. 3194 3195.Valid Usage 3196**** 3197 * [[VUID-VkSemaphoreTypeCreateInfo-timelineSemaphore-03252]] 3198 If the <<features-timelineSemaphore, pname:timelineSemaphore>> feature 3199 is not enabled, pname:semaphoreType must: not equal 3200 ename:VK_SEMAPHORE_TYPE_TIMELINE 3201 * [[VUID-VkSemaphoreTypeCreateInfo-semaphoreType-03279]] 3202 If pname:semaphoreType is ename:VK_SEMAPHORE_TYPE_BINARY, 3203 pname:initialValue must: be zero 3204**** 3205 3206include::{generated}/validity/structs/VkSemaphoreTypeCreateInfo.adoc[] 3207-- 3208 3209[open,refpage='VkSemaphoreType',desc='Specifies the type of a semaphore object',type='enums',alias='VkSemaphoreTypeKHR'] 3210-- 3211Possible values of slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType, 3212specifying the type of a semaphore, are: 3213 3214include::{generated}/api/enums/VkSemaphoreType.adoc[] 3215 3216ifdef::VK_KHR_timeline_semaphore[] 3217or the equivalent 3218 3219include::{generated}/api/enums/VkSemaphoreTypeKHR.adoc[] 3220endif::VK_KHR_timeline_semaphore[] 3221 3222 * ename:VK_SEMAPHORE_TYPE_BINARY specifies a _binary semaphore_ type that 3223 has a boolean payload indicating whether the semaphore is currently 3224 signaled or unsignaled. 3225 When created, the semaphore is in the unsignaled state. 3226 * ename:VK_SEMAPHORE_TYPE_TIMELINE specifies a _timeline semaphore_ type 3227 that has a strictly increasing 64-bit unsigned integer payload 3228 indicating whether the semaphore is signaled with respect to a 3229 particular reference value. 3230 When created, the semaphore payload has the value given by the 3231 pname:initialValue field of slink:VkSemaphoreTypeCreateInfo. 3232-- 3233endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3234 3235ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 3236[open,refpage='VkExportSemaphoreCreateInfo',desc='Structure specifying handle types that can be exported from a semaphore',type='structs'] 3237-- 3238To create a semaphore whose payload can: be exported to external handles, 3239add a slink:VkExportSemaphoreCreateInfo structure to the pname:pNext chain 3240of the slink:VkSemaphoreCreateInfo structure. 3241The sname:VkExportSemaphoreCreateInfo structure is defined as: 3242 3243include::{generated}/api/structs/VkExportSemaphoreCreateInfo.adoc[] 3244 3245ifdef::VK_KHR_external_semaphore[] 3246or the equivalent 3247 3248include::{generated}/api/structs/VkExportSemaphoreCreateInfoKHR.adoc[] 3249endif::VK_KHR_external_semaphore[] 3250 3251 * pname:sType is the type of this structure. 3252 * pname:pNext is `NULL` or a pointer to a structure extending this 3253 structure. 3254 * pname:handleTypes is a bitmask of 3255 elink:VkExternalSemaphoreHandleTypeFlagBits specifying one or more 3256 semaphore handle types the application can: export from the resulting 3257 semaphore. 3258 The application can: request multiple handle types for the same 3259 semaphore. 3260 3261.Valid Usage 3262**** 3263 * [[VUID-VkExportSemaphoreCreateInfo-handleTypes-01124]] 3264 The bits in pname:handleTypes must: be supported and compatible, as 3265 reported by slink:VkExternalSemaphoreProperties 3266**** 3267 3268include::{generated}/validity/structs/VkExportSemaphoreCreateInfo.adoc[] 3269-- 3270endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 3271 3272ifdef::VK_KHR_external_semaphore_win32[] 3273[open,refpage='VkExportSemaphoreWin32HandleInfoKHR',desc='Structure specifying additional attributes of Windows handles exported from a semaphore',type='structs'] 3274-- 3275To specify additional attributes of NT handles exported from a semaphore, 3276add a sname:VkExportSemaphoreWin32HandleInfoKHR structure to the pname:pNext 3277chain of the slink:VkSemaphoreCreateInfo structure. 3278The sname:VkExportSemaphoreWin32HandleInfoKHR structure is defined as: 3279 3280include::{generated}/api/structs/VkExportSemaphoreWin32HandleInfoKHR.adoc[] 3281 3282 * pname:sType is the type of this structure. 3283 * pname:pNext is `NULL` or a pointer to a structure extending this 3284 structure. 3285 * pname:pAttributes is a pointer to a Windows code:SECURITY_ATTRIBUTES 3286 structure specifying security attributes of the handle. 3287 * pname:dwAccess is a code:DWORD specifying access rights of the handle. 3288 * pname:name is a null-terminated UTF-16 string to associate with the 3289 underlying synchronization primitive referenced by NT handles exported 3290 from the created semaphore. 3291 3292If slink:VkExportSemaphoreCreateInfo is not included in the same pname:pNext 3293chain, this structure is ignored. 3294 3295If slink:VkExportSemaphoreCreateInfo is included in the pname:pNext chain of 3296slink:VkSemaphoreCreateInfo with a Windows pname:handleType, but either 3297sname:VkExportSemaphoreWin32HandleInfoKHR is not included in the pname:pNext 3298chain, or if it is but pname:pAttributes is set to `NULL`, default security 3299descriptor values will be used, and child processes created by the 3300application will not inherit the handle, as described in the MSDN 3301documentation for "`Synchronization Object Security and Access Rights`"^1^. 3302Further, if the structure is not present, the access rights used depend on 3303the handle type. 3304 3305For handles of the following types: 3306 3307ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT 3308 3309The implementation must: ensure the access rights allow both signal and wait 3310operations on the semaphore. 3311 3312For handles of the following types: 3313 3314ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT 3315 3316The access rights must: be: 3317 3318code:GENERIC_ALL 3319 33201:: 3321 https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights 3322 3323.Valid Usage 3324**** 3325 * [[VUID-VkExportSemaphoreWin32HandleInfoKHR-handleTypes-01125]] 3326 If slink:VkExportSemaphoreCreateInfo::pname:handleTypes does not include 3327 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or 3328 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT, 3329 sname:VkExportSemaphoreWin32HandleInfoKHR must: not be included in the 3330 pname:pNext chain of slink:VkSemaphoreCreateInfo 3331**** 3332 3333include::{generated}/validity/structs/VkExportSemaphoreWin32HandleInfoKHR.adoc[] 3334-- 3335 3336[open,refpage='vkGetSemaphoreWin32HandleKHR',desc='Get a Windows HANDLE for a semaphore',type='protos'] 3337-- 3338To export a Windows handle representing the payload of a semaphore, call: 3339 3340include::{generated}/api/protos/vkGetSemaphoreWin32HandleKHR.adoc[] 3341 3342 * pname:device is the logical device that created the semaphore being 3343 exported. 3344 * pname:pGetWin32HandleInfo is a pointer to a 3345 slink:VkSemaphoreGetWin32HandleInfoKHR structure containing parameters 3346 of the export operation. 3347 * pname:pHandle will return the Windows handle representing the semaphore 3348 state. 3349 3350For handle types defined as NT handles, the handles returned by 3351fname:vkGetSemaphoreWin32HandleKHR are owned by the application. 3352To avoid leaking resources, the application must: release ownership of them 3353using the code:CloseHandle system call when they are no longer needed. 3354 3355Exporting a Windows handle from a semaphore may: have side effects depending 3356on the transference of the specified handle type, as described in 3357<<synchronization-semaphores-importing,Importing Semaphore Payloads>>. 3358 3359include::{generated}/validity/protos/vkGetSemaphoreWin32HandleKHR.adoc[] 3360-- 3361 3362[open,refpage='VkSemaphoreGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle semaphore export operation',type='structs'] 3363-- 3364The sname:VkSemaphoreGetWin32HandleInfoKHR structure is defined as: 3365 3366include::{generated}/api/structs/VkSemaphoreGetWin32HandleInfoKHR.adoc[] 3367 3368 * pname:sType is the type of this structure. 3369 * pname:pNext is `NULL` or a pointer to a structure extending this 3370 structure. 3371 * pname:semaphore is the semaphore from which state will be exported. 3372 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 3373 specifying the type of handle requested. 3374 3375The properties of the handle returned depend on the value of 3376pname:handleType. 3377See elink:VkExternalSemaphoreHandleTypeFlagBits for a description of the 3378properties of the defined external semaphore handle types. 3379 3380.Valid Usage 3381**** 3382 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01126]] 3383 pname:handleType must: have been included in 3384 slink:VkExportSemaphoreCreateInfo::pname:handleTypes when the 3385 pname:semaphore's current payload was created 3386 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01127]] 3387 If pname:handleType is defined as an NT handle, 3388 flink:vkGetSemaphoreWin32HandleKHR must: be called no more than once for 3389 each valid unique combination of pname:semaphore and pname:handleType 3390 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-semaphore-01128]] 3391 pname:semaphore must: not currently have its payload replaced by an 3392 imported payload as described below in 3393 <<synchronization-semaphores-importing,Importing Semaphore Payloads>> 3394 unless that imported payload's handle type was included in 3395 slink:VkExternalSemaphoreProperties::pname:exportFromImportedHandleTypes 3396 for pname:handleType 3397 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01129]] 3398 If pname:handleType refers to a handle type with copy payload 3399 transference semantics, as defined below in 3400 <<synchronization-semaphores-importing,Importing Semaphore Payloads>>, 3401 there must: be no queue waiting on pname:semaphore 3402 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01130]] 3403 If pname:handleType refers to a handle type with copy payload 3404 transference semantics, pname:semaphore must: be signaled, or have an 3405 associated <<synchronization-semaphores-signaling,semaphore signal 3406 operation>> pending execution 3407 * [[VUID-VkSemaphoreGetWin32HandleInfoKHR-handleType-01131]] 3408 pname:handleType must: be defined as an NT handle or a global share 3409 handle 3410**** 3411 3412include::{generated}/validity/structs/VkSemaphoreGetWin32HandleInfoKHR.adoc[] 3413-- 3414endif::VK_KHR_external_semaphore_win32[] 3415 3416ifdef::VK_KHR_external_semaphore_fd[] 3417[open,refpage='vkGetSemaphoreFdKHR',desc='Get a POSIX file descriptor handle for a semaphore',type='protos'] 3418-- 3419To export a POSIX file descriptor representing the payload of a semaphore, 3420call: 3421 3422include::{generated}/api/protos/vkGetSemaphoreFdKHR.adoc[] 3423 3424 * pname:device is the logical device that created the semaphore being 3425 exported. 3426 * pname:pGetFdInfo is a pointer to a slink:VkSemaphoreGetFdInfoKHR 3427 structure containing parameters of the export operation. 3428 * pname:pFd will return the file descriptor representing the semaphore 3429 payload. 3430 3431Each call to fname:vkGetSemaphoreFdKHR must: create a new file descriptor 3432and transfer ownership of it to the application. 3433To avoid leaking resources, the application must: release ownership of the 3434file descriptor when it is no longer needed. 3435 3436[NOTE] 3437.Note 3438==== 3439Ownership can be released in many ways. 3440For example, the application can call code:close() on the file descriptor, 3441or transfer ownership back to Vulkan by using the file descriptor to import 3442a semaphore payload. 3443==== 3444Where supported by the operating system, the implementation must: set the 3445file descriptor to be closed automatically when an code:execve system call 3446is made. 3447 3448Exporting a file descriptor from a semaphore may: have side effects 3449depending on the transference of the specified handle type, as described in 3450<<synchronization-semaphores-importing,Importing Semaphore State>>. 3451 3452include::{generated}/validity/protos/vkGetSemaphoreFdKHR.adoc[] 3453-- 3454 3455[open,refpage='VkSemaphoreGetFdInfoKHR',desc='Structure describing a POSIX FD semaphore export operation',type='structs'] 3456-- 3457The sname:VkSemaphoreGetFdInfoKHR structure is defined as: 3458 3459include::{generated}/api/structs/VkSemaphoreGetFdInfoKHR.adoc[] 3460 3461 * pname:sType is the type of this structure. 3462 * pname:pNext is `NULL` or a pointer to a structure extending this 3463 structure. 3464 * pname:semaphore is the semaphore from which state will be exported. 3465 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 3466 specifying the type of handle requested. 3467 3468The properties of the file descriptor returned depend on the value of 3469pname:handleType. 3470See elink:VkExternalSemaphoreHandleTypeFlagBits for a description of the 3471properties of the defined external semaphore handle types. 3472 3473.Valid Usage 3474**** 3475 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-01132]] 3476 pname:handleType must: have been included in 3477 slink:VkExportSemaphoreCreateInfo::pname:handleTypes when 3478 pname:semaphore's current payload was created 3479 * [[VUID-VkSemaphoreGetFdInfoKHR-semaphore-01133]] 3480 pname:semaphore must: not currently have its payload replaced by an 3481 imported payload as described below in 3482 <<synchronization-semaphores-importing,Importing Semaphore Payloads>> 3483 unless that imported payload's handle type was included in 3484 slink:VkExternalSemaphoreProperties::pname:exportFromImportedHandleTypes 3485 for pname:handleType 3486 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-01134]] 3487 If pname:handleType refers to a handle type with copy payload 3488 transference semantics, as defined below in 3489 <<synchronization-semaphores-importing,Importing Semaphore Payloads>>, 3490 there must: be no queue waiting on pname:semaphore 3491 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-01135]] 3492 If pname:handleType refers to a handle type with copy payload 3493 transference semantics, pname:semaphore must: be signaled, or have an 3494 associated <<synchronization-semaphores-signaling,semaphore signal 3495 operation>> pending execution 3496 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-01136]] 3497 pname:handleType must: be defined as a POSIX file descriptor handle 3498ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3499 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-03253]] 3500 If pname:handleType refers to a handle type with copy payload 3501 transference semantics, pname:semaphore must: have been created with a 3502 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 3503 * [[VUID-VkSemaphoreGetFdInfoKHR-handleType-03254]] 3504 If pname:handleType refers to a handle type with copy payload 3505 transference semantics, pname:semaphore must: have an associated 3506 semaphore signal operation that has been submitted for execution and any 3507 semaphore signal operations on which it depends (if any) must: have also 3508 been submitted for execution 3509endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3510**** 3511 3512include::{generated}/validity/structs/VkSemaphoreGetFdInfoKHR.adoc[] 3513-- 3514endif::VK_KHR_external_semaphore_fd[] 3515 3516ifdef::VK_FUCHSIA_external_semaphore[] 3517[open,refpage='vkGetSemaphoreZirconHandleFUCHSIA',desc='Get a Zircon event handle for a semaphore',type='protos'] 3518-- 3519To export a Zircon event handle representing the payload of a semaphore, 3520call: 3521 3522include::{generated}/api/protos/vkGetSemaphoreZirconHandleFUCHSIA.adoc[] 3523 3524 * pname:device is the logical device that created the semaphore being 3525 exported. 3526 * pname:pGetZirconHandleInfo is a pointer to a 3527 slink:VkSemaphoreGetZirconHandleInfoFUCHSIA structure containing 3528 parameters of the export operation. 3529 * pname:pZirconHandle will return the Zircon event handle representing the 3530 semaphore payload. 3531 3532Each call to fname:vkGetSemaphoreZirconHandleFUCHSIA must: create a Zircon 3533event handle and transfer ownership of it to the application. 3534To avoid leaking resources, the application must: release ownership of the 3535Zircon event handle when it is no longer needed. 3536 3537[NOTE] 3538.Note 3539==== 3540Ownership can be released in many ways. 3541For example, the application can call zx_handle_close() on the file 3542descriptor, or transfer ownership back to Vulkan by using the file 3543descriptor to import a semaphore payload. 3544==== 3545 3546Exporting a Zircon event handle from a semaphore may: have side effects 3547depending on the transference of the specified handle type, as described in 3548<<synchronization-semaphores-importing,Importing Semaphore State>>. 3549 3550include::{generated}/validity/protos/vkGetSemaphoreZirconHandleFUCHSIA.adoc[] 3551-- 3552 3553[open,refpage='VkSemaphoreGetZirconHandleInfoFUCHSIA',desc='Structure describing a Zircon event handle semaphore export operation',type='structs'] 3554-- 3555The sname:VkSemaphoreGetZirconHandleInfoFUCHSIA structure is defined as: 3556 3557include::{generated}/api/structs/VkSemaphoreGetZirconHandleInfoFUCHSIA.adoc[] 3558 3559 * pname:sType is the type of this structure. 3560 * pname:pNext is `NULL` or a pointer to a structure extending this 3561 structure. 3562 * pname:semaphore is the semaphore from which state will be exported. 3563 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 3564 specifying the type of handle requested. 3565 3566The properties of the Zircon event handle returned depend on the value of 3567pname:handleType. 3568See elink:VkExternalSemaphoreHandleTypeFlagBits for a description of the 3569properties of the defined external semaphore handle types. 3570 3571.Valid Usage 3572**** 3573 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04758]] 3574 pname:handleType must: have been included in 3575 slink:VkExportSemaphoreCreateInfo::pname:handleTypes when 3576 pname:semaphore's current payload was created 3577 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-semaphore-04759]] 3578 pname:semaphore must: not currently have its payload replaced by an 3579 imported payload as described below in 3580 <<synchronization-semaphores-importing,Importing Semaphore Payloads>> 3581 unless that imported payload's handle type was included in 3582 slink:VkExternalSemaphoreProperties::pname:exportFromImportedHandleTypes 3583 for pname:handleType 3584 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04760]] 3585 If pname:handleType refers to a handle type with copy payload 3586 transference semantics, as defined below in 3587 <<synchronization-semaphores-importing,Importing Semaphore Payloads>>, 3588 there must: be no queue waiting on pname:semaphore 3589 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04761]] 3590 If pname:handleType refers to a handle type with copy payload 3591 transference semantics, pname:semaphore must: be signaled, or have an 3592 associated <<synchronization-semaphores-signaling,semaphore signal 3593 operation>> pending execution 3594 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-handleType-04762]] 3595 pname:handleType must: be defined as a Zircon event handle 3596 * [[VUID-VkSemaphoreGetZirconHandleInfoFUCHSIA-semaphore-04763]] 3597 pname:semaphore must: have been created with a elink:VkSemaphoreType of 3598 ename:VK_SEMAPHORE_TYPE_BINARY 3599**** 3600 3601include::{generated}/validity/structs/VkSemaphoreGetZirconHandleInfoFUCHSIA.adoc[] 3602-- 3603endif::VK_FUCHSIA_external_semaphore[] 3604 3605[open,refpage='vkDestroySemaphore',desc='Destroy a semaphore object',type='protos'] 3606-- 3607To destroy a semaphore, call: 3608 3609include::{generated}/api/protos/vkDestroySemaphore.adoc[] 3610 3611 * pname:device is the logical device that destroys the semaphore. 3612 * pname:semaphore is the handle of the semaphore to destroy. 3613 * pname:pAllocator controls host memory allocation as described in the 3614 <<memory-allocation, Memory Allocation>> chapter. 3615 3616.Valid Usage 3617**** 3618 * [[VUID-vkDestroySemaphore-semaphore-01137]] 3619 All submitted batches that refer to pname:semaphore must: have completed 3620 execution 3621 * [[VUID-vkDestroySemaphore-semaphore-01138]] 3622 If sname:VkAllocationCallbacks were provided when pname:semaphore was 3623 created, a compatible set of callbacks must: be provided here 3624 * [[VUID-vkDestroySemaphore-semaphore-01139]] 3625 If no sname:VkAllocationCallbacks were provided when pname:semaphore was 3626 created, pname:pAllocator must: be `NULL` 3627**** 3628 3629include::{generated}/validity/protos/vkDestroySemaphore.adoc[] 3630-- 3631 3632 3633[[synchronization-semaphores-signaling]] 3634=== Semaphore Signaling 3635 3636When a batch is submitted to a queue via a <<devsandqueues-submission, queue 3637submission>>, and it includes semaphores to be signaled, it defines a memory 3638dependency on the batch, and defines _semaphore signal operations_ which set 3639the semaphores to the signaled state. 3640 3641ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3642In case of semaphores created with a elink:VkSemaphoreType of 3643ename:VK_SEMAPHORE_TYPE_TIMELINE the semaphore is considered signaled with 3644respect to the counter value set to be signaled as specified in 3645slink:VkTimelineSemaphoreSubmitInfo or slink:VkSemaphoreSignalInfo. 3646endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3647 3648The first <<synchronization-dependencies-scopes, synchronization scope>> 3649includes every command submitted in the same batch. 3650ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3651In the case of flink:vkQueueSubmit2, the first synchronization scope is 3652limited to the pipeline stage specified by 3653slink:VkSemaphoreSubmitInfo::pname:stageMask. 3654endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3655Semaphore signal operations that are defined by flink:vkQueueSubmit 3656ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3657or flink:vkQueueSubmit2 3658endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3659additionally include all commands that occur earlier in 3660<<synchronization-submission-order,submission order>>. 3661Semaphore signal operations that are defined by flink:vkQueueSubmit 3662ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3663, flink:vkQueueSubmit2 3664endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3665or flink:vkQueueBindSparse additionally include in the first synchronization 3666scope any semaphore and fence signal operations that occur earlier in 3667<<synchronization-signal-operation-order,signal operation order>>. 3668 3669The second <<synchronization-dependencies-scopes, synchronization scope>> 3670includes only the semaphore signal operation. 3671 3672The first <<synchronization-dependencies-access-scopes, access scope>> 3673includes all memory access performed by the device. 3674 3675The second <<synchronization-dependencies-access-scopes, access scope>> is 3676empty. 3677 3678 3679[[synchronization-semaphores-waiting]] 3680=== Semaphore Waiting 3681 3682When a batch is submitted to a queue via a <<devsandqueues-submission, queue 3683submission>>, and it includes semaphores to be waited on, it defines a 3684memory dependency between prior semaphore signal operations and the batch, 3685and defines _semaphore wait operations_. 3686 3687Such semaphore wait operations set the semaphores 3688ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3689created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 3690endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3691to the unsignaled state. 3692ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3693In case of semaphores created with a elink:VkSemaphoreType of 3694ename:VK_SEMAPHORE_TYPE_TIMELINE a prior semaphore signal operation defines 3695a memory dependency with a semaphore wait operation if the value the 3696semaphore is signaled with is greater than or equal to the value the 3697semaphore is waited with, thus the semaphore will continue to be considered 3698signaled with respect to the counter value waited on as specified in 3699slink:VkTimelineSemaphoreSubmitInfo. 3700endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3701 3702The first synchronization scope includes all semaphore signal operations 3703that operate on semaphores waited on in the same batch, and that 3704happen-before the wait completes. 3705 3706The second <<synchronization-dependencies-scopes, synchronization scope>> 3707includes every command submitted in the same batch. 3708In the case of flink:vkQueueSubmit, the second synchronization scope is 3709limited to operations on the pipeline stages determined by the 3710<<synchronization-pipeline-stages-masks, destination stage mask>> specified 3711by the corresponding element of pname:pWaitDstStageMask. 3712ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3713In the case of flink:vkQueueSubmit2, the second synchronization scope is 3714limited to the pipeline stage specified by 3715slink:VkSemaphoreSubmitInfo::pname:stageMask. 3716endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3717Also, in the case of 3718ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3719either flink:vkQueueSubmit2 or 3720endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3721flink:vkQueueSubmit, the second synchronization scope additionally includes 3722all commands that occur later in 3723<<synchronization-submission-order,submission order>>. 3724 3725The first <<synchronization-dependencies-access-scopes, access scope>> is 3726empty. 3727 3728The second <<synchronization-dependencies-access-scopes, access scope>> 3729includes all memory access performed by the device. 3730 3731The semaphore wait operation happens-after the first set of operations in 3732the execution dependency, and happens-before the second set of operations in 3733the execution dependency. 3734 3735[NOTE] 3736.Note 3737==== 3738Unlike 3739ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3740timeline semaphores, 3741endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3742fences or events, the act of waiting for a binary semaphore also unsignals 3743that semaphore. 3744Applications must: ensure that between two such wait operations, the 3745semaphore is signaled again, with execution dependencies used to ensure 3746these occur in order. 3747Binary semaphore waits and signals should thus occur in discrete 1:1 pairs. 3748==== 3749 3750ifdef::VK_KHR_swapchain[] 3751[NOTE] 3752.Note 3753==== 3754A common scenario for using pname:pWaitDstStageMask with values other than 3755ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is when synchronizing a window 3756system presentation operation against subsequent command buffers which 3757render the next frame. 3758In this case, a presentation image must: not be overwritten until the 3759presentation operation completes, but other pipeline stages can: execute 3760without waiting. 3761A mask of ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT prevents 3762subsequent color attachment writes from executing until the semaphore 3763signals. 3764Some implementations may: be able to execute transfer operations and/or 3765pre-rasterization work before the semaphore is signaled. 3766 3767If an image layout transition needs to be performed on a presentable image 3768before it is used in a framebuffer, that can: be performed as the first 3769operation submitted to the queue after acquiring the image, and should: not 3770prevent other work from overlapping with the presentation operation. 3771For example, a sname:VkImageMemoryBarrier could use: 3772 3773 * pname:srcStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 3774 * pname:srcAccessMask = 0 3775 * pname:dstStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 3776 * pname:dstAccessMask = ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | 3777 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 3778 * pname:oldLayout = ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 3779 * pname:newLayout = ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 3780 3781Alternatively, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if 3782the image's contents need not be preserved. 3783 3784This barrier accomplishes a dependency chain between previous presentation 3785operations and subsequent color attachment output operations, with the 3786layout transition performed in between, and does not introduce a dependency 3787between previous work and any 3788<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 3789stage>>s. 3790More precisely, the semaphore signals after the presentation operation 3791completes, the semaphore wait stalls the 3792ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage, and there is a 3793dependency from that same stage to itself with the layout transition 3794performed in between. 3795==== 3796endif::VK_KHR_swapchain[] 3797 3798 3799[[synchronization-semaphores-waiting-state]] 3800=== Semaphore State Requirements For Wait Operations 3801 3802Before waiting on a semaphore, the application must: ensure the semaphore is 3803in a valid state for a wait operation. 3804Specifically, when a <<synchronization-semaphores-waiting,semaphore wait 3805operation>> is submitted to a queue: 3806 3807 * A binary semaphore must: be signaled, or have an associated 3808 <<synchronization-semaphores-signaling,semaphore signal operation>> that 3809 is pending execution. 3810 * Any <<synchronization-semaphores-signaling,semaphore signal operations>> 3811 on which the pending binary semaphore signal operation depends must: 3812 also be completed or pending execution. 3813 * There must: be no other queue waiting on the same binary semaphore when 3814 the operation executes. 3815 3816 3817ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 3818[[synchronization-semaphores-hostops]] 3819=== Host Operations on Semaphores 3820 3821In addition to <<synchronization-semaphores-signaling,semaphore signal 3822operations>> and <<synchronization-semaphores-waiting,semaphore wait 3823operations>> submitted to device queues, timeline semaphores support the 3824following host operations: 3825 3826 * Query the current counter value of the semaphore using the 3827 flink:vkGetSemaphoreCounterValue command. 3828 * Wait for a set of semaphores to reach particular counter values using 3829 the flink:vkWaitSemaphores command. 3830 * Signal the semaphore with a particular counter value from the host using 3831 the flink:vkSignalSemaphore command. 3832 3833[open,refpage='vkGetSemaphoreCounterValue',desc='Query the current state of a timeline semaphore',type='protos',alias='vkGetSemaphoreCounterValueKHR'] 3834-- 3835To query the current counter value of a semaphore created with a 3836elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE from the host, 3837call: 3838 3839ifdef::VK_VERSION_1_2[] 3840include::{generated}/api/protos/vkGetSemaphoreCounterValue.adoc[] 3841endif::VK_VERSION_1_2[] 3842 3843ifdef::VK_VERSION_1_2+VK_KHR_timeline_semaphore[or the equivalent command] 3844 3845ifdef::VK_KHR_timeline_semaphore[] 3846include::{generated}/api/protos/vkGetSemaphoreCounterValueKHR.adoc[] 3847endif::VK_KHR_timeline_semaphore[] 3848 3849 * pname:device is the logical device that owns the semaphore. 3850 * pname:semaphore is the handle of the semaphore to query. 3851 * pname:pValue is a pointer to a 64-bit integer value in which the current 3852 counter value of the semaphore is returned. 3853 3854[NOTE] 3855.Note 3856==== 3857If a <<devsandqueues-submission, queue submission>> command is pending 3858execution, then the value returned by this command may: immediately be out 3859of date. 3860==== 3861 3862.Valid Usage 3863**** 3864 * [[VUID-vkGetSemaphoreCounterValue-semaphore-03255]] 3865 pname:semaphore must: have been created with a elink:VkSemaphoreType of 3866 ename:VK_SEMAPHORE_TYPE_TIMELINE 3867**** 3868 3869include::{generated}/validity/protos/vkGetSemaphoreCounterValue.adoc[] 3870-- 3871 3872[open,refpage='vkWaitSemaphores',desc='Wait for timeline semaphores on the host',type='protos',alias='vkWaitSemaphoresKHR'] 3873-- 3874To wait for a set of semaphores created with a elink:VkSemaphoreType of 3875ename:VK_SEMAPHORE_TYPE_TIMELINE to reach particular counter values on the 3876host, call: 3877 3878ifdef::VK_VERSION_1_2[] 3879include::{generated}/api/protos/vkWaitSemaphores.adoc[] 3880endif::VK_VERSION_1_2[] 3881 3882ifdef::VK_VERSION_1_2+VK_KHR_timeline_semaphore[or the equivalent command] 3883 3884ifdef::VK_KHR_timeline_semaphore[] 3885include::{generated}/api/protos/vkWaitSemaphoresKHR.adoc[] 3886endif::VK_KHR_timeline_semaphore[] 3887 3888 * pname:device is the logical device that owns the semaphores. 3889 * pname:pWaitInfo is a pointer to a slink:VkSemaphoreWaitInfo structure 3890 containing information about the wait condition. 3891 * pname:timeout is the timeout period in units of nanoseconds. 3892 pname:timeout is adjusted to the closest value allowed by the 3893 implementation-dependent timeout accuracy, which may: be substantially 3894 longer than one nanosecond, and may: be longer than the requested 3895 period. 3896 3897If the condition is satisfied when fname:vkWaitSemaphores is called, then 3898fname:vkWaitSemaphores returns immediately. 3899If the condition is not satisfied at the time fname:vkWaitSemaphores is 3900called, then fname:vkWaitSemaphores will block and wait until the condition 3901is satisfied or the pname:timeout has expired, whichever is sooner. 3902 3903If pname:timeout is zero, then fname:vkWaitSemaphores does not wait, but 3904simply returns information about the current state of the semaphores. 3905ename:VK_TIMEOUT will be returned in this case if the condition is not 3906satisfied, even though no actual wait was performed. 3907 3908If the condition is satisfied before the pname:timeout has expired, 3909fname:vkWaitSemaphores returns ename:VK_SUCCESS. 3910Otherwise, fname:vkWaitSemaphores returns ename:VK_TIMEOUT after the 3911pname:timeout has expired. 3912 3913If device loss occurs (see <<devsandqueues-lost-device,Lost Device>>) before 3914the timeout has expired, fname:vkWaitSemaphores must: return in finite time 3915with either ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. 3916 3917include::{generated}/validity/protos/vkWaitSemaphores.adoc[] 3918-- 3919 3920[open,refpage='VkSemaphoreWaitInfo',desc='Structure containing information about the semaphore wait condition',type='structs',alias='VkSemaphoreWaitInfoKHR'] 3921-- 3922The sname:VkSemaphoreWaitInfo structure is defined as: 3923 3924include::{generated}/api/structs/VkSemaphoreWaitInfo.adoc[] 3925 3926ifdef::VK_KHR_timeline_semaphore[] 3927or the equivalent 3928 3929include::{generated}/api/structs/VkSemaphoreWaitInfoKHR.adoc[] 3930endif::VK_KHR_timeline_semaphore[] 3931 3932 * pname:sType is the type of this structure. 3933 * pname:pNext is `NULL` or a pointer to a structure extending this 3934 structure. 3935 * pname:flags is a bitmask of elink:VkSemaphoreWaitFlagBits specifying 3936 additional parameters for the semaphore wait operation. 3937 * pname:semaphoreCount is the number of semaphores to wait on. 3938 * pname:pSemaphores is a pointer to an array of pname:semaphoreCount 3939 semaphore handles to wait on. 3940 * pname:pValues is a pointer to an array of pname:semaphoreCount timeline 3941 semaphore values. 3942 3943.Valid Usage 3944**** 3945 * [[VUID-VkSemaphoreWaitInfo-pSemaphores-03256]] 3946 All of the elements of pname:pSemaphores must: reference a semaphore 3947 that was created with a elink:VkSemaphoreType of 3948 ename:VK_SEMAPHORE_TYPE_TIMELINE 3949**** 3950 3951include::{generated}/validity/structs/VkSemaphoreWaitInfo.adoc[] 3952-- 3953 3954[open,refpage='VkSemaphoreWaitFlagBits',desc='Bitmask specifying additional parameters of a semaphore wait operation',type='enums',alias='VkSemaphoreWaitFlagBitsKHR'] 3955-- 3956Bits which can: be set in slink:VkSemaphoreWaitInfo::pname:flags, specifying 3957additional parameters of a semaphore wait operation, are: 3958 3959include::{generated}/api/enums/VkSemaphoreWaitFlagBits.adoc[] 3960 3961ifdef::VK_KHR_timeline_semaphore[] 3962or the equivalent 3963 3964include::{generated}/api/enums/VkSemaphoreWaitFlagBitsKHR.adoc[] 3965endif::VK_KHR_timeline_semaphore[] 3966 3967 * ename:VK_SEMAPHORE_WAIT_ANY_BIT specifies that the semaphore wait 3968 condition is that at least one of the semaphores in 3969 sname:VkSemaphoreWaitInfo::pname:pSemaphores has reached the value 3970 specified by the corresponding element of 3971 sname:VkSemaphoreWaitInfo::pname:pValues. 3972 If ename:VK_SEMAPHORE_WAIT_ANY_BIT is not set, the semaphore wait 3973 condition is that all of the semaphores in 3974 sname:VkSemaphoreWaitInfo::pname:pSemaphores have reached the value 3975 specified by the corresponding element of 3976 sname:VkSemaphoreWaitInfo::pname:pValues. 3977-- 3978 3979[open,refpage='VkSemaphoreWaitFlags',desc='Bitmask of VkSemaphoreWaitFlagBits',type='flags',alias='VkSemaphoreWaitFlagsKHR'] 3980-- 3981include::{generated}/api/flags/VkSemaphoreWaitFlags.adoc[] 3982 3983ifdef::VK_KHR_timeline_semaphore[] 3984or the equivalent 3985 3986include::{generated}/api/flags/VkSemaphoreWaitFlagsKHR.adoc[] 3987endif::VK_KHR_timeline_semaphore[] 3988 3989tname:VkSemaphoreWaitFlags is a bitmask type for setting a mask of zero or 3990more elink:VkSemaphoreWaitFlagBits. 3991-- 3992 3993[open,refpage='vkSignalSemaphore',desc='Signal a timeline semaphore on the host',type='protos',alias='vkSignalSemaphoreKHR'] 3994-- 3995To signal a semaphore created with a elink:VkSemaphoreType of 3996ename:VK_SEMAPHORE_TYPE_TIMELINE with a particular counter value, on the 3997host, call: 3998 3999ifdef::VK_VERSION_1_2[] 4000include::{generated}/api/protos/vkSignalSemaphore.adoc[] 4001endif::VK_VERSION_1_2[] 4002 4003ifdef::VK_VERSION_1_2+VK_KHR_timeline_semaphore[or the equivalent command] 4004 4005ifdef::VK_KHR_timeline_semaphore[] 4006include::{generated}/api/protos/vkSignalSemaphoreKHR.adoc[] 4007endif::VK_KHR_timeline_semaphore[] 4008 4009 * pname:device is the logical device that owns the semaphore. 4010 * pname:pSignalInfo is a pointer to a slink:VkSemaphoreSignalInfo 4011 structure containing information about the signal operation. 4012 4013When fname:vkSignalSemaphore is executed on the host, it defines and 4014immediately executes a <<synchronization-semaphores-signaling,_semaphore 4015signal operation_>> which sets the timeline semaphore to the given value. 4016 4017The first synchronization scope is defined by the host execution model, but 4018includes execution of fname:vkSignalSemaphore on the host and anything that 4019happened-before it. 4020 4021The second synchronization scope is empty. 4022 4023include::{generated}/validity/protos/vkSignalSemaphore.adoc[] 4024-- 4025 4026[open,refpage='VkSemaphoreSignalInfo',desc='Structure containing information about a semaphore signal operation',type='structs',alias='VkSemaphoreSignalInfoKHR'] 4027-- 4028The sname:VkSemaphoreSignalInfo structure is defined as: 4029 4030include::{generated}/api/structs/VkSemaphoreSignalInfo.adoc[] 4031 4032ifdef::VK_KHR_timeline_semaphore[] 4033or the equivalent 4034 4035include::{generated}/api/structs/VkSemaphoreSignalInfoKHR.adoc[] 4036endif::VK_KHR_timeline_semaphore[] 4037 4038 * pname:sType is the type of this structure. 4039 * pname:pNext is `NULL` or a pointer to a structure extending this 4040 structure. 4041 * pname:semaphore is the handle of the semaphore to signal. 4042 * pname:value is the value to signal. 4043 4044.Valid Usage 4045**** 4046 * [[VUID-VkSemaphoreSignalInfo-semaphore-03257]] 4047 pname:semaphore must: have been created with a elink:VkSemaphoreType of 4048 ename:VK_SEMAPHORE_TYPE_TIMELINE 4049 * [[VUID-VkSemaphoreSignalInfo-value-03258]] 4050 pname:value must: have a value greater than the current value of the 4051 semaphore 4052 * [[VUID-VkSemaphoreSignalInfo-value-03259]] 4053 pname:value must: be less than the value of any pending semaphore signal 4054 operations 4055 * [[VUID-VkSemaphoreSignalInfo-value-03260]] 4056 pname:value must: have a value which does not differ from the current 4057 value of the semaphore or the value of any outstanding semaphore wait or 4058 signal operation on pname:semaphore by more than 4059 <<limits-maxTimelineSemaphoreValueDifference, 4060 pname:maxTimelineSemaphoreValueDifference>> 4061**** 4062 4063include::{generated}/validity/structs/VkSemaphoreSignalInfo.adoc[] 4064-- 4065endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4066 4067 4068ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 4069[[synchronization-semaphores-importing]] 4070=== Importing Semaphore Payloads 4071 4072Applications can: import a semaphore payload into an existing semaphore 4073using an external semaphore handle. 4074The effects of the import operation will be either temporary or permanent, 4075as specified by the application. 4076If the import is temporary, the implementation must: restore the semaphore 4077to its prior permanent state after submitting the next semaphore wait 4078operation. 4079Performing a subsequent temporary import on a semaphore before performing a 4080semaphore wait has no effect on this requirement; the next wait submitted on 4081the semaphore must: still restore its last permanent state. 4082A permanent payload import behaves as if the target semaphore was destroyed, 4083and a new semaphore was created with the same handle but the imported 4084payload. 4085Because importing a semaphore payload temporarily or permanently detaches 4086the existing payload from a semaphore, similar usage restrictions to those 4087applied to fname:vkDestroySemaphore are applied to any command that imports 4088a semaphore payload. 4089Which of these import types is used is referred to as the import operation's 4090_permanence_. 4091Each handle type supports either one or both types of permanence. 4092 4093The implementation must: perform the import operation by either referencing 4094or copying the payload referred to by the specified external semaphore 4095handle, depending on the handle's type. 4096The import method used is referred to as the handle type's _transference_. 4097When using handle types with reference transference, importing a payload to 4098a semaphore adds the semaphore to the set of all semaphores sharing that 4099payload. 4100This set includes the semaphore from which the payload was exported. 4101Semaphore signaling and waiting operations performed on any semaphore in the 4102set must: behave as if the set were a single semaphore. 4103Importing a payload using handle types with copy transference creates a 4104duplicate copy of the payload at the time of import, but makes no further 4105reference to it. 4106Semaphore signaling and waiting operations performed on the target of copy 4107imports must: not affect any other semaphore or payload. 4108 4109Export operations have the same transference as the specified handle type's 4110import operations. 4111Additionally, exporting a semaphore payload to a handle with copy 4112transference has the same side effects on the source semaphore's payload as 4113executing a semaphore wait operation. 4114If the semaphore was using a temporarily imported payload, the semaphore's 4115prior permanent payload will be restored. 4116 4117ifdef::VK_KHR_external_semaphore_win32,VK_KHR_external_semaphore_fd,VK_FUCHSIA_external_semaphore[] 4118[NOTE] 4119.Note 4120==== 4121The permanence and transference of handle types can be found in: 4122 4123ifdef::VK_KHR_external_semaphore_win32[] 4124 * <<synchronization-semaphore-handletypes-win32,Handle Types Supported by 4125 sname:VkImportSemaphoreWin32HandleInfoKHR>> 4126endif::VK_KHR_external_semaphore_win32[] 4127ifdef::VK_KHR_external_semaphore_fd[] 4128 * <<synchronization-semaphore-handletypes-fd,Handle Types Supported by 4129 sname:VkImportSemaphoreFdInfoKHR>> 4130endif::VK_KHR_external_semaphore_fd[] 4131ifdef::VK_FUCHSIA_external_semaphore[] 4132 * <<synchronization-semaphore-handletypes-fuchsia,Handle Types Supported 4133 by sname:VkImportSemaphoreZirconHandleInfoFUCHSIA>> 4134endif::VK_FUCHSIA_external_semaphore[] 4135==== 4136endif::VK_KHR_external_semaphore_win32,VK_KHR_external_semaphore_fd,VK_FUCHSIA_external_semaphore[] 4137 4138<<fundamentals-threadingbehavior,External synchronization>> allows 4139implementations to modify an object's internal state, i.e. payload, without 4140internal synchronization. 4141However, for semaphores sharing a payload across processes, satisfying the 4142external synchronization requirements of sname:VkSemaphore parameters as if 4143all semaphores in the set were the same object is sometimes infeasible. 4144Satisfying the <<synchronization-semaphores-waiting-state,wait operation 4145state requirements>> would similarly require impractical coordination or 4146levels of trust between processes. 4147Therefore, these constraints only apply to a specific semaphore handle, not 4148to its payload. 4149For distinct semaphore objects which share a payload, if the semaphores are 4150passed to separate queue submission commands concurrently, behavior will be 4151as if the commands were called in an arbitrary sequential order. 4152If the <<synchronization-semaphores-waiting-state,wait operation state 4153requirements>> are violated for the shared payload by a queue submission 4154command, or if a signal operation is queued for a shared payload that is 4155already signaled or has a pending signal operation, effects must: be limited 4156to one or more of the following: 4157 4158 * Returning ename:VK_ERROR_INITIALIZATION_FAILED from the command which 4159 resulted in the violation. 4160 * Losing the logical device on which the violation occurred immediately or 4161 at a future time, resulting in a ename:VK_ERROR_DEVICE_LOST error from 4162 subsequent commands, including the one causing the violation. 4163 * Continuing execution of the violating command or operation as if the 4164 semaphore wait completed successfully after an implementation-dependent 4165 timeout. 4166 In this case, the state of the payload becomes undefined:, and future 4167 operations on semaphores sharing the payload will be subject to these 4168 same rules. 4169 The semaphore must: be destroyed or have its payload replaced by an 4170 import operation to again have a well-defined state. 4171 4172[NOTE] 4173.Note 4174==== 4175These rules allow processes to synchronize access to shared memory without 4176trusting each other. 4177However, such processes must still be cautious not to use the shared 4178semaphore for more than synchronizing access to the shared memory. 4179For example, a process should not use a shared semaphore as part of an 4180execution dependency chain that, when complete, leads to objects being 4181destroyed, if it does not trust other processes sharing the semaphore 4182payload. 4183==== 4184 4185When a semaphore is using an imported payload, its 4186slink:VkExportSemaphoreCreateInfo::pname:handleTypes value is specified when 4187creating the semaphore from which the payload was exported, rather than 4188specified when creating the semaphore. 4189Additionally, 4190slink:VkExternalSemaphoreProperties::pname:exportFromImportedHandleTypes 4191restricts which handle types can: be exported from such a semaphore based on 4192the specific handle type used to import the current payload. 4193ifdef::VK_KHR_swapchain[] 4194Passing a semaphore to flink:vkAcquireNextImageKHR is equivalent to 4195temporarily importing a semaphore payload to that semaphore. 4196 4197[NOTE] 4198.Note 4199==== 4200Because the exportable handle types of an imported semaphore correspond to 4201its current imported payload, and flink:vkAcquireNextImageKHR behaves the 4202same as a temporary import operation for which the source semaphore is 4203opaque to the application, applications have no way of determining whether 4204any external handle types can: be exported from a semaphore in this state. 4205Therefore, applications must: not attempt to export external handles from 4206semaphores using a temporarily imported payload from 4207flink:vkAcquireNextImageKHR. 4208==== 4209endif::VK_KHR_swapchain[] 4210 4211When importing a semaphore payload, it is the responsibility of the 4212application to ensure the external handles meet all valid usage 4213requirements. 4214However, implementations must: perform sufficient validation of external 4215handles to ensure that the operation results in a valid semaphore which will 4216not cause program termination, device loss, queue stalls, or corruption of 4217other resources when used as allowed according to its import parameters, and 4218excepting those side effects allowed for violations of the 4219<<synchronization-semaphores-waiting-state,valid semaphore state for wait 4220operations>> rules. 4221If the external handle provided does not meet these requirements, the 4222implementation must: fail the semaphore payload import operation with the 4223error code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. 4224 4225ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4226In addition, when importing a semaphore payload that is not compatible with 4227the payload type corresponding to the elink:VkSemaphoreType the semaphore 4228was created with, the implementation may: fail the semaphore payload import 4229operation with the error code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. 4230 4231[NOTE] 4232.Note 4233==== 4234As the introduction of the external semaphore handle type 4235ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of 4236timeline semaphores, support for importing semaphore payloads from external 4237handles of that type into semaphores created (implicitly or explicitly) with 4238a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for 4239backwards compatibility. 4240However, applications should: prefer importing such handle types into 4241semaphores created with a elink:VkSemaphoreType of 4242ename:VK_SEMAPHORE_TYPE_TIMELINE. 4243==== 4244endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4245endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 4246 4247ifdef::VK_KHR_external_semaphore_win32[] 4248[open,refpage='vkImportSemaphoreWin32HandleKHR',desc='Import a semaphore from a Windows HANDLE',type='protos'] 4249-- 4250To import a semaphore payload from a Windows handle, call: 4251 4252include::{generated}/api/protos/vkImportSemaphoreWin32HandleKHR.adoc[] 4253 4254 * pname:device is the logical device that created the semaphore. 4255 * pname:pImportSemaphoreWin32HandleInfo is a pointer to a 4256 slink:VkImportSemaphoreWin32HandleInfoKHR structure specifying the 4257 semaphore and import parameters. 4258 4259Importing a semaphore payload from Windows handles does not transfer 4260ownership of the handle to the Vulkan implementation. 4261For handle types defined as NT handles, the application must: release 4262ownership using the code:CloseHandle system call when the handle is no 4263longer needed. 4264 4265Applications can: import the same semaphore payload into multiple instances 4266of Vulkan, into the same instance from which it was exported, and multiple 4267times into a given Vulkan instance. 4268 4269include::{generated}/validity/protos/vkImportSemaphoreWin32HandleKHR.adoc[] 4270-- 4271 4272[open,refpage='VkImportSemaphoreWin32HandleInfoKHR',desc='Structure specifying Windows handle to import to a semaphore',type='structs'] 4273-- 4274The sname:VkImportSemaphoreWin32HandleInfoKHR structure is defined as: 4275 4276include::{generated}/api/structs/VkImportSemaphoreWin32HandleInfoKHR.adoc[] 4277 4278 * pname:sType is the type of this structure. 4279 * pname:pNext is `NULL` or a pointer to a structure extending this 4280 structure. 4281 * pname:semaphore is the semaphore into which the payload will be 4282 imported. 4283 * pname:flags is a bitmask of elink:VkSemaphoreImportFlagBits specifying 4284 additional parameters for the semaphore payload import operation. 4285 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 4286 specifying the type of pname:handle. 4287 * pname:handle is `NULL` or the external handle to import. 4288 * pname:name is `NULL` or a null-terminated UTF-16 string naming the 4289 underlying synchronization primitive to import. 4290 4291The handle types supported by pname:handleType are: 4292 4293[[synchronization-semaphore-handletypes-win32]] 4294.Handle Types Supported by sname:VkImportSemaphoreWin32HandleInfoKHR 4295[width="80%",options="header"] 4296|==== 4297| Handle Type | Transference | Permanence Supported 4298| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Reference | Temporary,Permanent 4299| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Reference | Temporary,Permanent 4300| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT | Reference | Temporary,Permanent 4301|==== 4302 4303.Valid Usage 4304**** 4305 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01140]] 4306 pname:handleType must: be a value included in the 4307 <<synchronization-semaphore-handletypes-win32,Handle Types Supported by 4308 sname:VkImportSemaphoreWin32HandleInfoKHR>> table 4309 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01466]] 4310 If pname:handleType is not 4311 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or 4312 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT, pname:name 4313 must: be `NULL` 4314 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01467]] 4315 If pname:handle is `NULL`, pname:name must: name a valid synchronization 4316 primitive of the type specified by pname:handleType 4317 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-01468]] 4318 If pname:name is `NULL`, pname:handle must: be a valid handle of the 4319 type specified by pname:handleType 4320 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handle-01469]] 4321 If pname:handle is not `NULL`, pname:name must: be `NULL` 4322 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handle-01542]] 4323 If pname:handle is not `NULL`, it must: obey any requirements listed for 4324 pname:handleType in 4325 <<external-semaphore-handle-types-compatibility,external semaphore 4326 handle types compatibility>> 4327 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-name-01543]] 4328 If pname:name is not `NULL`, it must: obey any requirements listed for 4329 pname:handleType in 4330 <<external-semaphore-handle-types-compatibility,external semaphore 4331 handle types compatibility>> 4332 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-03261]] 4333 If pname:handleType is 4334 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or 4335 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the 4336 slink:VkSemaphoreCreateInfo::pname:flags field must: match that of the 4337 semaphore from which pname:handle or pname:name was exported 4338ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4339 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-handleType-03262]] 4340 If pname:handleType is 4341 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT or 4342 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, the 4343 slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType field must: match 4344 that of the semaphore from which pname:handle or pname:name was exported 4345 * [[VUID-VkImportSemaphoreWin32HandleInfoKHR-flags-03322]] 4346 If pname:flags contains ename:VK_SEMAPHORE_IMPORT_TEMPORARY_BIT, the 4347 slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType field of the 4348 semaphore from which pname:handle or pname:name was exported must: not 4349 be ename:VK_SEMAPHORE_TYPE_TIMELINE 4350endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4351**** 4352 4353include::{generated}/validity/structs/VkImportSemaphoreWin32HandleInfoKHR.adoc[] 4354-- 4355endif::VK_KHR_external_semaphore_win32[] 4356 4357ifdef::VK_KHR_external_semaphore_fd[] 4358[open,refpage='vkImportSemaphoreFdKHR',desc='Import a semaphore from a POSIX file descriptor',type='protos'] 4359-- 4360To import a semaphore payload from a POSIX file descriptor, call: 4361 4362include::{generated}/api/protos/vkImportSemaphoreFdKHR.adoc[] 4363 4364 * pname:device is the logical device that created the semaphore. 4365 * pname:pImportSemaphoreFdInfo is a pointer to a 4366 slink:VkImportSemaphoreFdInfoKHR structure specifying the semaphore and 4367 import parameters. 4368 4369Importing a semaphore payload from a file descriptor transfers ownership of 4370the file descriptor from the application to the Vulkan implementation. 4371The application must: not perform any operations on the file descriptor 4372after a successful import. 4373 4374Applications can: import the same semaphore payload into multiple instances 4375of Vulkan, into the same instance from which it was exported, and multiple 4376times into a given Vulkan instance. 4377 4378.Valid Usage 4379**** 4380 * [[VUID-vkImportSemaphoreFdKHR-semaphore-01142]] 4381 pname:semaphore must: not be associated with any queue command that has 4382 not yet completed execution on that queue 4383**** 4384 4385include::{generated}/validity/protos/vkImportSemaphoreFdKHR.adoc[] 4386-- 4387 4388[open,refpage='VkImportSemaphoreFdInfoKHR',desc='Structure specifying POSIX file descriptor to import to a semaphore',type='structs'] 4389-- 4390The sname:VkImportSemaphoreFdInfoKHR structure is defined as: 4391 4392include::{generated}/api/structs/VkImportSemaphoreFdInfoKHR.adoc[] 4393 4394 * pname:sType is the type of this structure. 4395 * pname:pNext is `NULL` or a pointer to a structure extending this 4396 structure. 4397 * pname:semaphore is the semaphore into which the payload will be 4398 imported. 4399 * pname:flags is a bitmask of elink:VkSemaphoreImportFlagBits specifying 4400 additional parameters for the semaphore payload import operation. 4401 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 4402 specifying the type of pname:fd. 4403 * pname:fd is the external handle to import. 4404 4405The handle types supported by pname:handleType are: 4406 4407[[synchronization-semaphore-handletypes-fd]] 4408.Handle Types Supported by sname:VkImportSemaphoreFdInfoKHR 4409[width="80%",options="header"] 4410|==== 4411| Handle Type | Transference | Permanence Supported 4412| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT | Reference | Temporary,Permanent 4413| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT | Copy | Temporary 4414|==== 4415 4416.Valid Usage 4417**** 4418 * [[VUID-VkImportSemaphoreFdInfoKHR-handleType-01143]] 4419 pname:handleType must: be a value included in the 4420 <<synchronization-semaphore-handletypes-fd,Handle Types Supported by 4421 sname:VkImportSemaphoreFdInfoKHR>> table 4422 * [[VUID-VkImportSemaphoreFdInfoKHR-fd-01544]] 4423 pname:fd must: obey any requirements listed for pname:handleType in 4424 <<external-semaphore-handle-types-compatibility,external semaphore 4425 handle types compatibility>> 4426 * [[VUID-VkImportSemaphoreFdInfoKHR-handleType-03263]] 4427 If pname:handleType is 4428 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the 4429 slink:VkSemaphoreCreateInfo::pname:flags field must: match that of the 4430 semaphore from which pname:fd was exported 4431 * [[VUID-VkImportSemaphoreFdInfoKHR-handleType-07307]] 4432 If pname:handleType refers to a handle type with copy payload 4433 transference semantics, pname:flags must: contain 4434 ename:VK_SEMAPHORE_IMPORT_TEMPORARY_BIT 4435ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4436 * [[VUID-VkImportSemaphoreFdInfoKHR-handleType-03264]] 4437 If pname:handleType is 4438 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the 4439 slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType field must: match 4440 that of the semaphore from which pname:fd was exported 4441 * [[VUID-VkImportSemaphoreFdInfoKHR-flags-03323]] 4442 If pname:flags contains ename:VK_SEMAPHORE_IMPORT_TEMPORARY_BIT, the 4443 slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType field of the 4444 semaphore from which pname:fd was exported must: not be 4445 ename:VK_SEMAPHORE_TYPE_TIMELINE 4446endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4447**** 4448 4449If pname:handleType is ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT, 4450the special value `-1` for pname:fd is treated like a valid sync file 4451descriptor referring to an object that has already signaled. 4452The import operation will succeed and the sname:VkSemaphore will have a 4453temporarily imported payload as if a valid file descriptor had been 4454provided. 4455 4456[NOTE] 4457.Note 4458==== 4459This special behavior for importing an invalid sync file descriptor allows 4460easier interoperability with other system APIs which use the convention that 4461an invalid sync file descriptor represents work that has already completed 4462and does not need to be waited for. 4463It is consistent with the option for implementations to return a `-1` file 4464descriptor when exporting a 4465ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT from a sname:VkSemaphore 4466which is signaled. 4467==== 4468 4469include::{generated}/validity/structs/VkImportSemaphoreFdInfoKHR.adoc[] 4470-- 4471endif::VK_KHR_external_semaphore_fd[] 4472 4473ifdef::VK_FUCHSIA_external_semaphore[] 4474[open,refpage='vkImportSemaphoreZirconHandleFUCHSIA',desc='Import a semaphore from a Zircon event handle',type='protos'] 4475-- 4476To import a semaphore payload from a Zircon event handle, call: 4477 4478include::{generated}/api/protos/vkImportSemaphoreZirconHandleFUCHSIA.adoc[] 4479 4480 * pname:device is the logical device that created the semaphore. 4481 * pname:pImportSemaphoreZirconHandleInfo is a pointer to a 4482 slink:VkImportSemaphoreZirconHandleInfoFUCHSIA structure specifying the 4483 semaphore and import parameters. 4484 4485Importing a semaphore payload from a Zircon event handle transfers ownership 4486of the handle from the application to the Vulkan implementation. 4487The application must: not perform any operations on the handle after a 4488successful import. 4489 4490Applications can: import the same semaphore payload into multiple instances 4491of Vulkan, into the same instance from which it was exported, and multiple 4492times into a given Vulkan instance. 4493 4494.Valid Usage 4495**** 4496 * [[VUID-vkImportSemaphoreZirconHandleFUCHSIA-semaphore-04764]] 4497 pname:semaphore must: not be associated with any queue command that has 4498 not yet completed execution on that queue 4499**** 4500 4501include::{generated}/validity/protos/vkImportSemaphoreZirconHandleFUCHSIA.adoc[] 4502-- 4503 4504[open,refpage='VkImportSemaphoreZirconHandleInfoFUCHSIA',desc='Structure specifying Zircon event handle to import to a semaphore',type='structs'] 4505-- 4506The sname:VkImportSemaphoreZirconHandleInfoFUCHSIA structure is defined as: 4507 4508include::{generated}/api/structs/VkImportSemaphoreZirconHandleInfoFUCHSIA.adoc[] 4509 4510 * pname:sType is the type of this structure. 4511 * pname:pNext is `NULL` or a pointer to a structure extending this 4512 structure. 4513 * pname:semaphore is the semaphore into which the payload will be 4514 imported. 4515 * pname:flags is a bitmask of elink:VkSemaphoreImportFlagBits specifying 4516 additional parameters for the semaphore payload import operation. 4517 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 4518 specifying the type of pname:zirconHandle. 4519 * pname:zirconHandle is the external handle to import. 4520 4521The handle types supported by pname:handleType are: 4522 4523[[synchronization-semaphore-handletypes-fuchsia]] 4524.Handle Types Supported by sname:VkImportSemaphoreZirconHandleInfoFUCHSIA 4525[width="80%",options="header"] 4526|==== 4527| Handle Type | Transference | Permanence Supported 4528| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA | Reference | Temporary,Permanent 4529|==== 4530 4531.Valid Usage 4532**** 4533 * [[VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-handleType-04765]] 4534 pname:handleType must: be a value included in the 4535 <<synchronization-semaphore-handletypes-fuchsia,Handle Types Supported 4536 by sname:VkImportSemaphoreZirconHandleInfoFUCHSIA>> table 4537 * [[VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-zirconHandle-04766]] 4538 pname:zirconHandle must: obey any requirements listed for 4539 pname:handleType in 4540 <<external-semaphore-handle-types-compatibility,external semaphore 4541 handle types compatibility>> 4542 * [[VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-zirconHandle-04767]] 4543 pname:zirconHandle must: have code:ZX_RIGHTS_BASIC and 4544 code:ZX_RIGHTS_SIGNAL rights 4545ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4546 * [[VUID-VkImportSemaphoreZirconHandleInfoFUCHSIA-semaphoreType-04768]] 4547 The slink:VkSemaphoreTypeCreateInfo::pname:semaphoreType field must: not 4548 be ename:VK_SEMAPHORE_TYPE_TIMELINE 4549endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 4550**** 4551 4552include::{generated}/validity/structs/VkImportSemaphoreZirconHandleInfoFUCHSIA.adoc[] 4553-- 4554endif::VK_FUCHSIA_external_semaphore[] 4555 4556ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 4557ifdef::VK_KHR_external_semaphore_win32,VK_KHR_external_semaphore_fd,VK_FUCHSIA_external_semaphore[] 4558[open,refpage='VkSemaphoreImportFlagBits',desc='Bitmask specifying additional parameters of semaphore payload import',type='enums'] 4559-- 4560Bits which can: be set in 4561 4562ifdef::VK_KHR_external_semaphore_win32[] 4563 * slink:VkImportSemaphoreWin32HandleInfoKHR::pname:flags 4564endif::VK_KHR_external_semaphore_win32[] 4565ifdef::VK_KHR_external_semaphore_fd[] 4566 * slink:VkImportSemaphoreFdInfoKHR::pname:flags 4567endif::VK_KHR_external_semaphore_fd[] 4568ifdef::VK_FUCHSIA_external_semaphore[] 4569 * slink:VkImportSemaphoreZirconHandleInfoFUCHSIA::pname:flags 4570endif::VK_FUCHSIA_external_semaphore[] 4571 4572specifying additional parameters of a semaphore import operation are: 4573 4574include::{generated}/api/enums/VkSemaphoreImportFlagBits.adoc[] 4575 4576ifdef::VK_KHR_external_semaphore[] 4577or the equivalent 4578 4579include::{generated}/api/enums/VkSemaphoreImportFlagBitsKHR.adoc[] 4580endif::VK_KHR_external_semaphore[] 4581 4582These bits have the following meanings: 4583 4584 * ename:VK_SEMAPHORE_IMPORT_TEMPORARY_BIT specifies that the semaphore 4585 payload will be imported only temporarily, as described in 4586 <<synchronization-semaphores-importing,Importing Semaphore Payloads>>, 4587 regardless of the permanence of pname:handleType. 4588-- 4589 4590[open,refpage='VkSemaphoreImportFlags',desc='Bitmask of VkSemaphoreImportFlagBits',type='flags'] 4591-- 4592include::{generated}/api/flags/VkSemaphoreImportFlags.adoc[] 4593 4594ifdef::VK_KHR_external_semaphore[] 4595or the equivalent 4596 4597include::{generated}/api/flags/VkSemaphoreImportFlagsKHR.adoc[] 4598endif::VK_KHR_external_semaphore[] 4599 4600tname:VkSemaphoreImportFlags is a bitmask type for setting a mask of zero or 4601more elink:VkSemaphoreImportFlagBits. 4602-- 4603endif::VK_KHR_external_semaphore_win32,VK_KHR_external_semaphore_fd,VK_FUCHSIA_external_semaphore[] 4604endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 4605 4606 4607[[synchronization-events]] 4608== Events 4609 4610[open,refpage='VkEvent',desc='Opaque handle to an event object',type='handles'] 4611-- 4612Events are a synchronization primitive that can: be used to insert a 4613fine-grained dependency between commands submitted to the same queue, or 4614between the host and a queue. 4615Events must: not be used to insert a dependency between commands submitted 4616to different queues. 4617Events have two states - signaled and unsignaled. 4618An application can: signal or unsignal an event either on the host or on the 4619device. 4620A device can: be made to wait for an event to become signaled before 4621executing further operations. 4622No command exists to wait for an event to become signaled on the host, but 4623the current state of an event can: be queried. 4624 4625Events are represented by sname:VkEvent handles: 4626 4627include::{generated}/api/handles/VkEvent.adoc[] 4628-- 4629 4630[open,refpage='vkCreateEvent',desc='Create a new event object',type='protos'] 4631-- 4632To create an event, call: 4633 4634include::{generated}/api/protos/vkCreateEvent.adoc[] 4635 4636 * pname:device is the logical device that creates the event. 4637 * pname:pCreateInfo is a pointer to a slink:VkEventCreateInfo structure 4638 containing information about how the event is to be created. 4639 * pname:pAllocator controls host memory allocation as described in the 4640 <<memory-allocation, Memory Allocation>> chapter. 4641 * pname:pEvent is a pointer to a handle in which the resulting event 4642 object is returned. 4643 4644When created, the event object is in the unsignaled state. 4645 4646ifdef::VK_KHR_portability_subset[] 4647.Valid Usage 4648**** 4649 * [[VUID-vkCreateEvent-events-04468]] 4650 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 4651 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:events is 4652 ename:VK_FALSE, then the implementation does not support 4653 <<synchronization-events, events>>, and flink:vkCreateEvent must: not be 4654 used 4655**** 4656endif::VK_KHR_portability_subset[] 4657 4658include::{generated}/validity/protos/vkCreateEvent.adoc[] 4659-- 4660 4661[open,refpage='VkEventCreateInfo',desc='Structure specifying parameters of a newly created event',type='structs'] 4662-- 4663The sname:VkEventCreateInfo structure is defined as: 4664 4665include::{generated}/api/structs/VkEventCreateInfo.adoc[] 4666 4667 * pname:sType is the type of this structure. 4668 * pname:pNext is `NULL` or a pointer to a structure extending this 4669 structure. 4670 * pname:flags is a bitmask of elink:VkEventCreateFlagBits defining 4671 additional creation parameters. 4672 4673ifdef::VK_EXT_metal_objects[] 4674.Valid Usage 4675**** 4676 * [[VUID-VkEventCreateInfo-pNext-06790]] 4677 If the pname:pNext chain includes a 4678 slink:VkExportMetalObjectCreateInfoEXT structure, its 4679 pname:exportObjectType member must: be 4680 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXT 4681**** 4682endif::VK_EXT_metal_objects[] 4683 4684include::{generated}/validity/structs/VkEventCreateInfo.adoc[] 4685-- 4686 4687[open,refpage='VkEventCreateFlagBits',desc='Event creation flag bits',type='enums'] 4688-- 4689include::{generated}/api/enums/VkEventCreateFlagBits.adoc[] 4690 4691ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4692 * ename:VK_EVENT_CREATE_DEVICE_ONLY_BIT specifies that host event commands 4693 will not be used with this event. 4694endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4695 4696ifndef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4697[NOTE] 4698.Note 4699==== 4700All bits for this type are defined by extensions, and none of those 4701extensions are enabled in this build of the specification. 4702==== 4703endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4704-- 4705 4706[open,refpage='VkEventCreateFlags',desc='Bitmask of event creation flag bits',type='flags'] 4707-- 4708include::{generated}/api/flags/VkEventCreateFlags.adoc[] 4709 4710tname:VkEventCreateFlags is a bitmask type for setting a mask of 4711elink:VkEventCreateFlagBits. 4712-- 4713 4714[open,refpage='vkDestroyEvent',desc='Destroy an event object',type='protos'] 4715-- 4716To destroy an event, call: 4717 4718include::{generated}/api/protos/vkDestroyEvent.adoc[] 4719 4720 * pname:device is the logical device that destroys the event. 4721 * pname:event is the handle of the event to destroy. 4722 * pname:pAllocator controls host memory allocation as described in the 4723 <<memory-allocation, Memory Allocation>> chapter. 4724 4725.Valid Usage 4726**** 4727 * [[VUID-vkDestroyEvent-event-01145]] 4728 All submitted commands that refer to pname:event must: have completed 4729 execution 4730 * [[VUID-vkDestroyEvent-event-01146]] 4731 If sname:VkAllocationCallbacks were provided when pname:event was 4732 created, a compatible set of callbacks must: be provided here 4733 * [[VUID-vkDestroyEvent-event-01147]] 4734 If no sname:VkAllocationCallbacks were provided when pname:event was 4735 created, pname:pAllocator must: be `NULL` 4736**** 4737 4738include::{generated}/validity/protos/vkDestroyEvent.adoc[] 4739-- 4740 4741[open,refpage='vkGetEventStatus',desc='Retrieve the status of an event object',type='protos'] 4742-- 4743To query the state of an event from the host, call: 4744 4745include::{generated}/api/protos/vkGetEventStatus.adoc[] 4746 4747 * pname:device is the logical device that owns the event. 4748 * pname:event is the handle of the event to query. 4749 4750Upon success, fname:vkGetEventStatus returns the state of the event object 4751with the following return codes: 4752 4753.Event Object Status Codes 4754[width="80%",options="header"] 4755|==== 4756| Status | Meaning 4757| ename:VK_EVENT_SET | The event specified by pname:event is signaled. 4758| ename:VK_EVENT_RESET | The event specified by pname:event is unsignaled. 4759|==== 4760 4761If a fname:vkCmdSetEvent or fname:vkCmdResetEvent command is in a command 4762buffer that is in the <<commandbuffers-lifecycle, pending state>>, then the 4763value returned by this command may: immediately be out of date. 4764 4765The state of an event can: be updated by the host. 4766The state of the event is immediately changed, and subsequent calls to 4767fname:vkGetEventStatus will return the new state. 4768If an event is already in the requested state, then updating it to the same 4769state has no effect. 4770 4771ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4772.Valid Usage 4773**** 4774 * [[VUID-vkGetEventStatus-event-03940]] 4775 pname:event must: not have been created with 4776 ename:VK_EVENT_CREATE_DEVICE_ONLY_BIT 4777**** 4778endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4779 4780include::{generated}/validity/protos/vkGetEventStatus.adoc[] 4781-- 4782 4783[[synchronization-events-signaling-host]] 4784[open,refpage='vkSetEvent',desc='Set an event to signaled state',type='protos'] 4785-- 4786To set the state of an event to signaled from the host, call: 4787 4788include::{generated}/api/protos/vkSetEvent.adoc[] 4789 4790 * pname:device is the logical device that owns the event. 4791 * pname:event is the event to set. 4792 4793When flink:vkSetEvent is executed on the host, it defines an _event signal 4794operation_ which sets the event to the signaled state. 4795 4796If pname:event is already in the signaled state when flink:vkSetEvent is 4797executed, then flink:vkSetEvent has no effect, and no event signal operation 4798occurs. 4799 4800[NOTE] 4801.Note 4802==== 4803If a command buffer is waiting for an event to be signaled from the host, 4804the application must signal the event before submitting the command buffer, 4805as described in the <<commandbuffers-submission-progress, queue forward 4806progress>> section. 4807==== 4808 4809ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4810.Valid Usage 4811**** 4812 * [[VUID-vkSetEvent-event-03941]] 4813 pname:event must: not have been created with 4814 ename:VK_EVENT_CREATE_DEVICE_ONLY_BIT 4815**** 4816endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4817 4818include::{generated}/validity/protos/vkSetEvent.adoc[] 4819-- 4820 4821[[synchronization-events-unsignaling-host]] 4822[open,refpage='vkResetEvent',desc='Reset an event to non-signaled state',type='protos'] 4823-- 4824To set the state of an event to unsignaled from the host, call: 4825 4826include::{generated}/api/protos/vkResetEvent.adoc[] 4827 4828 * pname:device is the logical device that owns the event. 4829 * pname:event is the event to reset. 4830 4831When flink:vkResetEvent is executed on the host, it defines an _event 4832unsignal operation_ which resets the event to the unsignaled state. 4833 4834If pname:event is already in the unsignaled state when flink:vkResetEvent is 4835executed, then flink:vkResetEvent has no effect, and no event unsignal 4836operation occurs. 4837 4838.Valid Usage 4839**** 4840 * [[VUID-vkResetEvent-event-03821]] 4841 There must: be an execution dependency between fname:vkResetEvent and 4842 the execution of any flink:vkCmdWaitEvents that includes pname:event in 4843 its pname:pEvents parameter 4844ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4845 * [[VUID-vkResetEvent-event-03822]] 4846 There must: be an execution dependency between fname:vkResetEvent and 4847 the execution of any flink:vkCmdWaitEvents2 that includes pname:event in 4848 its pname:pEvents parameter 4849endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4850ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4851 * [[VUID-vkResetEvent-event-03823]] 4852 pname:event must: not have been created with 4853 ename:VK_EVENT_CREATE_DEVICE_ONLY_BIT 4854endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4855**** 4856 4857include::{generated}/validity/protos/vkResetEvent.adoc[] 4858-- 4859 4860The state of an event can: also be updated on the device by commands 4861inserted in command buffers. 4862 4863[[synchronization-events-signaling-device]] 4864ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4865[open,refpage='vkCmdSetEvent2',desc='Set an event object to signaled state',type='protos',alias='vkCmdSetEvent2KHR'] 4866-- 4867To signal an event from a device, call: 4868 4869ifdef::VK_VERSION_1_3[] 4870include::{generated}/api/protos/vkCmdSetEvent2.adoc[] 4871endif::VK_VERSION_1_3[] 4872 4873ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 4874 4875ifdef::VK_KHR_synchronization2[] 4876include::{generated}/api/protos/vkCmdSetEvent2KHR.adoc[] 4877endif::VK_KHR_synchronization2[] 4878 4879 * pname:commandBuffer is the command buffer into which the command is 4880 recorded. 4881 * pname:event is the event that will be signaled. 4882 * pname:pDependencyInfo is a pointer to a slink:VkDependencyInfo structure 4883 defining the first scopes of this operation. 4884 4885When flink:vkCmdSetEvent2 is submitted to a queue, it defines the first half 4886of memory dependencies defined by pname:pDependencyInfo, as well as an event 4887signal operation which sets the event to the signaled state. 4888A memory dependency is defined between the event signal operation and 4889commands that occur earlier in submission order. 4890 4891The first <<synchronization-dependencies-scopes, synchronization scope>> and 4892<<synchronization-dependencies-access-scopes, access scope>> are defined by 4893the union of all the memory dependencies defined by pname:pDependencyInfo, 4894and are applied to all operations that occur earlier in 4895<<synchronization-submission-order,submission order>>. 4896<<synchronization-queue-transfers, Queue family ownership transfers>> and 4897<<synchronization-image-layout-transitions, image layout transitions>> 4898defined by pname:pDependencyInfo are also included in the first scopes. 4899 4900The second <<synchronization-dependencies-scopes, synchronization scope>> 4901includes only the event signal operation, and any 4902<<synchronization-queue-transfers, queue family ownership transfers>> and 4903<<synchronization-image-layout-transitions, image layout transitions>> 4904defined by pname:pDependencyInfo. 4905 4906The second <<synchronization-dependencies-access-scopes, access scope>> 4907includes only <<synchronization-queue-transfers, queue family ownership 4908transfers>> and <<synchronization-image-layout-transitions, image layout 4909transitions>>. 4910 4911Future flink:vkCmdWaitEvents2 commands rely on all values of each element in 4912pname:pDependencyInfo matching exactly with those used to signal the 4913corresponding event. 4914flink:vkCmdWaitEvents must: not be used to wait on the result of a signal 4915operation defined by fname:vkCmdSetEvent2. 4916 4917[NOTE] 4918.Note 4919==== 4920The extra information provided by flink:vkCmdSetEvent2 compared to 4921flink:vkCmdSetEvent allows implementations to more efficiently schedule the 4922operations required to satisfy the requested dependencies. 4923With flink:vkCmdSetEvent, the full dependency information is not known until 4924flink:vkCmdWaitEvents is recorded, forcing implementations to insert the 4925required operations at that point and not before. 4926==== 4927 4928If pname:event is already in the signaled state when flink:vkCmdSetEvent2 is 4929executed on the device, then flink:vkCmdSetEvent2 has no effect, no event 4930signal operation occurs, and no dependency is generated. 4931 4932.Valid Usage 4933**** 4934 * [[VUID-vkCmdSetEvent2-synchronization2-03824]] 4935 The <<features-synchronization2, pname:synchronization2>> feature must: 4936 be enabled 4937 * [[VUID-vkCmdSetEvent2-dependencyFlags-03825]] 4938 The pname:dependencyFlags member of pname:pDependencyInfo must: be `0` 4939ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 4940 * [[VUID-vkCmdSetEvent2-commandBuffer-03826]] 4941 The current device mask of pname:commandBuffer must: include exactly one 4942 physical device 4943endif::VK_VERSION_1_1,VK_KHR_device_group[] 4944 * [[VUID-vkCmdSetEvent2-srcStageMask-03827]] 4945 The pname:srcStageMask member of any element of the 4946 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 4947 pname:pImageMemoryBarriers members of pname:pDependencyInfo must: only 4948 include pipeline stages valid for the queue family that was used to 4949 create the command pool that pname:commandBuffer was allocated from 4950 * [[VUID-vkCmdSetEvent2-dstStageMask-03828]] 4951 The pname:dstStageMask member of any element of the 4952 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 4953 pname:pImageMemoryBarriers members of pname:pDependencyInfo must: only 4954 include pipeline stages valid for the queue family that was used to 4955 create the command pool that pname:commandBuffer was allocated from 4956**** 4957 4958include::{generated}/validity/protos/vkCmdSetEvent2.adoc[] 4959-- 4960 4961[open,refpage='VkDependencyInfo',desc='Structure specifying dependency information for a synchronization command',type='structs',alias='VkDependencyInfoKHR'] 4962-- 4963The sname:VkDependencyInfo structure is defined as: 4964 4965include::{generated}/api/structs/VkDependencyInfo.adoc[] 4966 4967ifdef::VK_KHR_synchronization2[] 4968or the equivalent 4969 4970include::{generated}/api/structs/VkDependencyInfoKHR.adoc[] 4971endif::VK_KHR_synchronization2[] 4972 4973 * pname:sType is the type of this structure. 4974 * pname:pNext is `NULL` or a pointer to a structure extending this 4975 structure. 4976 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits 4977 specifying how execution and memory dependencies are formed. 4978 * pname:memoryBarrierCount is the length of the pname:pMemoryBarriers 4979 array. 4980 * pname:pMemoryBarriers is a pointer to an array of slink:VkMemoryBarrier2 4981 structures defining memory dependencies between any memory accesses. 4982 * pname:bufferMemoryBarrierCount is the length of the 4983 pname:pBufferMemoryBarriers array. 4984 * pname:pBufferMemoryBarriers is a pointer to an array of 4985 slink:VkBufferMemoryBarrier2 structures defining memory dependencies 4986 between buffer ranges. 4987 * pname:imageMemoryBarrierCount is the length of the 4988 pname:pImageMemoryBarriers array. 4989 * pname:pImageMemoryBarriers is a pointer to an array of 4990 slink:VkImageMemoryBarrier2 structures defining memory dependencies 4991 between image subresources. 4992 4993This structure defines a set of <<synchronization-dependencies-memory, 4994memory dependencies>>, as well as <<synchronization-queue-transfers, queue 4995family transfer operations>> and <<synchronization-image-layout-transitions, 4996image layout transitions>>. 4997 4998Each member of pname:pMemoryBarriers, pname:pBufferMemoryBarriers, and 4999pname:pImageMemoryBarriers defines a separate 5000<<synchronization-dependencies-memory, memory dependency>>. 5001 5002include::{generated}/validity/structs/VkDependencyInfo.adoc[] 5003-- 5004endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5005 5006[open,refpage='vkCmdSetEvent',desc='Set an event object to signaled state',type='protos'] 5007-- 5008:refpage: vkCmdSetEvent 5009 5010To set the state of an event to signaled from a device, call: 5011 5012include::{generated}/api/protos/vkCmdSetEvent.adoc[] 5013 5014 * pname:commandBuffer is the command buffer into which the command is 5015 recorded. 5016 * pname:event is the event that will be signaled. 5017 * pname:stageMask specifies the <<synchronization-pipeline-stages,source 5018 stage mask>> used to determine the first 5019 <<synchronization-dependencies-scopes, synchronization scope>>. 5020 5021 5022ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5023fname:vkCmdSetEvent behaves identically to flink:vkCmdSetEvent2, except that 5024it does not define an access scope, and must: only be used with 5025flink:vkCmdWaitEvents, not flink:vkCmdWaitEvents2. 5026endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5027 5028ifndef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5029When flink:vkCmdSetEvent is submitted to a queue, it defines an execution 5030dependency on commands that were submitted before it, and defines an event 5031signal operation which sets the event to the signaled state. 5032 5033The first <<synchronization-dependencies-scopes, synchronization scope>> 5034includes all commands that occur earlier in 5035<<synchronization-submission-order,submission order>>. 5036The synchronization scope is limited to operations on the pipeline stages 5037determined by the <<synchronization-pipeline-stages-masks, source stage 5038mask>> specified by pname:stageMask. 5039 5040The second <<synchronization-dependencies-scopes, synchronization scope>> 5041includes only the event signal operation. 5042 5043If pname:event is already in the signaled state when flink:vkCmdSetEvent is 5044executed on the device, then flink:vkCmdSetEvent has no effect, no event 5045signal operation occurs, and no execution dependency is generated. 5046endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5047 5048.Valid Usage 5049**** 5050:stageMaskName: stageMask 5051include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5052 * [[VUID-vkCmdSetEvent-stageMask-06457]] 5053 Any pipeline stage included in pname:stageMask must: be supported by the 5054 capabilities of the queue family specified by the pname:queueFamilyIndex 5055 member of the slink:VkCommandPoolCreateInfo structure that was used to 5056 create the sname:VkCommandPool that pname:commandBuffer was allocated 5057 from, as specified in the <<synchronization-pipeline-stages-supported, 5058 table of supported pipeline stages>> 5059 * [[VUID-vkCmdSetEvent-stageMask-01149]] 5060 pname:stageMask must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 5061ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5062 * [[VUID-vkCmdSetEvent-commandBuffer-01152]] 5063 pname:commandBuffer's current device mask must: include exactly one 5064 physical device 5065endif::VK_VERSION_1_1,VK_KHR_device_group[] 5066**** 5067 5068include::{generated}/validity/protos/vkCmdSetEvent.adoc[] 5069-- 5070 5071[[synchronization-events-unsignaling-device]] 5072ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5073[open,refpage='vkCmdResetEvent2',desc='Reset an event object to non-signaled state',type='protos',alias='vkCmdResetEvent2KHR'] 5074-- 5075:refpage: vkCmdResetEvent2 5076 5077To unsignal the event from a device, call: 5078 5079ifdef::VK_VERSION_1_3[] 5080include::{generated}/api/protos/vkCmdResetEvent2.adoc[] 5081endif::VK_VERSION_1_3[] 5082 5083ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 5084 5085ifdef::VK_KHR_synchronization2[] 5086include::{generated}/api/protos/vkCmdResetEvent2KHR.adoc[] 5087endif::VK_KHR_synchronization2[] 5088 5089 * pname:commandBuffer is the command buffer into which the command is 5090 recorded. 5091 * pname:event is the event that will be unsignaled. 5092 * pname:stageMask is a tlink:VkPipelineStageFlags2 mask of pipeline stages 5093 used to determine the first <<synchronization-dependencies-scopes, 5094 synchronization scope>>. 5095 5096When flink:vkCmdResetEvent2 is submitted to a queue, it defines an execution 5097dependency on commands that were submitted before it, and defines an event 5098unsignal operation which resets the event to the unsignaled state. 5099 5100The first <<synchronization-dependencies-scopes, synchronization scope>> 5101includes all commands that occur earlier in 5102<<synchronization-submission-order,submission order>>. 5103The synchronization scope is limited to operations by pname:stageMask or 5104stages that are <<synchronization-pipeline-stages-order,logically earlier>> 5105than pname:stageMask. 5106 5107The second <<synchronization-dependencies-scopes, synchronization scope>> 5108includes only the event unsignal operation. 5109 5110If pname:event is already in the unsignaled state when 5111flink:vkCmdResetEvent2 is executed on the device, then this command has no 5112effect, no event unsignal operation occurs, and no execution dependency is 5113generated. 5114 5115.Valid Usage 5116**** 5117:stageMaskName: stageMask 5118include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 5119 * [[VUID-vkCmdResetEvent2-synchronization2-03829]] 5120 The <<features-synchronization2, pname:synchronization2>> feature must: 5121 be enabled 5122 * [[VUID-vkCmdResetEvent2-stageMask-03830]] 5123 pname:stageMask must: not include ename:VK_PIPELINE_STAGE_2_HOST_BIT 5124 * [[VUID-vkCmdResetEvent2-event-03831]] 5125 There must: be an execution dependency between fname:vkCmdResetEvent2 5126 and the execution of any flink:vkCmdWaitEvents that includes pname:event 5127 in its pname:pEvents parameter 5128 * [[VUID-vkCmdResetEvent2-event-03832]] 5129 There must: be an execution dependency between fname:vkCmdResetEvent2 5130 and the execution of any flink:vkCmdWaitEvents2 that includes 5131 pname:event in its pname:pEvents parameter 5132ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5133 * [[VUID-vkCmdResetEvent2-commandBuffer-03833]] 5134 pname:commandBuffer's current device mask must: include exactly one 5135 physical device 5136endif::VK_VERSION_1_1,VK_KHR_device_group[] 5137**** 5138 5139include::{generated}/validity/protos/vkCmdResetEvent2.adoc[] 5140-- 5141endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5142 5143[open,refpage='vkCmdResetEvent',desc='Reset an event object to non-signaled state',type='protos'] 5144-- 5145:refpage: vkCmdResetEvent 5146 5147To set the state of an event to unsignaled from a device, call: 5148 5149include::{generated}/api/protos/vkCmdResetEvent.adoc[] 5150 5151 * pname:commandBuffer is the command buffer into which the command is 5152 recorded. 5153 * pname:event is the event that will be unsignaled. 5154 * pname:stageMask is a bitmask of elink:VkPipelineStageFlagBits specifying 5155 the <<synchronization-pipeline-stages, source stage mask>> used to 5156 determine when the pname:event is unsignaled. 5157 5158ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5159fname:vkCmdResetEvent behaves identically to flink:vkCmdResetEvent2. 5160endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5161 5162ifndef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5163When flink:vkCmdResetEvent is submitted to a queue, it defines an execution 5164dependency on commands that were submitted before it, and defines an event 5165unsignal operation which resets the event to the unsignaled state. 5166 5167The first <<synchronization-dependencies-scopes, synchronization scope>> 5168includes all commands that occur earlier in 5169<<synchronization-submission-order,submission order>>. 5170The synchronization scope is limited to operations on the pipeline stages 5171determined by the <<synchronization-pipeline-stages-masks, source stage 5172mask>> specified by pname:stageMask. 5173 5174The second <<synchronization-dependencies-scopes, synchronization scope>> 5175includes only the event unsignal operation. 5176 5177If pname:event is already in the unsignaled state when flink:vkCmdResetEvent 5178is executed on the device, then flink:vkCmdResetEvent has no effect, no 5179event unsignal operation occurs, and no execution dependency is generated. 5180endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5181 5182.Valid Usage 5183**** 5184:stageMaskName: stageMask 5185include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5186 * [[VUID-vkCmdResetEvent-stageMask-06458]] 5187 Any pipeline stage included in pname:stageMask must: be supported by the 5188 capabilities of the queue family specified by the pname:queueFamilyIndex 5189 member of the slink:VkCommandPoolCreateInfo structure that was used to 5190 create the sname:VkCommandPool that pname:commandBuffer was allocated 5191 from, as specified in the <<synchronization-pipeline-stages-supported, 5192 table of supported pipeline stages>> 5193 * [[VUID-vkCmdResetEvent-stageMask-01153]] 5194 pname:stageMask must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 5195 * [[VUID-vkCmdResetEvent-event-03834]] 5196 There must: be an execution dependency between fname:vkCmdResetEvent and 5197 the execution of any flink:vkCmdWaitEvents that includes pname:event in 5198 its pname:pEvents parameter 5199ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5200 * [[VUID-vkCmdResetEvent-event-03835]] 5201 There must: be an execution dependency between fname:vkCmdResetEvent and 5202 the execution of any flink:vkCmdWaitEvents2 that includes pname:event in 5203 its pname:pEvents parameter 5204endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5205ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5206 * [[VUID-vkCmdResetEvent-commandBuffer-01157]] 5207 pname:commandBuffer's current device mask must: include exactly one 5208 physical device 5209endif::VK_VERSION_1_1,VK_KHR_device_group[] 5210**** 5211 5212include::{generated}/validity/protos/vkCmdResetEvent.adoc[] 5213-- 5214 5215ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5216[open,refpage='vkCmdWaitEvents2',desc='Wait for one or more events',type='protos',alias='vkCmdWaitEvents2KHR'] 5217-- 5218To wait for one or more events to enter the signaled state on a device, 5219call: 5220 5221[[synchronization-events-waiting-device]] 5222ifdef::VK_VERSION_1_3[] 5223include::{generated}/api/protos/vkCmdWaitEvents2.adoc[] 5224endif::VK_VERSION_1_3[] 5225 5226ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 5227 5228ifdef::VK_KHR_synchronization2[] 5229include::{generated}/api/protos/vkCmdWaitEvents2KHR.adoc[] 5230endif::VK_KHR_synchronization2[] 5231 5232 * pname:commandBuffer is the command buffer into which the command is 5233 recorded. 5234 * pname:eventCount is the length of the pname:pEvents array. 5235 * pname:pEvents is a pointer to an array of pname:eventCount events to 5236 wait on. 5237 * pname:pDependencyInfos is a pointer to an array of pname:eventCount 5238 slink:VkDependencyInfo structures, defining the second 5239 <<synchronization-dependencies-scopes, synchronization scope>>. 5240 5241When fname:vkCmdWaitEvents2 is submitted to a queue, it inserts memory 5242dependencies according to the elements of pname:pDependencyInfos and each 5243corresponding element of pname:pEvents. 5244fname:vkCmdWaitEvents2 must: not be used to wait on event signal operations 5245occurring on other queues, or signal operations executed by 5246flink:vkCmdSetEvent. 5247 5248The first <<synchronization-dependencies-scopes, synchronization scope>> and 5249<<synchronization-dependencies-access-scopes, access scope>> of each memory 5250dependency defined by any element [eq]#i# of pname:pDependencyInfos are 5251applied to operations that occurred earlier in 5252<<synchronization-submission-order,submission order>> than the last event 5253signal operation on element [eq]#i# of pname:pEvents. 5254 5255Signal operations for an event at index [eq]#i# are only included if: 5256 5257 * The event was signaled by a flink:vkCmdSetEvent2 command that occurred 5258 earlier in <<synchronization-submission-order,submission order>> with a 5259 pname:dependencyInfo parameter exactly equal to the element of 5260 pname:pDependencyInfos at index [eq]#i# ; or 5261 * The event was created without ename:VK_EVENT_CREATE_DEVICE_ONLY_BIT, and 5262 the first <<synchronization-dependencies-scopes, synchronization scope>> 5263 defined by the element of pname:pDependencyInfos at index [eq]#i# only 5264 includes host operations (ename:VK_PIPELINE_STAGE_2_HOST_BIT). 5265 5266The second <<synchronization-dependencies-scopes, synchronization scope>> 5267and <<synchronization-dependencies-access-scopes, access scope>> of each 5268memory dependency defined by any element [eq]#i# of pname:pDependencyInfos 5269are applied to operations that occurred later in 5270<<synchronization-submission-order,submission order>> than 5271fname:vkCmdWaitEvents2. 5272 5273[NOTE] 5274.Note 5275==== 5276flink:vkCmdWaitEvents2 is used with flink:vkCmdSetEvent2 to define a memory 5277dependency between two sets of action commands, roughly in the same way as 5278pipeline barriers, but split into two commands such that work between the 5279two may: execute unhindered. 5280==== 5281 5282[NOTE] 5283.Note 5284==== 5285Applications should be careful to avoid race conditions when using events. 5286There is no direct ordering guarantee between fname:vkCmdSetEvent2 and 5287flink:vkCmdResetEvent2, flink:vkCmdResetEvent, or flink:vkCmdSetEvent. 5288Another execution dependency (e.g. a pipeline barrier or semaphore with 5289ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT) is needed to prevent such a race 5290condition. 5291==== 5292 5293.Valid Usage 5294**** 5295 * [[VUID-vkCmdWaitEvents2-synchronization2-03836]] 5296 The <<features-synchronization2, pname:synchronization2>> feature must: 5297 be enabled 5298 * [[VUID-vkCmdWaitEvents2-pEvents-03837]] 5299 Members of pname:pEvents must: not have been signaled by 5300 flink:vkCmdSetEvent 5301 * [[VUID-vkCmdWaitEvents2-pEvents-03838]] 5302 For any element [eq]#i# of pname:pEvents, if that event is signaled by 5303 flink:vkCmdSetEvent2, that command's pname:dependencyInfo parameter 5304 must: be exactly equal to the [eq]##i##th element of 5305 pname:pDependencyInfos 5306 * [[VUID-vkCmdWaitEvents2-pEvents-03839]] 5307 For any element [eq]#i# of pname:pEvents, if that event is signaled by 5308 flink:vkSetEvent, barriers in the [eq]##i##th element of 5309 pname:pDependencyInfos must: include only host operations in their first 5310 <<synchronization-dependencies-scopes, synchronization scope>> 5311 * [[VUID-vkCmdWaitEvents2-pEvents-03840]] 5312 For any element [eq]#i# of pname:pEvents, if barriers in the [eq]##i##th 5313 element of pname:pDependencyInfos include only host operations, the 5314 [eq]##i##th element of pname:pEvents must: be signaled before 5315 flink:vkCmdWaitEvents2 is executed 5316 * [[VUID-vkCmdWaitEvents2-pEvents-03841]] 5317 For any element [eq]#i# of pname:pEvents, if barriers in the [eq]##i##th 5318 element of pname:pDependencyInfos do not include host operations, the 5319 [eq]##i##th element of pname:pEvents must: be signaled by a 5320 corresponding flink:vkCmdSetEvent2 that occurred earlier in 5321 <<synchronization-submission-order,submission order>> 5322 * [[VUID-vkCmdWaitEvents2-srcStageMask-03842]] 5323 The pname:srcStageMask member of any element of the 5324 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 5325 pname:pImageMemoryBarriers members of pname:pDependencyInfos must: 5326 either include only pipeline stages valid for the queue family that was 5327 used to create the command pool that pname:commandBuffer was allocated 5328 from, or include only ename:VK_PIPELINE_STAGE_2_HOST_BIT 5329 * [[VUID-vkCmdWaitEvents2-dstStageMask-03843]] 5330 The pname:dstStageMask member of any element of the 5331 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 5332 pname:pImageMemoryBarriers members of pname:pDependencyInfos must: only 5333 include pipeline stages valid for the queue family that was used to 5334 create the command pool that pname:commandBuffer was allocated from 5335 * [[VUID-vkCmdWaitEvents2-dependencyFlags-03844]] 5336 If fname:vkCmdWaitEvents2 is being called inside a render pass instance, 5337 the pname:srcStageMask member of any element of the 5338 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 5339 pname:pImageMemoryBarriers members of pname:pDependencyInfos must: not 5340 include ename:VK_PIPELINE_STAGE_2_HOST_BIT 5341 * [[VUID-vkCmdWaitEvents2-commandBuffer-03846]] 5342 pname:commandBuffer's current device mask must: include exactly one 5343 physical device 5344**** 5345 5346include::{generated}/validity/protos/vkCmdWaitEvents2.adoc[] 5347-- 5348endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5349 5350[open,refpage='vkCmdWaitEvents',desc='Wait for one or more events and insert a set of memory',type='protos'] 5351-- 5352:refpage: vkCmdWaitEvents 5353 5354To wait for one or more events to enter the signaled state on a device, 5355call: 5356 5357[[synchronization-events-waiting-device]] 5358include::{generated}/api/protos/vkCmdWaitEvents.adoc[] 5359 5360 * pname:commandBuffer is the command buffer into which the command is 5361 recorded. 5362 * pname:eventCount is the length of the pname:pEvents array. 5363 * pname:pEvents is a pointer to an array of event object handles to wait 5364 on. 5365 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 5366 specifying the <<synchronization-pipeline-stages, source stage mask>>. 5367 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 5368 specifying the <<synchronization-pipeline-stages, destination stage 5369 mask>>. 5370 * pname:memoryBarrierCount is the length of the pname:pMemoryBarriers 5371 array. 5372 * pname:pMemoryBarriers is a pointer to an array of slink:VkMemoryBarrier 5373 structures. 5374 * pname:bufferMemoryBarrierCount is the length of the 5375 pname:pBufferMemoryBarriers array. 5376 * pname:pBufferMemoryBarriers is a pointer to an array of 5377 slink:VkBufferMemoryBarrier structures. 5378 * pname:imageMemoryBarrierCount is the length of the 5379 pname:pImageMemoryBarriers array. 5380 * pname:pImageMemoryBarriers is a pointer to an array of 5381 slink:VkImageMemoryBarrier structures. 5382 5383ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5384fname:vkCmdWaitEvents is largely similar to flink:vkCmdWaitEvents2, but can: 5385only wait on signal operations defined by flink:vkCmdSetEvent. 5386As flink:vkCmdSetEvent does not define any access scopes, 5387fname:vkCmdWaitEvents defines the first access scope for each event signal 5388operation in addition to its own access scopes. 5389 5390[NOTE] 5391.Note 5392==== 5393Since flink:vkCmdSetEvent does not have any dependency information beyond a 5394stage mask, implementations do not have the same opportunity to perform 5395<<synchronization-dependencies-available-and-visible, availability and 5396visibility operations>> or <<synchronization-image-layout-transitions, image 5397layout transitions>> in advance as they do with flink:vkCmdSetEvent2 and 5398flink:vkCmdWaitEvents2. 5399==== 5400endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5401 5402When fname:vkCmdWaitEvents is submitted to a queue, it defines a memory 5403dependency between prior event signal operations on the same queue or the 5404host, and subsequent commands. 5405fname:vkCmdWaitEvents must: not be used to wait on event signal operations 5406occurring on other queues. 5407 5408The first synchronization scope only includes event signal operations that 5409operate on members of pname:pEvents, and the operations that happened-before 5410the event signal operations. 5411Event signal operations performed by flink:vkCmdSetEvent that occur earlier 5412in <<synchronization-submission-order,submission order>> are included in the 5413first synchronization scope, if the <<synchronization-pipeline-stages-order, 5414logically latest>> pipeline stage in their pname:stageMask parameter is 5415<<synchronization-pipeline-stages-order, logically earlier>> than or equal 5416to the <<synchronization-pipeline-stages-order, logically latest>> pipeline 5417stage in pname:srcStageMask. 5418Event signal operations performed by flink:vkSetEvent are only included in 5419the first synchronization scope if ename:VK_PIPELINE_STAGE_HOST_BIT is 5420included in pname:srcStageMask. 5421 5422The second <<synchronization-dependencies-scopes, synchronization scope>> 5423includes all commands that occur later in 5424<<synchronization-submission-order,submission order>>. 5425The second synchronization scope is limited to operations on the pipeline 5426stages determined by the <<synchronization-pipeline-stages-masks, 5427destination stage mask>> specified by pname:dstStageMask. 5428 5429The first <<synchronization-dependencies-access-scopes, access scope>> is 5430limited to accesses in the pipeline stages determined by the 5431<<synchronization-pipeline-stages-masks, source stage mask>> specified by 5432pname:srcStageMask. 5433Within that, the first access scope only includes the first access scopes 5434defined by elements of the pname:pMemoryBarriers, 5435pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which 5436each define a set of <<synchronization-memory-barriers, memory barriers>>. 5437If no memory barriers are specified, then the first access scope includes no 5438accesses. 5439 5440The second <<synchronization-dependencies-access-scopes, access scope>> is 5441limited to accesses in the pipeline stages determined by the 5442<<synchronization-pipeline-stages-masks, destination stage mask>> specified 5443by pname:dstStageMask. 5444Within that, the second access scope only includes the second access scopes 5445defined by elements of the pname:pMemoryBarriers, 5446pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which 5447each define a set of <<synchronization-memory-barriers, memory barriers>>. 5448If no memory barriers are specified, then the second access scope includes 5449no accesses. 5450 5451ifndef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5452[NOTE] 5453.Note 5454==== 5455flink:vkCmdWaitEvents is used with flink:vkCmdSetEvent to define a memory 5456dependency between two sets of action commands, roughly in the same way as 5457pipeline barriers, but split into two commands such that work between the 5458two may: execute unhindered. 5459 5460Unlike flink:vkCmdPipelineBarrier, a <<synchronization-queue-transfers, 5461queue family ownership transfer>> cannot: be performed using 5462flink:vkCmdWaitEvents. 5463==== 5464 5465[NOTE] 5466.Note 5467==== 5468Applications should be careful to avoid race conditions when using events. 5469There is no direct ordering guarantee between flink:vkCmdWaitEvents and 5470ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[flink:vkCmdResetEvent2,] 5471flink:vkCmdResetEvent, or flink:vkCmdSetEvent. 5472Another execution dependency (e.g. a pipeline barrier or semaphore with 5473ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT) is needed to prevent such a race 5474condition. 5475==== 5476endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5477 5478.Valid Usage 5479**** 5480:stageMaskName: srcStageMask 5481include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5482 5483:stageMaskName: dstStageMask 5484include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5485include::{chapters}/commonvalidity/fine_sync_commands_common.adoc[] 5486 * [[VUID-vkCmdWaitEvents-srcStageMask-06459]] 5487 Any pipeline stage included in pname:srcStageMask must: be supported by 5488 the capabilities of the queue family specified by the 5489 pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 5490 structure that was used to create the sname:VkCommandPool that 5491 pname:commandBuffer was allocated from, as specified in the 5492 <<synchronization-pipeline-stages-supported, table of supported pipeline 5493 stages>> 5494 * [[VUID-vkCmdWaitEvents-dstStageMask-06460]] 5495 Any pipeline stage included in pname:dstStageMask must: be supported by 5496 the capabilities of the queue family specified by the 5497 pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 5498 structure that was used to create the sname:VkCommandPool that 5499 pname:commandBuffer was allocated from, as specified in the 5500 <<synchronization-pipeline-stages-supported, table of supported pipeline 5501 stages>> 5502 * [[VUID-vkCmdWaitEvents-srcStageMask-01158]] 5503 pname:srcStageMask must: be the bitwise OR of the pname:stageMask 5504 parameter used in previous calls to fname:vkCmdSetEvent with any of the 5505 elements of pname:pEvents and ename:VK_PIPELINE_STAGE_HOST_BIT if any of 5506 the elements of pname:pEvents was set using fname:vkSetEvent 5507 * [[VUID-vkCmdWaitEvents-srcStageMask-07308]] 5508 If fname:vkCmdWaitEvents is being called inside a render pass instance, 5509 pname:srcStageMask must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 5510 * [[VUID-vkCmdWaitEvents-srcQueueFamilyIndex-02803]] 5511 The pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex members of 5512 any element of pname:pBufferMemoryBarriers or pname:pImageMemoryBarriers 5513 must: be equal 5514ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5515 * [[VUID-vkCmdWaitEvents-commandBuffer-01167]] 5516 pname:commandBuffer's current device mask must: include exactly one 5517 physical device 5518endif::VK_VERSION_1_1,VK_KHR_device_group[] 5519ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5520 * [[VUID-vkCmdWaitEvents-pEvents-03847]] 5521 Elements of pname:pEvents must: not have been signaled by 5522 flink:vkCmdSetEvent2 5523endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5524**** 5525 5526include::{generated}/validity/protos/vkCmdWaitEvents.adoc[] 5527-- 5528 5529 5530[[synchronization-pipeline-barriers]] 5531== Pipeline Barriers 5532 5533ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5534[open,refpage='vkCmdPipelineBarrier2',desc='Insert a memory dependency',type='protos',alias='vkCmdPipelineBarrier2KHR'] 5535-- 5536:refpage: vkCmdPipelineBarrier2 5537 5538To record a pipeline barrier, call: 5539 5540ifdef::VK_VERSION_1_3[] 5541include::{generated}/api/protos/vkCmdPipelineBarrier2.adoc[] 5542endif::VK_VERSION_1_3[] 5543 5544ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 5545 5546ifdef::VK_KHR_synchronization2[] 5547include::{generated}/api/protos/vkCmdPipelineBarrier2KHR.adoc[] 5548endif::VK_KHR_synchronization2[] 5549 5550 * pname:commandBuffer is the command buffer into which the command is 5551 recorded. 5552 * pname:pDependencyInfo is a pointer to a slink:VkDependencyInfo structure 5553 defining the scopes of this operation. 5554 5555When flink:vkCmdPipelineBarrier2 is submitted to a queue, it defines memory 5556dependencies between commands that were submitted before it, and those 5557submitted after it. 5558 5559The first <<synchronization-dependencies-scopes, synchronization scope>> and 5560<<synchronization-dependencies-access-scopes, access scope>> of each memory 5561dependency defined by pname:pDependencyInfo are applied to operations that 5562occurred earlier in <<synchronization-submission-order,submission order>>. 5563 5564The second <<synchronization-dependencies-scopes, synchronization scope>> 5565and <<synchronization-dependencies-access-scopes, access scope>> of each 5566memory dependency defined by pname:pDependencyInfo are applied to operations 5567that occurred later in <<synchronization-submission-order,submission 5568order>>. 5569 5570If fname:vkCmdPipelineBarrier2 is recorded within a render pass instance, 5571the synchronization scopes are 5572<<synchronization-pipeline-barriers-subpass-self-dependencies, limited to 5573operations within the same subpass>>. 5574 5575.Valid Usage 5576**** 5577include::{chapters}/commonvalidity/pipeline_barrier_common.adoc[] 5578 * [[VUID-vkCmdPipelineBarrier2-synchronization2-03848]] 5579 The <<features-synchronization2, pname:synchronization2>> feature must: 5580 be enabled 5581 * [[VUID-vkCmdPipelineBarrier2-srcStageMask-03849]] 5582 The pname:srcStageMask member of any element of the 5583 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 5584 pname:pImageMemoryBarriers members of pname:pDependencyInfo must: only 5585 include pipeline stages valid for the queue family that was used to 5586 create the command pool that pname:commandBuffer was allocated from 5587 * [[VUID-vkCmdPipelineBarrier2-dstStageMask-03850]] 5588 The pname:dstStageMask member of any element of the 5589 pname:pMemoryBarriers, pname:pBufferMemoryBarriers, or 5590 pname:pImageMemoryBarriers members of pname:pDependencyInfo must: only 5591 include pipeline stages valid for the queue family that was used to 5592 create the command pool that pname:commandBuffer was allocated from 5593**** 5594 5595include::{generated}/validity/protos/vkCmdPipelineBarrier2.adoc[] 5596-- 5597endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5598 5599[open,refpage='vkCmdPipelineBarrier',desc='Insert a memory dependency',type='protos'] 5600-- 5601:refpage: vkCmdPipelineBarrier 5602 5603To record a pipeline barrier, call: 5604 5605include::{generated}/api/protos/vkCmdPipelineBarrier.adoc[] 5606 5607 * pname:commandBuffer is the command buffer into which the command is 5608 recorded. 5609 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 5610 specifying the <<synchronization-pipeline-stages-masks,source stages>>. 5611 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 5612 specifying the <<synchronization-pipeline-stages-masks,destination 5613 stages>>. 5614 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits 5615 specifying how execution and memory dependencies are formed. 5616 * pname:memoryBarrierCount is the length of the pname:pMemoryBarriers 5617 array. 5618 * pname:pMemoryBarriers is a pointer to an array of slink:VkMemoryBarrier 5619 structures. 5620 * pname:bufferMemoryBarrierCount is the length of the 5621 pname:pBufferMemoryBarriers array. 5622 * pname:pBufferMemoryBarriers is a pointer to an array of 5623 slink:VkBufferMemoryBarrier structures. 5624 * pname:imageMemoryBarrierCount is the length of the 5625 pname:pImageMemoryBarriers array. 5626 * pname:pImageMemoryBarriers is a pointer to an array of 5627 slink:VkImageMemoryBarrier structures. 5628 5629ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5630fname:vkCmdPipelineBarrier operates almost identically to 5631flink:vkCmdPipelineBarrier2, except that the scopes and barriers are defined 5632as direct parameters rather than being defined by an slink:VkDependencyInfo. 5633endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5634 5635When flink:vkCmdPipelineBarrier is submitted to a queue, it defines a memory 5636dependency between commands that were submitted before it, and those 5637submitted after it. 5638 5639If flink:vkCmdPipelineBarrier was recorded outside a render pass instance, 5640the first <<synchronization-dependencies-scopes, synchronization scope>> 5641includes all commands that occur earlier in 5642<<synchronization-submission-order,submission order>>. 5643If flink:vkCmdPipelineBarrier was recorded inside a render pass instance, 5644the first synchronization scope includes only commands that occur earlier in 5645<<synchronization-submission-order,submission order>> within the same 5646subpass. 5647In either case, the first synchronization scope is limited to operations on 5648the pipeline stages determined by the 5649<<synchronization-pipeline-stages-masks, source stage mask>> specified by 5650pname:srcStageMask. 5651 5652If flink:vkCmdPipelineBarrier was recorded outside a render pass instance, 5653the second <<synchronization-dependencies-scopes, synchronization scope>> 5654includes all commands that occur later in 5655<<synchronization-submission-order,submission order>>. 5656If flink:vkCmdPipelineBarrier was recorded inside a render pass instance, 5657the second synchronization scope includes only commands that occur later in 5658<<synchronization-submission-order,submission order>> within the same 5659subpass. 5660In either case, the second synchronization scope is limited to operations on 5661the pipeline stages determined by the 5662<<synchronization-pipeline-stages-masks, destination stage mask>> specified 5663by pname:dstStageMask. 5664 5665The first <<synchronization-dependencies-access-scopes, access scope>> is 5666limited to accesses in the pipeline stages determined by the 5667<<synchronization-pipeline-stages-masks, source stage mask>> specified by 5668pname:srcStageMask. 5669Within that, the first access scope only includes the first access scopes 5670defined by elements of the pname:pMemoryBarriers, 5671pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which 5672each define a set of <<synchronization-memory-barriers, memory barriers>>. 5673If no memory barriers are specified, then the first access scope includes no 5674accesses. 5675 5676The second <<synchronization-dependencies-access-scopes, access scope>> is 5677limited to accesses in the pipeline stages determined by the 5678<<synchronization-pipeline-stages-masks, destination stage mask>> specified 5679by pname:dstStageMask. 5680Within that, the second access scope only includes the second access scopes 5681defined by elements of the pname:pMemoryBarriers, 5682pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which 5683each define a set of <<synchronization-memory-barriers, memory barriers>>. 5684If no memory barriers are specified, then the second access scope includes 5685no accesses. 5686 5687If pname:dependencyFlags includes ename:VK_DEPENDENCY_BY_REGION_BIT, then 5688any dependency between <<synchronization-framebuffer-regions, 5689framebuffer-space>> pipeline stages is 5690<<synchronization-framebuffer-regions, framebuffer-local>> - otherwise it is 5691<<synchronization-framebuffer-regions, framebuffer-global>>. 5692 5693.Valid Usage 5694**** 5695:stageMaskName: srcStageMask 5696include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5697 5698:stageMaskName: dstStageMask 5699include::{chapters}/commonvalidity/stage_mask_common.adoc[] 5700include::{chapters}/commonvalidity/fine_sync_commands_common.adoc[] 5701include::{chapters}/commonvalidity/pipeline_barrier_common.adoc[] 5702 * [[VUID-vkCmdPipelineBarrier-srcStageMask-06461]] 5703 Any pipeline stage included in pname:srcStageMask must: be supported by 5704 the capabilities of the queue family specified by the 5705 pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 5706 structure that was used to create the sname:VkCommandPool that 5707 pname:commandBuffer was allocated from, as specified in the 5708 <<synchronization-pipeline-stages-supported, table of supported pipeline 5709 stages>> 5710 * [[VUID-vkCmdPipelineBarrier-dstStageMask-06462]] 5711 Any pipeline stage included in pname:dstStageMask must: be supported by 5712 the capabilities of the queue family specified by the 5713 pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 5714 structure that was used to create the sname:VkCommandPool that 5715 pname:commandBuffer was allocated from, as specified in the 5716 <<synchronization-pipeline-stages-supported, table of supported pipeline 5717 stages>> 5718**** 5719 5720include::{generated}/validity/protos/vkCmdPipelineBarrier.adoc[] 5721-- 5722 5723[open,refpage='VkDependencyFlagBits',desc='Bitmask specifying how execution and memory dependencies are formed',type='enums'] 5724-- 5725Bits which can: be set in fname:vkCmdPipelineBarrier::pname:dependencyFlags, 5726specifying how execution and memory dependencies are formed, are: 5727 5728include::{generated}/api/enums/VkDependencyFlagBits.adoc[] 5729 5730 * ename:VK_DEPENDENCY_BY_REGION_BIT specifies that dependencies will be 5731 <<synchronization-framebuffer-regions, framebuffer-local>>. 5732ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 5733 * ename:VK_DEPENDENCY_VIEW_LOCAL_BIT specifies that a 5734 <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass 5735 has more than one view>>. 5736endif::VK_VERSION_1_1,VK_KHR_multiview[] 5737ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5738 * ename:VK_DEPENDENCY_DEVICE_GROUP_BIT specifies that dependencies are 5739 <<synchronization-device-local-dependencies, non-device-local>>. 5740endif::VK_VERSION_1_1,VK_KHR_device_group[] 5741ifdef::VK_EXT_attachment_feedback_loop_layout[] 5742 * ename:VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXT specifies that the render pass 5743 will write to and read from the same image using the 5744 ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout. 5745endif::VK_EXT_attachment_feedback_loop_layout[] 5746-- 5747 5748[open,refpage='VkDependencyFlags',desc='Bitmask of VkDependencyFlagBits',type='flags'] 5749-- 5750include::{generated}/api/flags/VkDependencyFlags.adoc[] 5751 5752tname:VkDependencyFlags is a bitmask type for setting a mask of zero or more 5753elink:VkDependencyFlagBits. 5754-- 5755 5756 5757[[synchronization-pipeline-barriers-subpass-self-dependencies]] 5758=== Subpass Self-dependency 5759 5760ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 5761flink:vkCmdPipelineBarrier 5762ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5763or flink:vkCmdPipelineBarrier2 5764endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5765must: not be called within a render pass instance started with 5766flink:vkCmdBeginRendering. 5767endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 5768 5769If flink:vkCmdPipelineBarrier 5770ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5771or flink:vkCmdPipelineBarrier2 5772endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5773is called inside a render pass instance, the following restrictions apply. 5774For a given subpass to allow a pipeline barrier, the render pass must: 5775declare a _self-dependency_ from that subpass to itself. 5776That is, there must: exist a subpass dependency with pname:srcSubpass and 5777pname:dstSubpass both equal to that subpass index. 5778More than one self-dependency can: be declared for each subpass. 5779 5780Self-dependencies must: only include pipeline stage bits that are graphics 5781stages. 5782If any of the stages in pname:srcStageMask are 5783<<synchronization-framebuffer-regions,framebuffer-space stages>>, 5784pname:dstStageMask must: only contain 5785<<synchronization-framebuffer-regions,framebuffer-space stages>>. 5786This means that pseudo-stages like ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT 5787which include the execution of both framebuffer-space stages and 5788non-framebuffer-space stages must: not be used. 5789 5790If the source and destination stage masks both include framebuffer-space 5791stages, then pname:dependencyFlags must: include 5792ename:VK_DEPENDENCY_BY_REGION_BIT. 5793ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 5794If the subpass has more than one view, then pname:dependencyFlags must: 5795include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT. 5796endif::VK_VERSION_1_1,VK_KHR_multiview[] 5797 5798Each of the <<synchronization-dependencies-scopes, synchronization scopes>> 5799and <<synchronization-dependencies-access-scopes, access scopes>> of a 5800ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5801flink:vkCmdPipelineBarrier2 or 5802endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5803flink:vkCmdPipelineBarrier command inside a render pass instance must: be a 5804subset of the scopes of one of the self-dependencies for the current 5805subpass. 5806 5807If the self-dependency has ename:VK_DEPENDENCY_BY_REGION_BIT 5808ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 5809or ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 5810endif::VK_VERSION_1_1,VK_KHR_multiview[] 5811set, then so must: the pipeline barrier. 5812Pipeline barriers within a render pass instance must: not include buffer 5813memory barriers. 5814Image memory barriers must: only specify image subresources that are used as 5815attachments within the subpass, and must: not define an 5816<<synchronization-image-layout-transitions, image layout transition>> or 5817<<synchronization-queue-transfers, queue family ownership transfer>>. 5818 5819 5820[[synchronization-memory-barriers]] 5821== Memory Barriers 5822 5823_Memory barriers_ are used to explicitly control access to buffer and image 5824subresource ranges. 5825Memory barriers are used to <<synchronization-queue-transfers, transfer 5826ownership between queue families>>, 5827<<synchronization-image-layout-transitions, change image layouts>>, and 5828define <<synchronization-dependencies-available-and-visible, availability 5829and visibility operations>>. 5830They explicitly define the <<synchronization-access-types, access types>> 5831and buffer and image subresource ranges that are included in the 5832<<synchronization-dependencies-access-scopes, access scopes>> of a memory 5833dependency that is created by a synchronization command that includes them. 5834 5835 5836[[synchronization-global-memory-barriers]] 5837=== Global Memory Barriers 5838 5839Global memory barriers apply to memory accesses involving all memory objects 5840that exist at the time of its execution. 5841 5842ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5843[open,refpage='VkMemoryBarrier2',desc='Structure specifying a global memory barrier',type='structs',alias='VkMemoryBarrier2KHR'] 5844-- 5845:refpage: VkMemoryBarrier2 5846 5847The sname:VkMemoryBarrier2 structure is defined as: 5848 5849include::{generated}/api/structs/VkMemoryBarrier2.adoc[] 5850 5851ifdef::VK_KHR_synchronization2[] 5852or the equivalent 5853 5854include::{generated}/api/structs/VkMemoryBarrier2KHR.adoc[] 5855endif::VK_KHR_synchronization2[] 5856 5857 * pname:sType is the type of this structure. 5858 * pname:pNext is `NULL` or a pointer to a structure extending this 5859 structure. 5860 * pname:srcStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 5861 stages to be included in the <<synchronization-dependencies-scopes, 5862 first synchronization scope>>. 5863 * pname:srcAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 5864 included in the <<synchronization-dependencies-access-scopes, first 5865 access scope>>. 5866 * pname:dstStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 5867 stages to be included in the <<synchronization-dependencies-scopes, 5868 second synchronization scope>>. 5869 * pname:dstAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 5870 included in the <<synchronization-dependencies-access-scopes, second 5871 access scope>>. 5872 5873This structure defines a <<synchronization-dependencies-memory, memory 5874dependency>> affecting all device memory. 5875 5876The first <<synchronization-dependencies-scopes, synchronization scope>> and 5877<<synchronization-dependencies-access-scopes, access scope>> described by 5878this structure include only operations and memory accesses specified by 5879pname:srcStageMask and pname:srcAccessMask. 5880 5881The second <<synchronization-dependencies-scopes, synchronization scope>> 5882and <<synchronization-dependencies-access-scopes, access scope>> described 5883by this structure include only operations and memory accesses specified by 5884pname:dstStageMask and pname:dstAccessMask. 5885 5886.Valid Usage 5887**** 5888:stageMaskName: srcStageMask 5889:accessMaskName: srcAccessMask 5890include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 5891include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 5892 5893:stageMaskName: dstStageMask 5894:accessMaskName: dstAccessMask 5895include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 5896include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 5897**** 5898 5899include::{generated}/validity/structs/VkMemoryBarrier2.adoc[] 5900-- 5901endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 5902 5903[open,refpage='VkMemoryBarrier',desc='Structure specifying a global memory barrier',type='structs'] 5904-- 5905The sname:VkMemoryBarrier structure is defined as: 5906 5907include::{generated}/api/structs/VkMemoryBarrier.adoc[] 5908 5909 * pname:sType is the type of this structure. 5910 * pname:pNext is `NULL` or a pointer to a structure extending this 5911 structure. 5912 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 5913 <<synchronization-access-masks, source access mask>>. 5914 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 5915 <<synchronization-access-masks, destination access mask>>. 5916 5917The first <<synchronization-dependencies-access-scopes, access scope>> is 5918limited to access types in the <<synchronization-access-masks, source access 5919mask>> specified by pname:srcAccessMask. 5920 5921The second <<synchronization-dependencies-access-scopes, access scope>> is 5922limited to access types in the <<synchronization-access-masks, destination 5923access mask>> specified by pname:dstAccessMask. 5924 5925include::{generated}/validity/structs/VkMemoryBarrier.adoc[] 5926-- 5927 5928 5929[[synchronization-buffer-memory-barriers]] 5930=== Buffer Memory Barriers 5931 5932Buffer memory barriers only apply to memory accesses involving a specific 5933buffer range. 5934That is, a memory dependency formed from a buffer memory barrier is 5935<<synchronization-dependencies-access-scopes, scoped>> to access via the 5936specified buffer range. 5937Buffer memory barriers can: also be used to define a 5938<<synchronization-queue-transfers, queue family ownership transfer>> for the 5939specified buffer range. 5940 5941ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 5942[open,refpage='VkBufferMemoryBarrier2',desc='Structure specifying a buffer memory barrier',type='structs',alias='VkBufferMemoryBarrier2KHR'] 5943-- 5944:refpage: VkBufferMemoryBarrier2 5945 5946The sname:VkBufferMemoryBarrier2 structure is defined as: 5947 5948include::{generated}/api/structs/VkBufferMemoryBarrier2.adoc[] 5949 5950ifdef::VK_KHR_synchronization2[] 5951or the equivalent 5952 5953include::{generated}/api/structs/VkBufferMemoryBarrier2KHR.adoc[] 5954endif::VK_KHR_synchronization2[] 5955 5956 * pname:sType is the type of this structure. 5957 * pname:pNext is `NULL` or a pointer to a structure extending this 5958 structure. 5959 * pname:srcStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 5960 stages to be included in the <<synchronization-dependencies-scopes, 5961 first synchronization scope>>. 5962 * pname:srcAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 5963 included in the <<synchronization-dependencies-access-scopes, first 5964 access scope>>. 5965 * pname:dstStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 5966 stages to be included in the <<synchronization-dependencies-scopes, 5967 second synchronization scope>>. 5968 * pname:dstAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 5969 included in the <<synchronization-dependencies-access-scopes, second 5970 access scope>>. 5971 * pname:srcQueueFamilyIndex is the source queue family for a 5972 <<synchronization-queue-transfers, queue family ownership transfer>>. 5973 * pname:dstQueueFamilyIndex is the destination queue family for a 5974 <<synchronization-queue-transfers, queue family ownership transfer>>. 5975 * pname:buffer is a handle to the buffer whose backing memory is affected 5976 by the barrier. 5977 * pname:offset is an offset in bytes into the backing memory for 5978 pname:buffer; this is relative to the base offset as bound to the buffer 5979 (see flink:vkBindBufferMemory). 5980 * pname:size is a size in bytes of the affected area of backing memory for 5981 pname:buffer, or ename:VK_WHOLE_SIZE to use the range from pname:offset 5982 to the end of the buffer. 5983 5984This structure defines a <<synchronization-dependencies-memory, memory 5985dependency>> limited to a range of a buffer, and can: define a 5986<<synchronization-queue-transfers, queue family transfer operation>> for 5987that range. 5988 5989The first <<synchronization-dependencies-scopes, synchronization scope>> and 5990<<synchronization-dependencies-access-scopes, access scope>> described by 5991this structure include only operations and memory accesses specified by 5992pname:srcStageMask and pname:srcAccessMask. 5993 5994The second <<synchronization-dependencies-scopes, synchronization scope>> 5995and <<synchronization-dependencies-access-scopes, access scope>> described 5996by this structure include only operations and memory accesses specified by 5997pname:dstStageMask and pname:dstAccessMask. 5998 5999Both <<synchronization-dependencies-access-scopes, access scopes>> are 6000limited to only memory accesses to pname:buffer in the range defined by 6001pname:offset and pname:size. 6002 6003If pname:buffer was created with ename:VK_SHARING_MODE_EXCLUSIVE, and 6004pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, this 6005memory barrier defines a <<synchronization-queue-transfers, queue family 6006transfer operation>>. 6007When executed on a queue in the family identified by 6008pname:srcQueueFamilyIndex, this barrier defines a 6009<<synchronization-queue-transfers-release, queue family release operation>> 6010for the specified buffer range, and the second synchronization and access 6011scopes do not synchronize operations on that queue. 6012When executed on a queue in the family identified by 6013pname:dstQueueFamilyIndex, this barrier defines a 6014<<synchronization-queue-transfers-acquire, queue family acquire operation>> 6015for the specified buffer range, and the first synchronization and access 6016scopes do not synchronize operations on that queue. 6017 6018ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6019A <<synchronization-queue-transfers, queue family transfer operation>> is 6020also defined if the values are not equal, and either is one of the special 6021queue family values reserved for external memory ownership transfers, as 6022described in <<synchronization-queue-transfers>>. 6023A <<synchronization-queue-transfers-release, queue family release 6024operation>> is defined when pname:dstQueueFamilyIndex is one of those 6025values, and a <<synchronization-queue-transfers-acquire, queue family 6026acquire operation>> is defined when pname:srcQueueFamilyIndex is one of 6027those values. 6028endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6029 6030 6031.Valid Usage 6032**** 6033 6034:stageMaskName: srcStageMask 6035:accessMaskName: srcAccessMask 6036include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 6037include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 6038 6039:stageMaskName: dstStageMask 6040:accessMaskName: dstAccessMask 6041include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 6042include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 6043include::{chapters}/commonvalidity/buffer_memory_barrier_common.adoc[] 6044 * [[VUID-VkBufferMemoryBarrier2-srcStageMask-03851]] 6045 If either pname:srcStageMask or pname:dstStageMask includes 6046 ename:VK_PIPELINE_STAGE_2_HOST_BIT, pname:srcQueueFamilyIndex and 6047 pname:dstQueueFamilyIndex must: be equal 6048**** 6049 6050include::{generated}/validity/structs/VkBufferMemoryBarrier2.adoc[] 6051-- 6052endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6053 6054[open,refpage='VkBufferMemoryBarrier',desc='Structure specifying a buffer memory barrier',type='structs'] 6055-- 6056:refpage: VkBufferMemoryBarrier 6057 6058The sname:VkBufferMemoryBarrier structure is defined as: 6059 6060include::{generated}/api/structs/VkBufferMemoryBarrier.adoc[] 6061 6062 * pname:sType is the type of this structure. 6063 * pname:pNext is `NULL` or a pointer to a structure extending this 6064 structure. 6065 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 6066 <<synchronization-access-masks, source access mask>>. 6067 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 6068 <<synchronization-access-masks, destination access mask>>. 6069 * pname:srcQueueFamilyIndex is the source queue family for a 6070 <<synchronization-queue-transfers, queue family ownership transfer>>. 6071 * pname:dstQueueFamilyIndex is the destination queue family for a 6072 <<synchronization-queue-transfers, queue family ownership transfer>>. 6073 * pname:buffer is a handle to the buffer whose backing memory is affected 6074 by the barrier. 6075 * pname:offset is an offset in bytes into the backing memory for 6076 pname:buffer; this is relative to the base offset as bound to the buffer 6077 (see flink:vkBindBufferMemory). 6078 * pname:size is a size in bytes of the affected area of backing memory for 6079 pname:buffer, or ename:VK_WHOLE_SIZE to use the range from pname:offset 6080 to the end of the buffer. 6081 6082The first <<synchronization-dependencies-access-scopes, access scope>> is 6083limited to access to memory through the specified buffer range, via access 6084types in the <<synchronization-access-masks, source access mask>> specified 6085by pname:srcAccessMask. 6086If pname:srcAccessMask includes ename:VK_ACCESS_HOST_WRITE_BIT, a 6087<<synchronization-dependencies-available-and-visible, memory domain 6088operation>> is performed where available memory in the host domain is also 6089made available to the device domain. 6090 6091The second <<synchronization-dependencies-access-scopes, access scope>> is 6092limited to access to memory through the specified buffer range, via access 6093types in the <<synchronization-access-masks, destination access mask>> 6094specified by pname:dstAccessMask. 6095If pname:dstAccessMask includes ename:VK_ACCESS_HOST_WRITE_BIT or 6096ename:VK_ACCESS_HOST_READ_BIT, a 6097<<synchronization-dependencies-available-and-visible, memory domain 6098operation>> is performed where available memory in the device domain is also 6099made available to the host domain. 6100 6101[NOTE] 6102.Note 6103==== 6104When ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT is used, available memory in 6105host domain is automatically made visible to host domain, and any host write 6106is automatically made available to host domain. 6107==== 6108 6109If pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, and 6110pname:srcQueueFamilyIndex is equal to the current queue family, then the 6111memory barrier defines a <<synchronization-queue-transfers-release, queue 6112family release operation>> for the specified buffer range, and the second 6113access scope includes no access, as if pname:dstAccessMask was `0`. 6114 6115If pname:dstQueueFamilyIndex is not equal to pname:srcQueueFamilyIndex, and 6116pname:dstQueueFamilyIndex is equal to the current queue family, then the 6117memory barrier defines a <<synchronization-queue-transfers-acquire, queue 6118family acquire operation>> for the specified buffer range, and the first 6119access scope includes no access, as if pname:srcAccessMask was `0`. 6120 6121.Valid Usage 6122**** 6123include::{chapters}/commonvalidity/buffer_memory_barrier_common.adoc[] 6124ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 6125 * [[VUID-VkBufferMemoryBarrier-synchronization2-03852]] 6126 If the <<features-synchronization2, pname:synchronization2>> feature is 6127 not enabled, and pname:buffer was created with a sharing mode of 6128 ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and 6129 pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED 6130endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6131ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6132 * [[VUID-VkBufferMemoryBarrier-synchronization2-03853]] 6133 If the <<features-synchronization2, pname:synchronization2>> feature is 6134 not enabled, and pname:buffer was created with a sharing mode of 6135 ename:VK_SHARING_MODE_CONCURRENT, at least one of 6136 pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: be 6137 ename:VK_QUEUE_FAMILY_IGNORED 6138endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6139**** 6140 6141include::{generated}/validity/structs/VkBufferMemoryBarrier.adoc[] 6142-- 6143 6144[open,refpage='VK_WHOLE_SIZE',desc='Sentinel value to use entire remaining array length',type='consts'] 6145-- 6146ename:VK_WHOLE_SIZE is a special value indicating that the entire remaining 6147length of a buffer following a given pname:offset should be used. 6148It can: be specified for slink:VkBufferMemoryBarrier::pname:size and other 6149structures. 6150 6151include::{generated}/api/enums/VK_WHOLE_SIZE.adoc[] 6152-- 6153 6154 6155[[synchronization-image-memory-barriers]] 6156=== Image Memory Barriers 6157 6158Image memory barriers only apply to memory accesses involving a specific 6159image subresource range. 6160That is, a memory dependency formed from an image memory barrier is 6161<<synchronization-dependencies-access-scopes, scoped>> to access via the 6162specified image subresource range. 6163Image memory barriers can: also be used to define 6164<<synchronization-image-layout-transitions, image layout transitions>> or a 6165<<synchronization-queue-transfers, queue family ownership transfer>> for the 6166specified image subresource range. 6167 6168ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 6169[open,refpage='VkImageMemoryBarrier2',desc='Structure specifying an image memory barrier',type='structs',alias='VkImageMemoryBarrier2KHR'] 6170-- 6171:refpage: VkImageMemoryBarrier2 6172 6173The sname:VkImageMemoryBarrier2 structure is defined as: 6174 6175include::{generated}/api/structs/VkImageMemoryBarrier2.adoc[] 6176 6177ifdef::VK_KHR_synchronization2[] 6178or the equivalent 6179 6180include::{generated}/api/structs/VkImageMemoryBarrier2KHR.adoc[] 6181endif::VK_KHR_synchronization2[] 6182 6183 * pname:sType is the type of this structure. 6184 * pname:pNext is `NULL` or a pointer to a structure extending this 6185 structure. 6186 * pname:srcStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 6187 stages to be included in the <<synchronization-dependencies-scopes, 6188 first synchronization scope>>. 6189 * pname:srcAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 6190 included in the <<synchronization-dependencies-access-scopes, first 6191 access scope>>. 6192 * pname:dstStageMask is a tlink:VkPipelineStageFlags2 mask of pipeline 6193 stages to be included in the <<synchronization-dependencies-scopes, 6194 second synchronization scope>>. 6195 * pname:dstAccessMask is a tlink:VkAccessFlags2 mask of access flags to be 6196 included in the <<synchronization-dependencies-access-scopes, second 6197 access scope>>. 6198 * pname:oldLayout is the old layout in an 6199 <<synchronization-image-layout-transitions, image layout transition>>. 6200 * pname:newLayout is the new layout in an 6201 <<synchronization-image-layout-transitions, image layout transition>>. 6202 * pname:srcQueueFamilyIndex is the source queue family for a 6203 <<synchronization-queue-transfers, queue family ownership transfer>>. 6204 * pname:dstQueueFamilyIndex is the destination queue family for a 6205 <<synchronization-queue-transfers, queue family ownership transfer>>. 6206 * pname:image is a handle to the image affected by this barrier. 6207 * pname:subresourceRange describes the <<resources-image-views, image 6208 subresource range>> within pname:image that is affected by this barrier. 6209 6210This structure defines a <<synchronization-dependencies-memory, memory 6211dependency>> limited to an image subresource range, and can: define a 6212<<synchronization-queue-transfers, queue family transfer operation>> and 6213<<synchronization-image-layout-transitions, image layout transition>> for 6214that subresource range. 6215 6216The first <<synchronization-dependencies-scopes, synchronization scope>> and 6217<<synchronization-dependencies-access-scopes, access scope>> described by 6218this structure include only operations and memory accesses specified by 6219pname:srcStageMask and pname:srcAccessMask. 6220 6221The second <<synchronization-dependencies-scopes, synchronization scope>> 6222and <<synchronization-dependencies-access-scopes, access scope>> described 6223by this structure include only operations and memory accesses specified by 6224pname:dstStageMask and pname:dstAccessMask. 6225 6226Both <<synchronization-dependencies-access-scopes, access scopes>> are 6227limited to only memory accesses to pname:image in the subresource range 6228defined by pname:subresourceRange. 6229 6230If pname:image was created with ename:VK_SHARING_MODE_EXCLUSIVE, and 6231pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, this 6232memory barrier defines a <<synchronization-queue-transfers, queue family 6233transfer operation>>. 6234When executed on a queue in the family identified by 6235pname:srcQueueFamilyIndex, this barrier defines a 6236<<synchronization-queue-transfers-release, queue family release operation>> 6237for the specified image subresource range, and the second synchronization 6238and access scopes do not synchronize operations on that queue. 6239When executed on a queue in the family identified by 6240pname:dstQueueFamilyIndex, this barrier defines a 6241<<synchronization-queue-transfers-acquire, queue family acquire operation>> 6242for the specified image subresource range, and the first synchronization and 6243access scopes do not synchronize operations on that queue. 6244 6245ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6246A <<synchronization-queue-transfers, queue family transfer operation>> is 6247also defined if the values are not equal, and either is one of the special 6248queue family values reserved for external memory ownership transfers, as 6249described in <<synchronization-queue-transfers>>. 6250A <<synchronization-queue-transfers-release, queue family release 6251operation>> is defined when pname:dstQueueFamilyIndex is one of those 6252values, and a <<synchronization-queue-transfers-acquire, queue family 6253acquire operation>> is defined when pname:srcQueueFamilyIndex is one of 6254those values. 6255endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6256 6257If pname:oldLayout is not equal to pname:newLayout, then the memory barrier 6258defines an <<synchronization-image-layout-transitions, image layout 6259transition>> for the specified image subresource range. 6260If this memory barrier defines a <<synchronization-queue-transfers, queue 6261family transfer operation>>, the layout transition is only executed once 6262between the queues. 6263 6264[NOTE] 6265.Note 6266==== 6267When the old and new layout are equal, the layout values are ignored - data 6268is preserved no matter what values are specified, or what layout the image 6269is currently in. 6270==== 6271 6272ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6273 6274If pname:image has a multi-planar format and the image is _disjoint_, then 6275including ename:VK_IMAGE_ASPECT_COLOR_BIT in the pname:aspectMask member of 6276pname:subresourceRange is equivalent to including 6277ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and 6278(for three-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 6279 6280endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6281 6282.Valid Usage 6283**** 6284 6285:stageMaskName: srcStageMask 6286:accessMaskName: srcAccessMask 6287include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 6288include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 6289 6290:stageMaskName: dstStageMask 6291:accessMaskName: dstAccessMask 6292include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 6293include::{chapters}/commonvalidity/access_mask_2_common.adoc[] 6294include::{chapters}/commonvalidity/image_memory_barrier_common.adoc[] 6295 * [[VUID-VkImageMemoryBarrier2-srcStageMask-03854]] 6296 If either pname:srcStageMask or pname:dstStageMask includes 6297 ename:VK_PIPELINE_STAGE_2_HOST_BIT, pname:srcQueueFamilyIndex and 6298 pname:dstQueueFamilyIndex must: be equal 6299 * [[VUID-VkImageMemoryBarrier2-srcStageMask-03855]] 6300 If pname:srcStageMask includes ename:VK_PIPELINE_STAGE_2_HOST_BIT, and 6301 pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex define a 6302 <<synchronization-queue-transfers, queue family ownership transfer>> or 6303 pname:oldLayout and pname:newLayout define an 6304 <<synchronization-image-layout-transitions, image layout transition>>, 6305 pname:oldLayout must: be one of ename:VK_IMAGE_LAYOUT_PREINITIALIZED, 6306 ename:VK_IMAGE_LAYOUT_UNDEFINED, or ename:VK_IMAGE_LAYOUT_GENERAL 6307**** 6308 6309include::{generated}/validity/structs/VkImageMemoryBarrier2.adoc[] 6310-- 6311endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6312 6313[open,refpage='VkImageMemoryBarrier',desc='Structure specifying the parameters of an image memory barrier',type='structs'] 6314-- 6315:refpage: VkImageMemoryBarrier 6316 6317The sname:VkImageMemoryBarrier structure is defined as: 6318 6319include::{generated}/api/structs/VkImageMemoryBarrier.adoc[] 6320 6321 * pname:sType is the type of this structure. 6322 * pname:pNext is `NULL` or a pointer to a structure extending this 6323 structure. 6324 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 6325 <<synchronization-access-masks, source access mask>>. 6326 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 6327 <<synchronization-access-masks, destination access mask>>. 6328 * pname:oldLayout is the old layout in an 6329 <<synchronization-image-layout-transitions, image layout transition>>. 6330 * pname:newLayout is the new layout in an 6331 <<synchronization-image-layout-transitions, image layout transition>>. 6332 * pname:srcQueueFamilyIndex is the source queue family for a 6333 <<synchronization-queue-transfers, queue family ownership transfer>>. 6334 * pname:dstQueueFamilyIndex is the destination queue family for a 6335 <<synchronization-queue-transfers, queue family ownership transfer>>. 6336 * pname:image is a handle to the image affected by this barrier. 6337 * pname:subresourceRange describes the <<resources-image-views, image 6338 subresource range>> within pname:image that is affected by this barrier. 6339 6340The first <<synchronization-dependencies-access-scopes, access scope>> is 6341limited to access to memory through the specified image subresource range, 6342via access types in the <<synchronization-access-masks, source access mask>> 6343specified by pname:srcAccessMask. 6344If pname:srcAccessMask includes ename:VK_ACCESS_HOST_WRITE_BIT, memory 6345writes performed by that access type are also made visible, as that access 6346type is not performed through a resource. 6347 6348The second <<synchronization-dependencies-access-scopes, access scope>> is 6349limited to access to memory through the specified image subresource range, 6350via access types in the <<synchronization-access-masks, destination access 6351mask>> specified by pname:dstAccessMask. 6352If pname:dstAccessMask includes ename:VK_ACCESS_HOST_WRITE_BIT or 6353ename:VK_ACCESS_HOST_READ_BIT, available memory writes are also made visible 6354to accesses of those types, as those access types are not performed through 6355a resource. 6356 6357If pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, and 6358pname:srcQueueFamilyIndex is equal to the current queue family, then the 6359memory barrier defines a <<synchronization-queue-transfers-release, queue 6360family release operation>> for the specified image subresource range, and 6361the second access scope includes no access, as if pname:dstAccessMask was 6362`0`. 6363 6364If pname:dstQueueFamilyIndex is not equal to pname:srcQueueFamilyIndex, and 6365pname:dstQueueFamilyIndex is equal to the current queue family, then the 6366memory barrier defines a <<synchronization-queue-transfers-acquire, queue 6367family acquire operation>> for the specified image subresource range, and 6368the first access scope includes no access, as if pname:srcAccessMask was 6369`0`. 6370 6371ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 6372If the <<features-synchronization2, pname:synchronization2>> feature is not 6373enabled or pname:oldLayout is not equal to pname:newLayout, 6374endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6375pname:oldLayout and pname:newLayout define an 6376<<synchronization-image-layout-transitions, image layout transition>> for 6377the specified image subresource range. 6378 6379ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 6380[NOTE] 6381.Note 6382==== 6383If the <<features-synchronization2, pname:synchronization2>> feature is 6384enabled, when the old and new layout are equal, the layout values are 6385ignored - data is preserved no matter what values are specified, or what 6386layout the image is currently in. 6387==== 6388endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6389 6390ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6391 6392If pname:image has a multi-planar format and the image is _disjoint_, then 6393including ename:VK_IMAGE_ASPECT_COLOR_BIT in the pname:aspectMask member of 6394pname:subresourceRange is equivalent to including 6395ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and 6396(for three-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 6397 6398endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6399 6400.Valid Usage 6401**** 6402include::{chapters}/commonvalidity/image_memory_barrier_common.adoc[] 6403ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 6404 * [[VUID-VkImageMemoryBarrier-synchronization2-03856]] 6405 If the <<features-synchronization2, pname:synchronization2>> feature is 6406 not enabled, and pname:image was created with a sharing mode of 6407 ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and 6408 pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED 6409endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6410ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6411 * [[VUID-VkImageMemoryBarrier-synchronization2-03857]] 6412 If the <<features-synchronization2, pname:synchronization2>> feature is 6413 not enabled, and pname:image was created with a sharing mode of 6414 ename:VK_SHARING_MODE_CONCURRENT, at least one of 6415 pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: be 6416 ename:VK_QUEUE_FAMILY_IGNORED 6417endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6418**** 6419 6420include::{generated}/validity/structs/VkImageMemoryBarrier.adoc[] 6421-- 6422 6423 6424[[synchronization-queue-transfers]] 6425=== Queue Family Ownership Transfer 6426 6427Resources created with a elink:VkSharingMode of 6428ename:VK_SHARING_MODE_EXCLUSIVE must: have their ownership explicitly 6429transferred from one queue family to another in order to access their 6430content in a well-defined manner on a queue in a different queue family. 6431 6432[open,refpage='VK_QUEUE_FAMILY_IGNORED',desc='Ignored queue family index sentinel',type='consts'] 6433-- 6434The special queue family index ename:VK_QUEUE_FAMILY_IGNORED indicates that 6435a queue family parameter or member is ignored. 6436 6437include::{generated}/api/enums/VK_QUEUE_FAMILY_IGNORED.adoc[] 6438-- 6439 6440ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6441Resources shared with external APIs or instances using external memory must: 6442also explicitly manage ownership transfers between local and external queues 6443(or equivalent constructs in external APIs) regardless of the 6444elink:VkSharingMode specified when creating them. 6445 6446[open,refpage='VK_QUEUE_FAMILY_EXTERNAL',desc='External queue family index sentinel',type='consts',alias='VK_QUEUE_FAMILY_EXTERNAL_KHR'] 6447-- 6448The special queue family index ename:VK_QUEUE_FAMILY_EXTERNAL represents any 6449queue external to the resource's current Vulkan instance, as long as the 6450queue uses the same underlying 6451ifdef::VK_VERSION_1_1,VK_KHR_device_group[device group or] 6452physical device, and the same driver version as the resource's 6453slink:VkDevice, as indicated by 6454slink:VkPhysicalDeviceIDProperties::pname:deviceUUID and 6455slink:VkPhysicalDeviceIDProperties::pname:driverUUID. 6456 6457include::{generated}/api/enums/VK_QUEUE_FAMILY_EXTERNAL.adoc[] 6458 6459ifdef::VK_KHR_external_memory[] 6460or the equivalent 6461 6462include::{generated}/api/enums/VK_QUEUE_FAMILY_EXTERNAL_KHR.adoc[] 6463endif::VK_KHR_external_memory[] 6464-- 6465 6466ifdef::VK_EXT_queue_family_foreign[] 6467[open,refpage='VK_QUEUE_FAMILY_FOREIGN_EXT',desc='Foreign queue family index sentinel',type='consts'] 6468-- 6469The special queue family index ename:VK_QUEUE_FAMILY_FOREIGN_EXT represents 6470any queue external to the resource's current Vulkan instance, regardless of 6471the queue's underlying physical device or driver version. 6472This includes, for example, queues for fixed-function image processing 6473devices, media codec devices, and display devices, as well as all queues 6474that use the same underlying 6475ifdef::VK_VERSION_1_1,VK_KHR_device_group[device group or] 6476physical device, and the same driver version as the resource's 6477slink:VkDevice. 6478 6479include::{generated}/api/enums/VK_QUEUE_FAMILY_FOREIGN_EXT.adoc[] 6480-- 6481endif::VK_EXT_queue_family_foreign[] 6482endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6483 6484If memory dependencies are correctly expressed between uses of such a 6485resource between two queues in different families, but no ownership transfer 6486is defined, the contents of that resource are undefined: for any read 6487accesses performed by the second queue family. 6488 6489[NOTE] 6490.Note 6491==== 6492If an application does not need the contents of a resource to remain valid 6493when transferring from one queue family to another, then the ownership 6494transfer should: be skipped. 6495==== 6496 6497ifdef::VK_EXT_queue_family_foreign[] 6498[NOTE] 6499.Note 6500==== 6501Applications should expect transfers to/from 6502ename:VK_QUEUE_FAMILY_FOREIGN_EXT to be more expensive than transfers 6503to/from ename:VK_QUEUE_FAMILY_EXTERNAL_KHR. 6504==== 6505endif::VK_EXT_queue_family_foreign[] 6506 6507A queue family ownership transfer consists of two distinct parts: 6508 6509 . Release exclusive ownership from the source queue family 6510 . Acquire exclusive ownership for the destination queue family 6511 6512An application must: ensure that these operations occur in the correct order 6513by defining an execution dependency between them, e.g. using a semaphore. 6514 6515[[synchronization-queue-transfers-release]] A _release operation_ is used to 6516release exclusive ownership of a range of a buffer or image subresource 6517range. 6518A release operation is defined by executing a 6519<<synchronization-buffer-memory-barriers, buffer memory barrier>> (for a 6520buffer range) or an <<synchronization-image-memory-barriers, image memory 6521barrier>> (for an image subresource range) using a pipeline barrier command, 6522on a queue from the source queue family. 6523The pname:srcQueueFamilyIndex parameter of the barrier must: be set to the 6524source queue family index, and the pname:dstQueueFamilyIndex parameter to 6525the destination queue family index. 6526pname:dstAccessMask is ignored for such a barrier, such that no visibility 6527operation is executed - the value of this mask does not affect the validity 6528of the barrier. 6529The release operation happens-after the availability operation, and 6530happens-before operations specified in the second synchronization scope of 6531the calling command. 6532 6533[[synchronization-queue-transfers-acquire]] An _acquire operation_ is used 6534to acquire exclusive ownership of a range of a buffer or image subresource 6535range. 6536An acquire operation is defined by executing a 6537<<synchronization-buffer-memory-barriers, buffer memory barrier>> (for a 6538buffer range) or an <<synchronization-image-memory-barriers, image memory 6539barrier>> (for an image subresource range) using a pipeline barrier command, 6540on a queue from the destination queue family. 6541The buffer range or image subresource range specified in an acquire 6542operation must: match exactly that of a previous release operation. 6543The pname:srcQueueFamilyIndex parameter of the barrier must: be set to the 6544source queue family index, and the pname:dstQueueFamilyIndex parameter to 6545the destination queue family index. 6546pname:srcAccessMask is ignored for such a barrier, such that no availability 6547operation is executed - the value of this mask does not affect the validity 6548of the barrier. 6549The acquire operation happens-after operations in the first synchronization 6550scope of the calling command, and happens-before the visibility operation. 6551 6552[NOTE] 6553.Note 6554==== 6555Whilst it is not invalid to provide destination or source access masks for 6556memory barriers used for release or acquire operations, respectively, they 6557have no practical effect. 6558Access after a release operation has undefined: results, and so visibility 6559for those accesses has no practical effect. 6560Similarly, write access before an acquire operation will produce undefined: 6561results for future access, so availability of those writes has no practical 6562use. 6563In an earlier version of the specification, these were required to match on 6564both sides - but this was subsequently relaxed. 6565These masks should: be set to 0. 6566==== 6567 6568If the transfer is via an image memory barrier, and an 6569<<synchronization-image-layout-transitions, image layout transition>> is 6570desired, then the values of pname:oldLayout and pname:newLayout in the 6571_release operation_'s memory barrier must: be equal to values of 6572pname:oldLayout and pname:newLayout in the _acquire operation_'s memory 6573barrier. 6574Although the image layout transition is submitted twice, it will only be 6575executed once. 6576A layout transition specified in this way happens-after the _release 6577operation_ and happens-before the _acquire operation_. 6578 6579If the values of pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex are 6580equal, no ownership transfer is performed, and the barrier operates as if 6581they were both set to ename:VK_QUEUE_FAMILY_IGNORED. 6582 6583Queue family ownership transfers may: perform read and write accesses on all 6584memory bound to the image subresource or buffer range, so applications must: 6585ensure that all memory writes have been made 6586<<synchronization-dependencies-available-and-visible, available>> before a 6587queue family ownership transfer is executed. 6588Available memory is automatically made visible to queue family release and 6589acquire operations, and writes performed by those operations are 6590automatically made available. 6591 6592Once a queue family has acquired ownership of a buffer range or image 6593subresource range of a ename:VK_SHARING_MODE_EXCLUSIVE resource, its 6594contents are undefined: to other queue families unless ownership is 6595transferred. 6596The contents of any portion of another resource which aliases memory that is 6597bound to the transferred buffer or image subresource range are undefined: 6598after a release or acquire operation. 6599 6600[NOTE] 6601.Note 6602==== 6603Because <<synchronization-events, events>> cannot: be used directly for 6604inter-queue synchronization, and because flink:vkCmdSetEvent does not have 6605the queue family index or memory barrier parameters needed by a _release 6606operation_, the release and acquire operations of a queue family ownership 6607transfer can: only be performed using flink:vkCmdPipelineBarrier. 6608==== 6609 6610 6611[[synchronization-wait-idle]] 6612== Wait Idle Operations 6613 6614[open,refpage='vkQueueWaitIdle',desc='Wait for a queue to become idle',type='protos'] 6615-- 6616To wait on the host for the completion of outstanding queue operations for a 6617given queue, call: 6618 6619include::{generated}/api/protos/vkQueueWaitIdle.adoc[] 6620 6621 * pname:queue is the queue on which to wait. 6622 6623fname:vkQueueWaitIdle is equivalent to having submitted a valid fence to 6624every previously executed <<devsandqueues-submission,queue submission 6625command>> that accepts a fence, then waiting for all of those fences to 6626signal using flink:vkWaitForFences with an infinite timeout and 6627pname:waitAll set to ename:VK_TRUE. 6628 6629include::{generated}/validity/protos/vkQueueWaitIdle.adoc[] 6630-- 6631 6632[open,refpage='vkDeviceWaitIdle',desc='Wait for a device to become idle',type='protos'] 6633-- 6634To wait on the host for the completion of outstanding queue operations for 6635all queues on a given logical device, call: 6636 6637include::{generated}/api/protos/vkDeviceWaitIdle.adoc[] 6638 6639 * pname:device is the logical device to idle. 6640 6641fname:vkDeviceWaitIdle is equivalent to calling fname:vkQueueWaitIdle for 6642all queues owned by pname:device. 6643 6644include::{generated}/validity/protos/vkDeviceWaitIdle.adoc[] 6645-- 6646 6647 6648[[synchronization-submission-host-writes]] 6649== Host Write Ordering Guarantees 6650 6651When batches of command buffers are submitted to a queue via a 6652<<devsandqueues-submission, queue submission command>>, it defines a memory 6653dependency with prior host operations, and execution of command buffers 6654submitted to the queue. 6655 6656The first <<synchronization-dependencies-scopes, synchronization scope>> is 6657defined by the host execution model, but includes execution of 6658flink:vkQueueSubmit on the host and anything that happened-before it. 6659 6660The second <<synchronization-dependencies-scopes, synchronization scope>> 6661includes all commands submitted in the same <<devsandqueues-submission, 6662queue submission>>, and all commands that occur later in 6663<<synchronization-submission-order,submission order>>. 6664 6665The first <<synchronization-dependencies-access-scopes, access scope>> 6666includes all host writes to mappable device memory that are available to the 6667host memory domain. 6668 6669The second <<synchronization-dependencies-access-scopes, access scope>> 6670includes all memory access performed by the device. 6671 6672 6673ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6674[[synchronization-device-group]] 6675== Synchronization and Multiple Physical Devices 6676 6677If a logical device includes more than one physical device, then fences, 6678semaphores, and events all still have a single instance of the signaled 6679state. 6680 6681A fence becomes signaled when all physical devices complete the necessary 6682queue operations. 6683 6684Semaphore wait and signal operations all include a device index that is the 6685sole physical device that performs the operation. 6686These indices are provided in the slink:VkDeviceGroupSubmitInfo and 6687slink:VkDeviceGroupBindSparseInfo structures. 6688Semaphores are not exclusively owned by any physical device. 6689For example, a semaphore can be signaled by one physical device and then 6690waited on by a different physical device. 6691 6692An event can: only be waited on by the same physical device that signaled it 6693(or the host). 6694endif::VK_VERSION_1_1,VK_KHR_device_group[] 6695 6696 6697ifdef::VK_EXT_calibrated_timestamps[] 6698[[calibrated-timestamps]] 6699== Calibrated timestamps 6700 6701[open,refpage='vkGetCalibratedTimestampsEXT',desc='Query calibrated timestamps',type='protos'] 6702-- 6703In order to be able to correlate the time a particular operation took place 6704at on timelines of different time domains (e.g. a device operation vs. a 6705host operation), Vulkan allows querying calibrated timestamps from multiple 6706time domains. 6707 6708To query calibrated timestamps from a set of time domains, call: 6709 6710include::{generated}/api/protos/vkGetCalibratedTimestampsEXT.adoc[] 6711 6712 * pname:device is the logical device used to perform the query. 6713 * pname:timestampCount is the number of timestamps to query. 6714 * pname:pTimestampInfos is a pointer to an array of pname:timestampCount 6715 slink:VkCalibratedTimestampInfoEXT structures, describing the time 6716 domains the calibrated timestamps should be captured from. 6717 * pname:pTimestamps is a pointer to an array of pname:timestampCount 6718 64-bit unsigned integer values in which the requested calibrated 6719 timestamp values are returned. 6720 * pname:pMaxDeviation is a pointer to a 64-bit unsigned integer value in 6721 which the strictly positive maximum deviation, in nanoseconds, of the 6722 calibrated timestamp values is returned. 6723 6724[NOTE] 6725.Note 6726==== 6727The maximum deviation may: vary between calls to 6728fname:vkGetCalibratedTimestampsEXT even for the same set of time domains due 6729to implementation and platform specific reasons. 6730It is the application's responsibility to assess whether the returned 6731maximum deviation makes the timestamp values suitable for any particular 6732purpose and can: choose to re-issue the timestamp calibration call pursuing 6733a lower deviation value. 6734==== 6735 6736Calibrated timestamp values can: be extrapolated to estimate future 6737coinciding timestamp values, however, depending on the nature of the time 6738domains and other properties of the platform extrapolating values over a 6739sufficiently long period of time may: no longer be accurate enough to fit 6740any particular purpose, so applications are expected to re-calibrate the 6741timestamps on a regular basis. 6742 6743include::{generated}/validity/protos/vkGetCalibratedTimestampsEXT.adoc[] 6744-- 6745 6746[open,refpage='VkCalibratedTimestampInfoEXT',desc='Structure specifying the input parameters of a calibrated timestamp query',type='structs'] 6747-- 6748The sname:VkCalibratedTimestampInfoEXT structure is defined as: 6749 6750include::{generated}/api/structs/VkCalibratedTimestampInfoEXT.adoc[] 6751 6752 * pname:sType is the type of this structure. 6753 * pname:pNext is `NULL` or a pointer to a structure extending this 6754 structure. 6755 * pname:timeDomain is a elink:VkTimeDomainEXT value specifying the time 6756 domain from which the calibrated timestamp value should be returned. 6757 6758.Valid Usage 6759**** 6760 * [[VUID-VkCalibratedTimestampInfoEXT-timeDomain-02354]] 6761 pname:timeDomain must: be one of the elink:VkTimeDomainEXT values 6762 returned by flink:vkGetPhysicalDeviceCalibrateableTimeDomainsEXT 6763**** 6764include::{generated}/validity/structs/VkCalibratedTimestampInfoEXT.adoc[] 6765-- 6766 6767[open,refpage='VkTimeDomainEXT',desc='Supported time domains',type='enums'] 6768-- 6769The set of supported time domains consists of: 6770 6771include::{generated}/api/enums/VkTimeDomainEXT.adoc[] 6772 6773 * ename:VK_TIME_DOMAIN_DEVICE_EXT specifies the device time domain. 6774 Timestamp values in this time domain use the same units and are 6775 comparable with device timestamp values captured using 6776 flink:vkCmdWriteTimestamp 6777ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 6778 or flink:vkCmdWriteTimestamp2 6779endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6780 and are defined to be incrementing according to the 6781 <<limits-timestampPeriod, pname:timestampPeriod>> of the device. 6782 6783 * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT specifies the CLOCK_MONOTONIC 6784 time domain available on POSIX platforms. 6785 Timestamp values in this time domain are in units of nanoseconds and are 6786 comparable with platform timestamp values captured using the POSIX 6787 clock_gettime API as computed by this example: 6788 6789[NOTE] 6790.Note 6791==== 6792An implementation supporting `apiext:VK_EXT_calibrated_timestamps` will use 6793the same time domain for all its slink:VkQueue so that timestamp values 6794reported for ename:VK_TIME_DOMAIN_DEVICE_EXT can be matched to any timestamp 6795captured through flink:vkCmdWriteTimestamp 6796ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 6797or flink:vkCmdWriteTimestamp2 6798endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 6799. 6800==== 6801 6802[source,c] 6803~~~~ 6804struct timespec tv; 6805clock_gettime(CLOCK_MONOTONIC, &tv); 6806return tv.tv_nsec + tv.tv_sec*1000000000ull; 6807~~~~ 6808 6809 * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT specifies the 6810 CLOCK_MONOTONIC_RAW time domain available on POSIX platforms. 6811 Timestamp values in this time domain are in units of nanoseconds and are 6812 comparable with platform timestamp values captured using the POSIX 6813 clock_gettime API as computed by this example: 6814 6815[source,c] 6816~~~~ 6817struct timespec tv; 6818clock_gettime(CLOCK_MONOTONIC_RAW, &tv); 6819return tv.tv_nsec + tv.tv_sec*1000000000ull; 6820~~~~ 6821 6822 * ename:VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT specifies the 6823 performance counter (QPC) time domain available on Windows. 6824 Timestamp values in this time domain are in the same units as those 6825 provided by the Windows QueryPerformanceCounter API and are comparable 6826 with platform timestamp values captured using that API as computed by 6827 this example: 6828 6829[source,c] 6830~~~~ 6831LARGE_INTEGER counter; 6832QueryPerformanceCounter(&counter); 6833return counter.QuadPart; 6834~~~~ 6835-- 6836endif::VK_EXT_calibrated_timestamps[] 6837