VKCMDWAITEVENTS(3)

NAME
vkCmdWaitEvents - Wait for one or more events and insert a set of memory

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 the pEvents array.

    • pEvents is an array of event object handles to wait on.

    • srcStageMask (see ???) is the bitwise OR of the pipeline stages used to signal the event object handles in pEvents.

    • dstStageMask is the pipeline stages at which the wait will occur.

    • pMemoryBarriers is a pointer to an array of memoryBarrierCount VkMemoryBarrier structures.

    • pBufferMemoryBarriers is a pointer to an array of bufferMemoryBarrierCount VkBufferMemoryBarrier structures.

    • pImageMemoryBarriers is a pointer to an array of imageMemoryBarrierCount VkImageMemoryBarrier structures. See ??? for more details about memory barriers.

DESCRIPTION

vkCmdWaitEvents waits for events set by either vkSetEvent or vkCmdSetEvent to become signaled. Logically, it has three phases:

    1. Wait at the pipeline stages specified by dstStageMask (see ???) until the eventCount event objects specified by pEvents become signaled. Implementations may wait for each event object to become signaled in sequence (starting with the first event object in pEvents, and ending with the last), or wait for all of the event objects to become signaled at the same time.

    2. Execute the memory barriers specified by pMemoryBarriers, pBufferMemoryBarriers and pImageMemoryBarriers (see ???).

    3. Resume execution of pipeline stages specified by dstStageMask

Implementations may not execute commands in a pipelined manner, so vkCmdWaitEvents may not observe the results of a subsequent vkCmdSetEvent or vkCmdResetEvent command, even if the stages in dstStageMask occur after the stages in srcStageMask.

Commands that update the state of events in different pipeline stages may execute out of order, unless the ordering is enforced by execution dependencies.

    Note

    Applications should be careful to avoid race conditions when using events. For example, an event should only be reset if no vkCmdWaitEvents command is executing that waits upon that event.

Valid Usage

    • srcStageMask must be the bitwise OR of the stageMask parameter used in previous calls to vkCmdSetEvent with any of the members of pEvents and VK_PIPELINE_STAGE_HOST_BIT if any of the members of pEvents was set using vkSetEvent

    • If the geometry shaders feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

    • If the geometry shaders feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

    • If the tessellation shaders feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

    • If the tessellation shaders feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

    • If pEvents includes one or more events that will be signaled by vkSetEvent after commandBuffer has been submitted to a queue, then vkCmdWaitEvents must not be called inside a render pass instance
Valid Usage (Implicit)

    • commandBuffer must be a valid VkCommandBuffer handle

    • pEvents must be a pointer to an array of eventCount valid VkEvent handles

    • srcStageMask must be a valid combination of VkPipelineStageFlagBits values

    • srcStageMask must not be 0

    • dstStageMask must be a valid combination of VkPipelineStageFlagBits values

    • dstStageMask must not be 0

    • If memoryBarrierCount is not 0, pMemoryBarriers must be a pointer to an array of memoryBarrierCount valid VkMemoryBarrier structures

    • If bufferMemoryBarrierCount is not 0, pBufferMemoryBarriers must be a pointer to an array of bufferMemoryBarrierCount valid VkBufferMemoryBarrier structures

    • If imageMemoryBarrierCount is not 0, pImageMemoryBarriers must be a pointer to an array of imageMemoryBarrierCount valid VkImageMemoryBarrier structures

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

    • eventCount must be greater than 0

    • 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

VkBufferMemoryBarrier, VkCommandBuffer, VkEvent, VkImageMemoryBarrier, VkMemoryBarrier, VkPipelineStageFlags

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdWaitEvents

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.