• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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