C Specification

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

// Provided by VK_KHR_synchronization2
void vkCmdWaitEvents2KHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    eventCount,
    const VkEvent*                              pEvents,
    const VkDependencyInfoKHR*                  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 VkDependencyInfoKHR structures, defining the second synchronization scope.

Description

When vkCmdWaitEvents2KHR is submitted to a queue, it inserts memory dependencies according to the elements of pDependencyInfos and each corresponding element of pEvents. vkCmdWaitEvents2KHR must not be used to wait on event signal operations occurring on other queues, or signal operations execyted 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 vkCmdSetEvent2KHR 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_KHR, and the first synchronization scope defined by the element of pDependencyInfos at index i only includes host operations (VK_PIPELINE_STAGE_2_HOST_BIT_KHR).

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 vkCmdWaitEvents2KHR.

Note

vkCmdWaitEvents2KHR is used with vkCmdSetEvent2KHR 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 vkCmdSetEvent2KHR and vkCmdResetEvent2KHR, vkCmdResetEvent, or vkCmdSetEvent. Another execution dependency (e.g. a pipeline barrier or semaphore with VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT_KHR) is needed to prevent such a race condition.

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

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

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

  • VUID-vkCmdWaitEvents2KHR-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-vkCmdWaitEvents2KHR-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 vkCmdWaitEvents2KHR is executed

  • VUID-vkCmdWaitEvents2KHR-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 vkCmdSetEvent2KHR that occurred earlier in submission order

  • VUID-vkCmdWaitEvents2KHR-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, or include only VK_PIPELINE_STAGE_2_HOST_BIT_KHR

  • VUID-vkCmdWaitEvents2KHR-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-vkCmdWaitEvents2KHR-dependencyFlags-03844
    The dependencyFlags member of any element of pDependencyInfo must be 0

  • VUID-vkCmdWaitEvents2KHR-pEvents-03845
    If pEvents includes one or more events that will be signaled by vkSetEvent after commandBuffer has been submitted to a queue, then vkCmdWaitEvents2KHR must not be called inside a render pass instance

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

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

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

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

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

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

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

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

Primary
Secondary

Both

Graphics
Compute

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

SPDX-License-Identifier: CC-BY-4.0