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