C Specification

To signal an event from a device, call:

// Provided by VK_KHR_synchronization2
void vkCmdSetEvent2KHR(
    VkCommandBuffer                             commandBuffer,
    VkEvent                                     event,
    const VkDependencyInfoKHR*                  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 VkDependencyInfoKHR 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.

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-vkCmdSetEvent2KHR-synchronization2-03824
    The synchronization2 feature must be enabled

  • VUID-vkCmdSetEvent2KHR-dependencyFlags-03825
    The dependencyFlags member of dependencyInfo must be 0

  • VUID-vkCmdSetEvent2KHR-commandBuffer-03826
    The current device mask of commandBuffer must include exactly one physical device.

  • VUID-vkCmdSetEvent2KHR-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-vkCmdSetEvent2KHR-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-vkCmdSetEvent2KHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetEvent2KHR-event-parameter
    event must be a valid VkEvent handle

  • VUID-vkCmdSetEvent2KHR-pDependencyInfo-parameter
    pDependencyInfo must be a valid pointer to a valid VkDependencyInfoKHR structure

  • VUID-vkCmdSetEvent2KHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetEvent2KHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdSetEvent2KHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdSetEvent2KHR-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

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Graphics
Compute

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 2014-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0