vkCmdWaitEvents(3)

# vkCmdWaitEvents(3) Manual Page

## Name

vkCmdWaitEvents - Wait for one or more events and insert a set of memory

Loading… please wait.

## C Specification

To wait for one or more events to enter the signaled state on a device, call:

    // Provided by VK_VERSION_1_0
    void vkCmdWaitEvents(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    eventCount,
        const VkEvent*                              pEvents,
        VkPipelineStageFlags                        srcStageMask,
        VkPipelineStageFlags                        dstStageMask,
        uint32_t                                    memoryBarrierCount,
        const VkMemoryBarrier*                      pMemoryBarriers,
        uint32_t                                    bufferMemoryBarrierCount,
        const VkBufferMemoryBarrier*                pBufferMemoryBarriers,
        uint32_t                                    imageMemoryBarrierCount,
        const VkImageMemoryBarrier*                 pImageMemoryBarriers);

## Parameters

- `commandBuffer` is the command buffer into which the command is recorded.

- `eventCount` is the length of the `pEvents` array.

- `pEvents` is a pointer to an array of event object handles to wait on.

- `srcStageMask` is a bitmask of VkPipelineStageFlagBits specifying the source stage mask.

- `dstStageMask` is a bitmask of VkPipelineStageFlagBits specifying the destination stage mask.

- `memoryBarrierCount` is the length of the `pMemoryBarriers` array.

- `pMemoryBarriers` is a pointer to an array of VkMemoryBarrier structures.

- `bufferMemoryBarrierCount` is the length of the `pBufferMemoryBarriers` array.

- `pBufferMemoryBarriers` is a pointer to an array of VkBufferMemoryBarrier structures.

- `imageMemoryBarrierCount` is the length of the `pImageMemoryBarriers` array.

- `pImageMemoryBarriers` is a pointer to an array of VkImageMemoryBarrier structures.

## Description

`vkCmdWaitEvents` is largely similar to vkCmdWaitEvents2, but can only wait on signal operations defined by vkCmdSetEvent. As vkCmdSetEvent does not define any access scopes, `vkCmdWaitEvents` defines the first access scope for each event signal operation in addition to its own access scopes.

| Note Since vkCmdSetEvent does not have any dependency information beyond a stage mask, implementations do not have the same opportunity to perform availability and visibility operations or image layout transitions in advance as they do with vkCmdSetEvent2 and vkCmdWaitEvents2.

When `vkCmdWaitEvents` is submitted to a queue, it defines a memory dependency between prior event signal operations on the same queue or the host, and subsequent commands. `vkCmdWaitEvents` must not be used to wait on event signal operations occurring on other queues.

The first synchronization scope only includes event signal operations that operate on members of `pEvents`, and the operations that happened-before the event signal operations. Event signal operations performed by vkCmdSetEvent that occur earlier in submission order are included in the first synchronization scope, if the logically latest pipeline stage in their `stageMask` parameter is logically earlier than or equal to the logically latest pipeline stage in `srcStageMask`. Event signal operations performed by vkSetEvent are only included in the first synchronization scope if `VK_PIPELINE_STAGE_HOST_BIT` is included in `srcStageMask`.

The second synchronization scope includes all commands that occur later in submission order. The second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by `dstStageMask`.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by `srcStageMask`. Within that, the first access scope only includes the first access scopes defined by elements of the `pMemoryBarriers`, `pBufferMemoryBarriers` and `pImageMemoryBarriers` arrays, which each define a set of memory barriers. If no memory barriers are specified, then the first access scope includes no accesses.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by `dstStageMask`. Within that, the second access scope only includes the second access scopes defined by elements of the `pMemoryBarriers`, `pBufferMemoryBarriers` and `pImageMemoryBarriers` arrays, which each define a set of memory barriers. If no memory barriers are specified, then the second access scope includes no accesses.

Valid Usage

