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 vkCmdWaitEvents2KHR, 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 vkCmdSetEvent2KHR and vkCmdWaitEvents2KHR.

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-07319
    If the attachmentFragmentShadingRate feature is not 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-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-07319
    If the attachmentFragmentShadingRate feature is not 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-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 vkCmdSetEvent2KHR

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, or compute 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 Supported Queue Types Command Type

Primary
Secondary

Both

Graphics
Compute

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