VKCMDWAITEVENTS(3)

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

C SPECIFICATION

    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
    The command buffer in which to wait.

eventCount
    Number of event objects to wait on.

pEvents
    Array of eventCount number of event objects to wait on.

srcStageMask
    Mask of pipeline stages used to signal all of the events in pEvents.

dstStageMask
    Specifies which pipeline stages must wait for the events to become signaled (see VkPipelineStageFlags for more detail).

memoryBarrierCount
    Number of memory barriers to insert after waiting for the events.

ppMemoryBarriers
    Array of pointers to memory barrier structures specifying the parameters of the memory barriers to insert after waiting for the events. Each element of the array may point to a VkMemoryBarrier, VkBufferMemoryBarrier, or VkImageMemoryBarrier structure.

DESCRIPTION

vkCmdWaitEvents waits for a number of event objects to become signaled and inserts a set of memory barriers into the command buffer specified by commandBuffer.

vkCmdWaitEvents waits for each of the eventCount event object specified by pEvents to become signaled. The point at which each is signaled must have been specified in the command that caused the object to become signaled (either vkSetEvent or vkCmdSetEvent) and must also have the corresponding bit set in srcStageMask.

The ppMemoryBarriers parameter is a pointer to an array of memoryBarrierCount structures defining the parameters of memory barriers to insert after waiting for each of the events. Each element of the array may be an instance of VkMemoryBarrier, VkBufferMemoryBarrier, or VkImageMemoryBarrier, the definitions of each are, respectively:

    typedef struct VkMemoryBarrier {
        VkStructureType    sType;
        const void*        pNext;
        VkAccessFlags      srcAccessMask;
        VkAccessFlags      dstAccessMask;
    } VkMemoryBarrier;

    typedef struct VkBufferMemoryBarrier {
        VkStructureType    sType;
        const void*        pNext;
        VkAccessFlags      srcAccessMask;
        VkAccessFlags      dstAccessMask;
        uint32_t           srcQueueFamilyIndex;
        uint32_t           dstQueueFamilyIndex;
        VkBuffer           buffer;
        VkDeviceSize       offset;
        VkDeviceSize       size;
    } VkBufferMemoryBarrier;

    typedef struct VkImageMemoryBarrier {
        VkStructureType            sType;
        const void*                pNext;
        VkAccessFlags              srcAccessMask;
        VkAccessFlags              dstAccessMask;
        VkImageLayout              oldLayout;
        VkImageLayout              newLayout;
        uint32_t                   srcQueueFamilyIndex;
        uint32_t                   dstQueueFamilyIndex;
        VkImage                    image;
        VkImageSubresourceRange    subresourceRange;
    } VkImageMemoryBarrier;

The memory barriers specified by ppMemoryBarriers cause writes as described by outputMask that were written by pipeline stages in srcStageMask prior to the wait to be made visible to reads as described by inputMask in pipeline stages in dstStageMask subsequent to the wait.

In case of global memory barriers inserted by passing an VkMemoryBarrier structure to the command prior writes in the requested pipeline stages to any memory location corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of any memory location corresponding to the set of memory input coherency flags specified in the inputMask member of the structure.

In case of buffer memory barriers inserted by passing an VkBufferMemoryBarrier structure to the command prior writes in the requested pipeline stages to the specified sub-range of the buffer corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of the specified sub-range of the buffer corresponding to the set of memory input coherency flags specified in the inputMask member of the structure.

In case of image memory barriers inserted by passing an VkImageMemoryBarrier structure to the command prior writes in the requested pipeline stages to the specified sub-range of the image corresponding to the set of memory output coherency flags specified in the outputMask member of the structure are made coherent with subsequent reads in the requested pipeline stages of the specified sub-range of the image corresponding to the set of memory input coherency flags specified in the inputMask member of the structure. Additionally, if the oldLayout and newLayout members of the structure don’t match a layout transition is performed on the specified sub-range of the image as part of the memory barrier.

In case of buffer and image memory barriers the srcQueueFamilyIndex and dstQueueFamilyIndex members of the corresponding memory barrier structures can specify the parameters of a transfer of ownership between two distinct families of queues of a shared buffer or image object created with the VK_SHARING_MODE_EXCLUSIVE sharing mode. In case of regular resource transitions both srcQueueFamilyIndex and dstQueueFamilyIndex should be set to VK_QUEUE_FAMILY_IGNORED to indicate no transfer of ownership between queue families. In case of resource transitions involving ownership transfer of shared buffers or images one of these two members have to match the queue family index the command buffer specified by commandBuffer was created for, while the other should specify the queue family index the ownership transfer is released to or acquired from. Ownership transferring resource transitions have to be performed both on a queue from the source queue family and on a queue from the destination queue family (see VkSharingMode for more detail).

If inputMask is zero in any of the memory barrier structures then prior writes will only be coherent with any type of subsequent read after a future resource transition command specifies a non-empty set of memory input coherency control flags. This allows flushing device output caches unconditionally.

If outputMask is zero in any of the memory barrier structures then subsequent reads will only be coherent with any type of prior write if an earlier resource transition command specified a non-empty set of memory output coherency control flags. This allows invalidating device input caches unconditionally.

VALID USAGE

    • 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

    • Each of commandBuffer and the elements of pEvents must have been created, allocated or retrieved from the same VkDevice

    • 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

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Both | GRAPHICS COMPUTE

SEE ALSO

vkCmdSetEvent, vkCmdResetEvent, vkSetEvent, vkResetEvent, vkCmdPipelineBarrier, VkMemoryBarrier, VkBufferMemoryBarrier, VkImageMemoryBarrier, VkPipelineStageFlagBits

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.