- VUID-vkCmdWaitEvents-srcStageMask-04090
  If the `geometryShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- VUID-vkCmdWaitEvents-srcStageMask-04091
  If the `tessellationShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT` or `VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT`

- VUID-vkCmdWaitEvents-srcStageMask-04092
  If the `conditionalRendering` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

- VUID-vkCmdWaitEvents-srcStageMask-04093
  If the `fragmentDensityMap` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

- VUID-vkCmdWaitEvents-srcStageMask-04094
  If the `transformFeedback` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT`

- VUID-vkCmdWaitEvents-srcStageMask-04095
  If the `meshShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT`

- VUID-vkCmdWaitEvents-srcStageMask-04096
  If the `taskShader` feature is not enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT`

- VUID-vkCmdWaitEvents-srcStageMask-07318
  If neither the `shadingRateImage` or `attachmentFragmentShadingRate` are enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

- VUID-vkCmdWaitEvents-srcStageMask-03937
  If the `synchronization2` feature is not enabled, `srcStageMask` must not be `0`

- VUID-vkCmdWaitEvents-rayTracingPipeline-07949
  If neither the VK_NV_ray_tracing extension or `rayTracingPipeline` feature are enabled, `srcStageMask` must not contain `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- VUID-vkCmdWaitEvents-dstStageMask-04090
  If the `geometryShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- VUID-vkCmdWaitEvents-dstStageMask-04091
  If the `tessellationShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT` or `VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT`

- VUID-vkCmdWaitEvents-dstStageMask-04092
  If the `conditionalRendering` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

- VUID-vkCmdWaitEvents-dstStageMask-04093
  If the `fragmentDensityMap` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

- VUID-vkCmdWaitEvents-dstStageMask-04094
  If the `transformFeedback` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT`

- VUID-vkCmdWaitEvents-dstStageMask-04095
  If the `meshShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT`

