C Specification

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

// Provided by VK_VERSION_1_3
void vkCmdWaitEvents2(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    const VkDependencyInfo*                     pDependencyInfos);

or the equivalent command

// Provided by VK_KHR_synchronization2
void vkCmdWaitEvents2KHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    const VkDependencyInfo*                     pDependencyInfos);

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 eventCount events to wait on.

  • pDependencyInfos is a pointer to an array of eventCount VkDependencyInfo structures, defining the second synchronization scope.

Description

When vkCmdWaitEvents2 is submitted to a queue, it inserts memory dependencies according to the elements of pDependencyInfos and each corresponding element of pEvents. vkCmdWaitEvents2 must not be used to wait on event signal operations occurring on other queues, or signal operations executed by vkCmdSetEvent.

The first synchronization scope and access scope of each memory dependency defined by any element i of pDependencyInfos are applied to operations that occurred earlier in submission order than the last event signal operation on element i of pEvents.

Signal operations for an event at index i are only included if:

  • The event was signaled by a vkCmdSetEvent2 command that occurred earlier in submission order with a dependencyInfo parameter exactly equal to the element of pDependencyInfos at index i ; or

  • The event was created without VK_EVENT_CREATE_DEVICE_ONLY_BIT, and the first synchronization scope defined by the element of pDependencyInfos at index i only includes host operations (VK_PIPELINE_STAGE_2_HOST_BIT).

The second synchronization scope and access scope of each memory dependency defined by any element i of pDependencyInfos are applied to operations that occurred later in submission order than vkCmdWaitEvents2.

Note

vkCmdWaitEvents2 is used with vkCmdSetEvent2 to define a memory dependency between two sets of action commands, roughly in the same way as pipeline barriers, but split into two commands such that work between the two may execute unhindered.

Note

Applications should be careful to avoid race conditions when using events. There is no direct ordering guarantee between vkCmdSetEvent2 and vkCmdResetEvent2, vkCmdResetEvent, or vkCmdSetEvent. Another execution dependency (e.g. a pipeline barrier or semaphore with VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT) is needed to prevent such a race condition.

Valid Usage
  • VUID-vkCmdWaitEvents2-synchronization2-03836
    The synchronization2 feature must be enabled

  • VUID-vkCmdWaitEvents2-pEvents-03837
    Members of pEvents must not have been signaled by vkCmdSetEvent

  • VUID-vkCmdWaitEvents2-pEvents-03838
    For any element i of pEvents, if that event is signaled by vkCmdSetEvent2, that command’s dependencyInfo parameter must be exactly equal to the ith element of pDependencyInfos

  • VUID-vkCmdWaitEvents2-pEvents-03839
    For any element i of pEvents, if that event is signaled by vkSetEvent, barriers in the ith element of pDependencyInfos must include only host operations in their first synchronization scope

  • VUID-vkCmdWaitEvents2-pEvents-03840
    For any element i of pEvents, if barriers in the ith element of pDependencyInfos include only host operations, the ith element of pEvents must be signaled before vkCmdWaitEvents2 is executed

  • VUID-vkCmdWaitEvents2-pEvents-03841
    For any element i of pEvents, if barriers in the ith element of pDependencyInfos do not include host operations, the ith element of pEvents must be signaled by a corresponding vkCmdSetEvent2 that occurred earlier in submission order

  • VUID-vkCmdWaitEvents2-srcStageMask-03842
    The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must either include only pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWaitEvents2-dstStageMask-03843
    The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWaitEvents2-dependencyFlags-03844
    If vkCmdWaitEvents2 is being called inside a render pass instance, the srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfos must not include VK_PIPELINE_STAGE_2_HOST_BIT

  • VUID-vkCmdWaitEvents2-commandBuffer-03846
    commandBuffer’s current device mask must include exactly one physical device

Valid Usage (Implicit)
  • VUID-vkCmdWaitEvents2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

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

  • VUID-vkCmdWaitEvents2-pDependencyInfos-parameter
    pDependencyInfos must be a valid pointer to an array of eventCount valid VkDependencyInfo structures

  • VUID-vkCmdWaitEvents2-commandBuffer-recording
    commandBuffer must be in the recording state

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

  • VUID-vkCmdWaitEvents2-eventCount-arraylength
    eventCount must be greater than 0

  • VUID-vkCmdWaitEvents2-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

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 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0