C Specification
To wait for one or more events to enter the signaled state on a device, call:
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 thepEvents
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 thepMemoryBarriers
array. -
pMemoryBarriers
is a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCount
is the length of thepBufferMemoryBarriers
array. -
pBufferMemoryBarriers
is a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCount
is the length of thepImageMemoryBarriers
array. -
pImageMemoryBarriers
is a pointer to an array of VkImageMemoryBarrier structures.
Description
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 access 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 access 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.
Note
vkCmdWaitEvents is used with vkCmdSetEvent 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. Unlike vkCmdPipelineBarrier, a queue family ownership transfer cannot be performed using vkCmdWaitEvents. |
Note
Applications should be careful to avoid race conditions when using events. There is no direct ordering guarantee between a vkCmdResetEvent command and a vkCmdWaitEvents command submitted after it, so some other execution dependency must be included between these commands (e.g. a semaphore). |
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
Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.