- VUID-vkCmdWaitEvents-dstStageMask-04096
  If the `taskShader` feature is not enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT`

- VUID-vkCmdWaitEvents-dstStageMask-07318
  If neither the `shadingRateImage` or `attachmentFragmentShadingRate` are enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

- VUID-vkCmdWaitEvents-dstStageMask-03937
  If the `synchronization2` feature is not enabled, `dstStageMask` must not be `0`

- VUID-vkCmdWaitEvents-rayTracingPipeline-07949
  If neither the VK_NV_ray_tracing extension or `rayTracingPipeline` feature are enabled, `dstStageMask` must not contain `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- VUID-vkCmdWaitEvents-srcAccessMask-02815
  The `srcAccessMask` member of each element of `pMemoryBarriers` must only include access flags that are supported by one or more of the pipeline stages in `srcStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-dstAccessMask-02816
  The `dstAccessMask` member of each element of `pMemoryBarriers` must only include access flags that are supported by one or more of the pipeline stages in `dstStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-pBufferMemoryBarriers-02817
  For any element of `pBufferMemoryBarriers`, if its `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members are equal, or if its `srcQueueFamilyIndex` is the queue family index that was used to create the command pool that `commandBuffer` was allocated from, then its `srcAccessMask` member must only contain access flags that are supported by one or more of the pipeline stages in `srcStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-pBufferMemoryBarriers-02818
  For any element of `pBufferMemoryBarriers`, if its `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members are equal, or if its `dstQueueFamilyIndex` is the queue family index that was used to create the command pool that `commandBuffer` was allocated from, then its `dstAccessMask` member must only contain access flags that are supported by one or more of the pipeline stages in `dstStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-pImageMemoryBarriers-02819
  For any element of `pImageMemoryBarriers`, if its `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members are equal, or if its `srcQueueFamilyIndex` is the queue family index that was used to create the command pool that `commandBuffer` was allocated from, then its `srcAccessMask` member must only contain access flags that are supported by one or more of the pipeline stages in `srcStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-pImageMemoryBarriers-02820
  For any element of `pImageMemoryBarriers`, if its `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members are equal, or if its `dstQueueFamilyIndex` is the queue family index that was used to create the command pool that `commandBuffer` was allocated from, then its `dstAccessMask` member must only contain access flags that are supported by one or more of the pipeline stages in `dstStageMask`, as specified in the table of supported access types

- VUID-vkCmdWaitEvents-srcStageMask-06459
  Any pipeline stage included in `srcStageMask` must be supported by the capabilities of the queue family specified by the `queueFamilyIndex` member of the VkCommandPoolCreateInfo structure that was used to create the `VkCommandPool` that `commandBuffer` was allocated from, as specified in the table of supported pipeline stages

- VUID-vkCmdWaitEvents-dstStageMask-06460
  Any pipeline stage included in `dstStageMask` must be supported by the capabilities of the queue family specified by the `queueFamilyIndex` member of the VkCommandPoolCreateInfo structure that was used to create the `VkCommandPool` that `commandBuffer` was allocated from, as specified in the table of supported pipeline stages

- VUID-vkCmdWaitEvents-srcStageMask-01158
  `srcStageMask` must be the bitwise OR of the `stageMask` parameter used in previous calls to `vkCmdSetEvent` with any of the elements of `pEvents` and `VK_PIPELINE_STAGE_HOST_BIT` if any of the elements of `pEvents` was set using `vkSetEvent`

- VUID-vkCmdWaitEvents-srcStageMask-07308
  If `vkCmdWaitEvents` is being called inside a render pass instance, `srcStageMask` must not include `VK_PIPELINE_STAGE_HOST_BIT`

- VUID-vkCmdWaitEvents-srcQueueFamilyIndex-02803
  The `srcQueueFamilyIndex` and `dstQueueFamilyIndex` members of any element of `pBufferMemoryBarriers` or `pImageMemoryBarriers` must be equal

- VUID-vkCmdWaitEvents-commandBuffer-01167
  `commandBuffer`’s current device mask must include exactly one physical device

- VUID-vkCmdWaitEvents-pEvents-03847
  Elements of `pEvents` must not have been signaled by vkCmdSetEvent2

Valid Usage (Implicit)

- VUID-vkCmdWaitEvents-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdWaitEvents-pEvents-parameter
  `pEvents` must be a valid pointer to an array of `eventCount` valid VkEvent handles

- VUID-vkCmdWaitEvents-srcStageMask-parameter
  `srcStageMask` must be a valid combination of VkPipelineStageFlagBits values

- VUID-vkCmdWaitEvents-dstStageMask-parameter
  `dstStageMask` must be a valid combination of VkPipelineStageFlagBits values

- VUID-vkCmdWaitEvents-pMemoryBarriers-parameter
  If `memoryBarrierCount` is not `0`, `pMemoryBarriers` must be a valid pointer to an array of `memoryBarrierCount` valid VkMemoryBarrier structures

- VUID-vkCmdWaitEvents-pBufferMemoryBarriers-parameter
  If `bufferMemoryBarrierCount` is not `0`, `pBufferMemoryBarriers` must be a valid pointer to an array of `bufferMemoryBarrierCount` valid VkBufferMemoryBarrier structures

- VUID-vkCmdWaitEvents-pImageMemoryBarriers-parameter
  If `imageMemoryBarrierCount` is not `0`, `pImageMemoryBarriers` must be a valid pointer to an array of `imageMemoryBarrierCount` valid VkImageMemoryBarrier structures

- VUID-vkCmdWaitEvents-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdWaitEvents-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support graphics, compute, decode, or encode operations

- VUID-vkCmdWaitEvents-eventCount-arraylength
  `eventCount` must be greater than `0`

- VUID-vkCmdWaitEvents-commonparent
  Both of `commandBuffer`, and the elements of `pEvents` must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Both | Both | Graphics Compute Decode Encode | Synchronization

## See Also

VK_VERSION_1_0, VkBufferMemoryBarrier, VkCommandBuffer, VkEvent, VkImageMemoryBarrier, VkMemoryBarrier, VkPipelineStageFlags

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0