VulkanHub
Function Prototype

vkCmdWaitEvents2

Wait for one or more events

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

void vkCmdWaitEvents2KHR(
    VkCommandBuffer                   commandBuffer,
    uint32_t                                            eventCount,
    const VkEvent*                     pEvents,
    const VkDependencyInfo*            pDependencyInfos);
  • 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.

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.

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.

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 only include 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 ::