vkCmdSetEvent2(3)

C Specification

To signal an event from a device, call:

// Provided by VK_KHR_synchronization2
void vkCmdSetEvent2KHR(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    const VkDependencyInfo*                     pDependencyInfo);

Parameters

commandBuffer is the command buffer into which the command is recorded.
event is the event that will be signaled.
pDependencyInfo is a pointer to a VkDependencyInfo structure defining the first scopes of this operation.

Description

When vkCmdSetEvent2KHR is submitted to a queue, it defines the first half of memory dependencies defined by pDependencyInfo, as well as an event signal operation which sets the event to the signaled state. A memory dependency is defined between the event signal operation and commands that occur earlier in submission order.

The first synchronization scope and access scope are defined by the union of all the memory dependencies defined by pDependencyInfo, and are applied to all operations that occur earlier in submission order. Queue family ownership transfers and image layout transitions defined by pDependencyInfo are also included in the first scopes.

The second synchronization scope includes only the event signal operation, and any queue family ownership transfers and image layout transitions defined by pDependencyInfo.

The second access scope includes only queue family ownership transfers and image layout transitions.

Future vkCmdWaitEvents2KHR commands rely on all values of each element in pDependencyInfo matching exactly with those used to signal the corresponding event. vkCmdWaitEvents must not be used to wait on the result of a signal operation defined by vkCmdSetEvent2KHR.

Note

The extra information provided by vkCmdSetEvent2KHR compared to vkCmdSetEvent allows implementations to more efficiently schedule the operations required to satisfy the requested dependencies. With vkCmdSetEvent, the full dependency information is not known until vkCmdWaitEvents is recorded, forcing implementations to insert the required operations at that point and not before.

If event is already in the signaled state when vkCmdSetEvent2KHR is executed on the device, then vkCmdSetEvent2KHR has no effect, no event signal operation occurs, and no dependency is generated.

Valid Usage

VUID-vkCmdSetEvent2-synchronization2-03824
The synchronization2 feature must be enabled
VUID-vkCmdSetEvent2-dependencyFlags-03825
The dependencyFlags member of pDependencyInfo must be 0
VUID-vkCmdSetEvent2-srcStageMask-09391
The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must not include VK_PIPELINE_STAGE_2_HOST_BIT
VUID-vkCmdSetEvent2-dstStageMask-09392
The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must not include VK_PIPELINE_STAGE_2_HOST_BIT
VUID-vkCmdSetEvent2-commandBuffer-03826
The current device mask of commandBuffer must include exactly one physical device
VUID-vkCmdSetEvent2-srcStageMask-03827
The srcStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from
VUID-vkCmdSetEvent2-dstStageMask-03828
The dstStageMask member of any element of the pMemoryBarriers, pBufferMemoryBarriers, or pImageMemoryBarriers members of pDependencyInfo must only include pipeline stages valid for the queue family that was used to create the command pool that commandBuffer was allocated from

Valid Usage (Implicit)

VUID-vkCmdSetEvent2-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdSetEvent2-event-parameter
event must be a valid VkEvent handle
VUID-vkCmdSetEvent2-pDependencyInfo-parameter
pDependencyInfo must be a valid pointer to a valid VkDependencyInfo structure
VUID-vkCmdSetEvent2-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdSetEvent2-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations
VUID-vkCmdSetEvent2-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdSetEvent2-commonparent
Both of commandBuffer, and event 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