Vulkan Logo

6. Command Buffers

Command buffers are objects used to record commands which can be subsequently submitted to a device queue for execution. There are two levels of command buffers - primary command buffers, which can execute secondary command buffers, and which are submitted to queues, and secondary command buffers, which can be executed by primary command buffers, and which are not directly submitted to queues.

Command buffers are represented by VkCommandBuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkCommandBuffer)

Recorded commands include commands to bind pipelines and descriptor sets to the command buffer, commands to modify dynamic state, commands to draw (for graphics rendering), commands to dispatch (for compute), commands to execute secondary command buffers (for primary command buffers only), commands to copy buffers and images, and other commands.

Each command buffer manages state independently of other command buffers. There is no inheritance of state across primary and secondary command buffers, or between secondary command buffers. When a command buffer begins recording, all state in that command buffer is undefined. When secondary command buffer(s) are recorded to execute on a primary command buffer, the secondary command buffer inherits no state from the primary command buffer, and all state of the primary command buffer is undefined after an execute secondary command buffer command is recorded. There is one exception to this rule - if the primary command buffer is inside a render pass instance, then the render pass and subpass state is not disturbed by executing secondary command buffers. For state dependent commands (such as draws and dispatches), any state consumed by those commands must not be undefined.

VkCommandBufferInheritanceViewportScissorInfoNV defines an exception allowing limited inheritance of dynamic viewport and scissor state.

Unless otherwise specified, and without explicit synchronization, the various commands submitted to a queue via command buffers may execute in arbitrary order relative to each other, and/or concurrently. Also, the memory side effects of those commands may not be directly visible to other commands without explicit memory dependencies. This is true within a command buffer, and across command buffers submitted to a given queue. See the synchronization chapter for information on implicit and explicit synchronization between commands.

6.1. Command Buffer Lifecycle

Each command buffer is always in one of the following states:

Initial

When a command buffer is allocated, it is in the initial state. Some commands are able to reset a command buffer (or a set of command buffers) back to this state from any of the executable, recording or invalid state. Command buffers in the initial state can only be moved to the recording state, or freed.

Recording

vkBeginCommandBuffer changes the state of a command buffer from the initial state to the recording state. Once a command buffer is in the recording state, vkCmd* commands can be used to record to the command buffer.

Executable

vkEndCommandBuffer ends the recording of a command buffer, and moves it from the recording state to the executable state. Executable command buffers can be submitted, reset, or recorded to another command buffer.

Pending

Queue submission of a command buffer changes the state of a command buffer from the executable state to the pending state. Whilst in the pending state, applications must not attempt to modify the command buffer in any way - as the device may be processing the commands recorded to it. Once execution of a command buffer completes, the command buffer either reverts back to the executable state, or if it was recorded with VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, it moves to the invalid state. A synchronization command should be used to detect when this occurs.

Invalid

Some operations, such as modifying or deleting a resource that was used in a command recorded to a command buffer, will transition the state of that command buffer into the invalid state. Command buffers in the invalid state can only be reset or freed.

image/svg+xml Initial Recording Pending Executable Invalid Allocate Begin End Submission Completion Completion withOne Time Submit Reset Reset Invalidate
Figure 1. Lifecycle of a command buffer

Any given command that operates on a command buffer has its own requirements on what state a command buffer must be in, which are detailed in the valid usage constraints for that command.

Resetting a command buffer is an operation that discards any previously recorded commands and puts a command buffer in the initial state. Resetting occurs as a result of vkResetCommandBuffer or vkResetCommandPool, or as part of vkBeginCommandBuffer (which additionally puts the command buffer in the recording state).

Secondary command buffers can be recorded to a primary command buffer via vkCmdExecuteCommands. This partially ties the lifecycle of the two command buffers together - if the primary is submitted to a queue, both the primary and any secondaries recorded to it move to the pending state. Once execution of the primary completes, so it does for any secondary recorded within it. After all executions of each command buffer complete, they each move to their appropriate completion state (either to the executable state or the invalid state, as specified above).

If a secondary moves to the invalid state or the initial state, then all primary buffers it is recorded in move to the invalid state. A primary moving to any other state does not affect the state of a secondary recorded in it.

Note

Resetting or freeing a primary command buffer removes the lifecycle linkage to all secondary command buffers that were recorded into it.

6.2. Command Pools

Command pools are opaque objects that command buffer memory is allocated from, and which allow the implementation to amortize the cost of resource creation across multiple command buffers. Command pools are externally synchronized, meaning that a command pool must not be used concurrently in multiple threads. That includes use via recording commands on any command buffers allocated from the pool, as well as operations that allocate, free, and reset command buffers or the pool itself.

Command pools are represented by VkCommandPool handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)

To create a command pool, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateCommandPool(
    VkDevice                                    device,
    const VkCommandPoolCreateInfo*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkCommandPool*                              pCommandPool);
  • device is the logical device that creates the command pool.

  • pCreateInfo is a pointer to a VkCommandPoolCreateInfo structure specifying the state of the command pool object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pCommandPool is a pointer to a VkCommandPool handle in which the created pool is returned.

Valid Usage
  • VUID-vkCreateCommandPool-queueFamilyIndex-01937
    pCreateInfo->queueFamilyIndex must be the index of a queue family available in the logical device device

Valid Usage (Implicit)
  • VUID-vkCreateCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateCommandPool-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkCommandPoolCreateInfo structure

  • VUID-vkCreateCommandPool-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateCommandPool-pCommandPool-parameter
    pCommandPool must be a valid pointer to a VkCommandPool handle

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandPoolCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandPoolCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkCommandPoolCreateFlags    flags;
    uint32_t                    queueFamilyIndex;
} VkCommandPoolCreateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it.

  • queueFamilyIndex designates a queue family as described in section Queue Family Properties. All command buffers allocated from this command pool must be submitted on queues from the same queue family.

Valid Usage
  • VUID-VkCommandPoolCreateInfo-flags-02860
    If the protectedMemory feature is not enabled, the VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of flags must not be set

Valid Usage (Implicit)
  • VUID-VkCommandPoolCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO

  • VUID-VkCommandPoolCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkCommandPoolCreateInfo-flags-parameter
    flags must be a valid combination of VkCommandPoolCreateFlagBits values

Bits which can be set in VkCommandPoolCreateInfo::flags, specifying usage behavior for a command pool, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolCreateFlagBits {
    VK_COMMAND_POOL_CREATE_TRANSIENT_BIT = 0x00000001,
    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT = 0x00000002,
  // Provided by VK_VERSION_1_1
    VK_COMMAND_POOL_CREATE_PROTECTED_BIT = 0x00000004,
} VkCommandPoolCreateFlagBits;
  • VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command buffers allocated from the pool will be short-lived, meaning that they will be reset or freed in a relatively short timeframe. This flag may be used by the implementation to control memory allocation behavior within the pool.

  • VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command buffer allocated from a pool to be individually reset to the initial state; either by calling vkResetCommandBuffer, or via the implicit reset when calling vkBeginCommandBuffer. If this flag is not set on a pool, then vkResetCommandBuffer must not be called for any command buffer allocated from that pool.

  • VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command buffers allocated from the pool are protected command buffers.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolCreateFlags;

VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero or more VkCommandPoolCreateFlagBits.

To trim a command pool, call:

// Provided by VK_VERSION_1_1
void vkTrimCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolTrimFlags                      flags);

or the equivalent command

// Provided by VK_KHR_maintenance1
void vkTrimCommandPoolKHR(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolTrimFlags                      flags);
  • device is the logical device that owns the command pool.

  • commandPool is the command pool to trim.

  • flags is reserved for future use.

Trimming a command pool recycles unused memory from the command pool back to the system. Command buffers allocated from the pool are not affected by the command.

Note

This command provides applications with some control over the internal memory allocations used by command pools.

Unused memory normally arises from command buffers that have been recorded and later reset, such that they are no longer using the memory. On reset, a command buffer can return memory to its command pool, but the only way to release memory from a command pool to the system requires calling vkResetCommandPool, which cannot be executed while any command buffers from that pool are still in use. Subsequent recording operations into command buffers will reuse this memory but since total memory requirements fluctuate over time, unused memory can accumulate.

In this situation, trimming a command pool may be useful to return unused memory back to the system, returning the total outstanding memory allocated by the pool back to a more “average” value.

Implementations utilize many internal allocation strategies that make it impossible to guarantee that all unused memory is released back to the system. For instance, an implementation of a command pool may involve allocating memory in bulk from the system and sub-allocating from that memory. In such an implementation any live command buffer that holds a reference to a bulk allocation would prevent that allocation from being freed, even if only a small proportion of the bulk allocation is in use.

In most cases trimming will result in a reduction in allocated but unused memory, but it does not guarantee the “ideal” behavior.

Trimming may be an expensive operation, and should not be called frequently. Trimming should be treated as a way to relieve memory pressure after application-known points when there exists enough unused memory that the cost of trimming is “worth” it.

Valid Usage (Implicit)
  • VUID-vkTrimCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkTrimCommandPool-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkTrimCommandPool-flags-zerobitmask
    flags must be 0

  • VUID-vkTrimCommandPool-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to commandPool must be externally synchronized

// Provided by VK_VERSION_1_1
typedef VkFlags VkCommandPoolTrimFlags;

or the equivalent

// Provided by VK_KHR_maintenance1
typedef VkCommandPoolTrimFlags VkCommandPoolTrimFlagsKHR;

VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is currently reserved for future use.

To reset a command pool, call:

// Provided by VK_VERSION_1_0
VkResult vkResetCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    VkCommandPoolResetFlags                     flags);
  • device is the logical device that owns the command pool.

  • commandPool is the command pool to reset.

  • flags is a bitmask of VkCommandPoolResetFlagBits controlling the reset operation.

Resetting a command pool recycles all of the resources from all of the command buffers allocated from the command pool back to the command pool. All command buffers that have been allocated from the command pool are put in the initial state.

Any primary command buffer allocated from another VkCommandPool that is in the recording or executable state and has a secondary command buffer allocated from commandPool recorded into it, becomes invalid.

Valid Usage
  • VUID-vkResetCommandPool-commandPool-00040
    All VkCommandBuffer objects allocated from commandPool must not be in the pending state

Valid Usage (Implicit)
  • VUID-vkResetCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkResetCommandPool-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkResetCommandPool-flags-parameter
    flags must be a valid combination of VkCommandPoolResetFlagBits values

  • VUID-vkResetCommandPool-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to commandPool must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Bits which can be set in vkResetCommandPool::flags, controlling the reset operation, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolResetFlagBits {
    VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandPoolResetFlagBits;
  • VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT specifies that resetting a command pool recycles all of the resources from the command pool back to the system.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolResetFlags;

VkCommandPoolResetFlags is a bitmask type for setting a mask of zero or more VkCommandPoolResetFlagBits.

To destroy a command pool, call:

// Provided by VK_VERSION_1_0
void vkDestroyCommandPool(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the command pool.

  • commandPool is the handle of the command pool to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

When a pool is destroyed, all command buffers allocated from the pool are freed.

Any primary command buffer allocated from another VkCommandPool that is in the recording or executable state and has a secondary command buffer allocated from commandPool recorded into it, becomes invalid.

Valid Usage
  • VUID-vkDestroyCommandPool-commandPool-00041
    All VkCommandBuffer objects allocated from commandPool must not be in the pending state

  • VUID-vkDestroyCommandPool-commandPool-00042
    If VkAllocationCallbacks were provided when commandPool was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyCommandPool-commandPool-00043
    If no VkAllocationCallbacks were provided when commandPool was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroyCommandPool-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyCommandPool-commandPool-parameter
    If commandPool is not VK_NULL_HANDLE, commandPool must be a valid VkCommandPool handle

  • VUID-vkDestroyCommandPool-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyCommandPool-commandPool-parent
    If commandPool is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to commandPool must be externally synchronized

6.3. Command Buffer Allocation and Management

To allocate command buffers, call:

// Provided by VK_VERSION_1_0
VkResult vkAllocateCommandBuffers(
    VkDevice                                    device,
    const VkCommandBufferAllocateInfo*          pAllocateInfo,
    VkCommandBuffer*                            pCommandBuffers);
  • device is the logical device that owns the command pool.

  • pAllocateInfo is a pointer to a VkCommandBufferAllocateInfo structure describing parameters of the allocation.

  • pCommandBuffers is a pointer to an array of VkCommandBuffer handles in which the resulting command buffer objects are returned. The array must be at least the length specified by the commandBufferCount member of pAllocateInfo. Each allocated command buffer begins in the initial state.

vkAllocateCommandBuffers can be used to allocate multiple command buffers. If the allocation of any of those command buffers fails, the implementation must free all successfully allocated command buffer objects from this command, set all entries of the pCommandBuffers array to NULL and return the error.

Note

Filling pCommandBuffers with NULL values on failure is an exception to the default error behavior that output parameters will have undefined contents.

When command buffers are first allocated, they are in the initial state.

Valid Usage (Implicit)
  • VUID-vkAllocateCommandBuffers-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkAllocateCommandBuffers-pAllocateInfo-parameter
    pAllocateInfo must be a valid pointer to a valid VkCommandBufferAllocateInfo structure

  • VUID-vkAllocateCommandBuffers-pCommandBuffers-parameter
    pCommandBuffers must be a valid pointer to an array of pAllocateInfo->commandBufferCount VkCommandBuffer handles

  • VUID-vkAllocateCommandBuffers-pAllocateInfo::commandBufferCount-arraylength
    pAllocateInfo->commandBufferCount must be greater than 0

Host Synchronization
  • Host access to pAllocateInfo->commandPool must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandBufferAllocateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferAllocateInfo {
    VkStructureType         sType;
    const void*             pNext;
    VkCommandPool           commandPool;
    VkCommandBufferLevel    level;
    uint32_t                commandBufferCount;
} VkCommandBufferAllocateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • commandPool is the command pool from which the command buffers are allocated.

  • level is a VkCommandBufferLevel value specifying the command buffer level.

  • commandBufferCount is the number of command buffers to allocate from the pool.

Valid Usage (Implicit)
  • VUID-VkCommandBufferAllocateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO

  • VUID-VkCommandBufferAllocateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkCommandBufferAllocateInfo-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-VkCommandBufferAllocateInfo-level-parameter
    level must be a valid VkCommandBufferLevel value

Possible values of VkCommandBufferAllocateInfo::level, specifying the command buffer level, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferLevel {
    VK_COMMAND_BUFFER_LEVEL_PRIMARY = 0,
    VK_COMMAND_BUFFER_LEVEL_SECONDARY = 1,
} VkCommandBufferLevel;
  • VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command buffer.

  • VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command buffer.

To reset a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkResetCommandBuffer(
    VkCommandBuffer                             commandBuffer,
    VkCommandBufferResetFlags                   flags);

Any primary command buffer that is in the recording or executable state and has commandBuffer recorded into it, becomes invalid.

Valid Usage
  • VUID-vkResetCommandBuffer-commandBuffer-00045
    commandBuffer must not be in the pending state

  • VUID-vkResetCommandBuffer-commandBuffer-00046
    commandBuffer must have been allocated from a pool that was created with the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT

Valid Usage (Implicit)
  • VUID-vkResetCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkResetCommandBuffer-flags-parameter
    flags must be a valid combination of VkCommandBufferResetFlagBits values

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Bits which can be set in vkResetCommandBuffer::flags, controlling the reset operation, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferResetFlagBits {
    VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandBufferResetFlagBits;
  • VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most or all memory resources currently owned by the command buffer should be returned to the parent command pool. If this flag is not set, then the command buffer may hold onto memory resources and reuse them when recording commands. commandBuffer is moved to the initial state.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferResetFlags;

VkCommandBufferResetFlags is a bitmask type for setting a mask of zero or more VkCommandBufferResetFlagBits.

To free command buffers, call:

// Provided by VK_VERSION_1_0
void vkFreeCommandBuffers(
    VkDevice                                    device,
    VkCommandPool                               commandPool,
    uint32_t                                    commandBufferCount,
    const VkCommandBuffer*                      pCommandBuffers);
  • device is the logical device that owns the command pool.

  • commandPool is the command pool from which the command buffers were allocated.

  • commandBufferCount is the length of the pCommandBuffers array.

  • pCommandBuffers is a pointer to an array of handles of command buffers to free.

Any primary command buffer that is in the recording or executable state and has any element of pCommandBuffers recorded into it, becomes invalid.

Valid Usage
  • VUID-vkFreeCommandBuffers-pCommandBuffers-00047
    All elements of pCommandBuffers must not be in the pending state

  • VUID-vkFreeCommandBuffers-pCommandBuffers-00048
    pCommandBuffers must be a valid pointer to an array of commandBufferCount VkCommandBuffer handles, each element of which must either be a valid handle or NULL

Valid Usage (Implicit)
  • VUID-vkFreeCommandBuffers-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkFreeCommandBuffers-commandPool-parameter
    commandPool must be a valid VkCommandPool handle

  • VUID-vkFreeCommandBuffers-commandBufferCount-arraylength
    commandBufferCount must be greater than 0

  • VUID-vkFreeCommandBuffers-commandPool-parent
    commandPool must have been created, allocated, or retrieved from device

  • VUID-vkFreeCommandBuffers-pCommandBuffers-parent
    Each element of pCommandBuffers that is a valid handle must have been created, allocated, or retrieved from commandPool

Host Synchronization
  • Host access to commandPool must be externally synchronized

  • Host access to each member of pCommandBuffers must be externally synchronized

6.4. Command Buffer Recording

To begin recording a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkBeginCommandBuffer(
    VkCommandBuffer                             commandBuffer,
    const VkCommandBufferBeginInfo*             pBeginInfo);
  • commandBuffer is the handle of the command buffer which is to be put in the recording state.

  • pBeginInfo is a pointer to a VkCommandBufferBeginInfo structure defining additional information about how the command buffer begins recording.

Valid Usage
  • VUID-vkBeginCommandBuffer-commandBuffer-00049
    commandBuffer must not be in the recording or pending state

  • VUID-vkBeginCommandBuffer-commandBuffer-00050
    If commandBuffer was allocated from a VkCommandPool which did not have the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, commandBuffer must be in the initial state

  • VUID-vkBeginCommandBuffer-commandBuffer-00051
    If commandBuffer is a secondary command buffer, the pInheritanceInfo member of pBeginInfo must be a valid VkCommandBufferInheritanceInfo structure

  • VUID-vkBeginCommandBuffer-commandBuffer-00052
    If commandBuffer is a secondary command buffer and either the occlusionQueryEnable member of the pInheritanceInfo member of pBeginInfo is VK_FALSE, or the occlusionQueryPrecise feature is not enabled, then pBeginInfo->pInheritanceInfo->queryFlags must not contain VK_QUERY_CONTROL_PRECISE_BIT

  • VUID-vkBeginCommandBuffer-commandBuffer-02840
    If commandBuffer is a primary command buffer, then pBeginInfo->flags must not set both the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags

Valid Usage (Implicit)
  • VUID-vkBeginCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkBeginCommandBuffer-pBeginInfo-parameter
    pBeginInfo must be a valid pointer to a valid VkCommandBufferBeginInfo structure

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkCommandBufferBeginInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferBeginInfo {
    VkStructureType                          sType;
    const void*                              pNext;
    VkCommandBufferUsageFlags                flags;
    const VkCommandBufferInheritanceInfo*    pInheritanceInfo;
} VkCommandBufferBeginInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkCommandBufferUsageFlagBits specifying usage behavior for the command buffer.

  • pInheritanceInfo is a pointer to a VkCommandBufferInheritanceInfo structure, used if commandBuffer is a secondary command buffer. If this is a primary command buffer, then this value is ignored.

Valid Usage
  • VUID-VkCommandBufferBeginInfo-flags-09123
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-VkCommandBufferBeginInfo-flags-00055
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the framebuffer member of pInheritanceInfo must be either VK_NULL_HANDLE, or a valid VkFramebuffer that is compatible with the renderPass member of pInheritanceInfo

  • VUID-VkCommandBufferBeginInfo-flags-09240
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the dynamicRendering feature is not enabled, the renderPass member of pInheritanceInfo must not be VK_NULL_HANDLE

  • VUID-VkCommandBufferBeginInfo-flags-06002
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is VK_NULL_HANDLE, the pNext chain of pInheritanceInfo must include a VkCommandBufferInheritanceRenderingInfo structure

  • VUID-VkCommandBufferBeginInfo-flags-06003
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the renderPass member of pInheritanceInfo is VK_NULL_HANDLE, and the pNext chain of pInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, the colorAttachmentCount member of that structure must be equal to the value of VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount

  • VUID-VkCommandBufferBeginInfo-flags-06000
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not VK_NULL_HANDLE, the renderPass member of pInheritanceInfo must be a valid VkRenderPass

  • VUID-VkCommandBufferBeginInfo-flags-06001
    If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not VK_NULL_HANDLE, the subpass member of pInheritanceInfo must be a valid subpass index within the renderPass member of pInheritanceInfo

Valid Usage (Implicit)
  • VUID-VkCommandBufferBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO

  • VUID-VkCommandBufferBeginInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeviceGroupCommandBufferBeginInfo

  • VUID-VkCommandBufferBeginInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCommandBufferBeginInfo-flags-parameter
    flags must be a valid combination of VkCommandBufferUsageFlagBits values

Bits which can be set in VkCommandBufferBeginInfo::flags, specifying usage behavior for a command buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferUsageFlagBits {
    VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT = 0x00000001,
    VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT = 0x00000002,
    VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT = 0x00000004,
} VkCommandBufferUsageFlagBits;
  • VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each recording of the command buffer will only be submitted once, and the command buffer will be reset and recorded again between each submission.

  • VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a secondary command buffer is considered to be entirely inside a render pass. If this is a primary command buffer, then this bit is ignored.

  • VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a command buffer can be resubmitted to a queue while it is in the pending state, and recorded into multiple primary command buffers.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferUsageFlags;

VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero or more VkCommandBufferUsageFlagBits.

If the command buffer is a secondary command buffer, then the VkCommandBufferInheritanceInfo structure defines any state that will be inherited from the primary command buffer:

// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferInheritanceInfo {
    VkStructureType                  sType;
    const void*                      pNext;
    VkRenderPass                     renderPass;
    uint32_t                         subpass;
    VkFramebuffer                    framebuffer;
    VkBool32                         occlusionQueryEnable;
    VkQueryControlFlags              queryFlags;
    VkQueryPipelineStatisticFlags    pipelineStatistics;
} VkCommandBufferInheritanceInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • renderPass is a VkRenderPass object defining which render passes the VkCommandBuffer will be compatible with and can be executed within.

  • subpass is the index of the subpass within the render pass instance that the VkCommandBuffer will be executed within.

  • framebuffer can refer to the VkFramebuffer object that the VkCommandBuffer will be rendering to if it is executed within a render pass instance. It can be VK_NULL_HANDLE if the framebuffer is not known.

    Note

    Specifying the exact framebuffer that the secondary command buffer will be executed with may result in better performance at command buffer execution time.

  • occlusionQueryEnable specifies whether the command buffer can be executed while an occlusion query is active in the primary command buffer. If this is VK_TRUE, then this command buffer can be executed whether the primary command buffer has an occlusion query active or not. If this is VK_FALSE, then the primary command buffer must not have an occlusion query active.

  • queryFlags specifies the query flags that can be used by an active occlusion query in the primary command buffer when this secondary command buffer is executed. If this value includes the VK_QUERY_CONTROL_PRECISE_BIT bit, then the active query can return boolean results or actual sample counts. If this bit is not set, then the active query must not use the VK_QUERY_CONTROL_PRECISE_BIT bit.

  • pipelineStatistics is a bitmask of VkQueryPipelineStatisticFlagBits specifying the set of pipeline statistics that can be counted by an active query in the primary command buffer when this secondary command buffer is executed. If this value includes a given bit, then this command buffer can be executed whether the primary command buffer has a pipeline statistics query active that includes this bit or not. If this value excludes a given bit, then the active pipeline statistics query must not be from a query pool that counts that statistic.

If the VkCommandBuffer will not be executed within a render pass instance, or if the render pass instance was begun with vkCmdBeginRendering, renderPass, subpass, and framebuffer are ignored.

Valid Usage
  • VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056
    If the inheritedQueries feature is not enabled, occlusionQueryEnable must be VK_FALSE

  • VUID-VkCommandBufferInheritanceInfo-queryFlags-00057
    If the inheritedQueries feature is enabled, queryFlags must be a valid combination of VkQueryControlFlagBits values

  • VUID-VkCommandBufferInheritanceInfo-queryFlags-02788
    If the inheritedQueries feature is not enabled, queryFlags must be 0

  • VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-02789
    If the pipelineStatisticsQuery feature is enabled, pipelineStatistics must be a valid combination of VkQueryPipelineStatisticFlagBits values

  • VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058
    If the pipelineStatisticsQuery feature is not enabled, pipelineStatistics must be 0

Valid Usage (Implicit)
Note

On some implementations, not using the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command buffers to be patched in-place if needed, rather than creating a copy of the command buffer.

If a command buffer is in the invalid, or executable state, and the command buffer was allocated from a command pool with the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, then vkBeginCommandBuffer implicitly resets the command buffer, behaving as if vkResetCommandBuffer had been called with VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. After the implicit reset, commandBuffer is moved to the recording state.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then that structure controls whether a command buffer can be executed while conditional rendering is active in the primary command buffer.

The VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is defined as:

// Provided by VK_EXT_conditional_rendering
typedef struct VkCommandBufferInheritanceConditionalRenderingInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           conditionalRenderingEnable;
} VkCommandBufferInheritanceConditionalRenderingInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • conditionalRenderingEnable specifies whether the command buffer can be executed while conditional rendering is active in the primary command buffer. If this is VK_TRUE, then this command buffer can be executed whether the primary command buffer has active conditional rendering or not. If this is VK_FALSE, then the primary command buffer must not have conditional rendering active.

If this structure is not present, the behavior is as if conditionalRenderingEnable is VK_FALSE.

Valid Usage
  • VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977
    If the inheritedConditionalRendering feature is not enabled, conditionalRenderingEnable must be VK_FALSE

Valid Usage (Implicit)
  • VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT

To begin recording a secondary command buffer compatible with execution inside a render pass using render pass transform, add the VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the pNext chain of VkCommandBufferInheritanceInfo structure passed to the vkBeginCommandBuffer command specifying the parameters for transformed rasterization.

The VkCommandBufferInheritanceRenderPassTransformInfoQCOM structure is defined as:

// Provided by VK_QCOM_render_pass_transform
typedef struct VkCommandBufferInheritanceRenderPassTransformInfoQCOM {
    VkStructureType                  sType;
    void*                            pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
    VkRect2D                         renderArea;
} VkCommandBufferInheritanceRenderPassTransformInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • transform is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to the render pass.

  • renderArea is the render area that is affected by the command buffer.

When the secondary is recorded to execute within a render pass instance using vkCmdExecuteCommands, the render pass transform parameters of the secondary command buffer must be consistent with the render pass transform parameters specified for the render pass instance. In particular, the transform and renderArea for command buffer must be identical to the transform and renderArea of the render pass instance.

Valid Usage
  • VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-transform-02864
    transform must be VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

Valid Usage (Implicit)
  • VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM

The VkCommandBufferInheritanceViewportScissorInfoNV structure is defined as:

// Provided by VK_NV_inherited_viewport_scissor
typedef struct VkCommandBufferInheritanceViewportScissorInfoNV {
    VkStructureType      sType;
    const void*          pNext;
    VkBool32             viewportScissor2D;
    uint32_t             viewportDepthCount;
    const VkViewport*    pViewportDepths;
} VkCommandBufferInheritanceViewportScissorInfoNV;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • viewportScissor2D specifies whether the listed dynamic state is inherited.

  • viewportDepthCount specifies the maximum number of viewports to inherit. When viewportScissor2D is VK_FALSE, the behavior is as if this value is zero.

  • pViewportDepths is a pointer to a VkViewport structure specifying the expected depth range for each inherited viewport.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceViewportScissorInfoNV structure, then that structure controls whether a command buffer can inherit the following state from other command buffers:

  • VK_DYNAMIC_STATE_SCISSOR

  • VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT

  • VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

as well as the following state, with restrictions on inherited depth values and viewport count:

  • VK_DYNAMIC_STATE_VIEWPORT

  • VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT

If viewportScissor2D is VK_FALSE, then the command buffer does not inherit the listed dynamic state, and should set this state itself. If this structure is not present, the behavior is as if viewportScissor2D is VK_FALSE.

If viewportScissor2D is VK_TRUE, then the listed dynamic state is inherited, and the command buffer must not set this state, except that the viewport and scissor count may be set by binding a graphics pipeline that does not specify this state as dynamic.

Note

Due to this restriction, applications should ensure either all or none of the graphics pipelines bound in this secondary command buffer use dynamic viewport/scissor counts.

When the command buffer is executed as part of a the execution of a vkCmdExecuteCommands command, the inherited state (if enabled) is determined by the following procedure, performed separately for each dynamic state, and separately for each value for dynamic state that consists of multiple values (e.g. multiple viewports).

  • With i being the index of the executed command buffer in the pCommandBuffers array of vkCmdExecuteCommands, if i > 0 and any secondary command buffer from index 0 to i-1 modifies the state, the inherited state is provisionally set to the final value set by the last such secondary command buffer. Binding a graphics pipeline defining the state statically is equivalent to setting the state to an undefined value.

  • Otherwise, the tentatative inherited state is that of the primary command buffer at the point the vkCmdExecuteCommands command was recorded; if the state is undefined, then so is the provisional inherited state.

  • If the provisional inherited state is an undefined value, then the state is not inherited.

  • If the provisional inherited state is a viewport, with n being its viewport index, then if n ≥ viewportDepthCount, or if either VkViewport::minDepth or VkViewport::maxDepth are not equal to the respective values of the nth element of pViewportDepths, then the state is not inherited.

  • If the provisional inherited state passes both checks, then it becomes the actual inherited state.

Note

There is no support for inheriting dynamic state from a secondary command buffer executed as part of a different vkCmdExecuteCommands command.

Valid Usage
  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04782
    If the inheritedViewportScissor2D feature is not enabled, viewportScissor2D must be VK_FALSE

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04783
    If the multiViewport feature is not enabled and viewportScissor2D is VK_TRUE, then viewportDepthCount must be 1

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04784
    If viewportScissor2D is VK_TRUE, then viewportDepthCount must be greater than 0

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04785
    If viewportScissor2D is VK_TRUE, then pViewportDepths must be a valid pointer to an array of viewportDepthCount valid VkViewport structures, except any requirements on x, y, width, and height do not apply

  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04786
    If viewportScissor2D is VK_TRUE, then the command buffer must be recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

Valid Usage (Implicit)
  • VUID-VkCommandBufferInheritanceViewportScissorInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV

The VkCommandBufferInheritanceRenderingInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferInheritanceRenderingInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkRenderingFlags         flags;
    uint32_t                 viewMask;
    uint32_t                 colorAttachmentCount;
    const VkFormat*          pColorAttachmentFormats;
    VkFormat                 depthAttachmentFormat;
    VkFormat                 stencilAttachmentFormat;
    VkSampleCountFlagBits    rasterizationSamples;
} VkCommandBufferInheritanceRenderingInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkCommandBufferInheritanceRenderingInfo VkCommandBufferInheritanceRenderingInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • flags is a bitmask of VkRenderingFlagBits used by the render pass instance.

  • viewMask is the view mask used for rendering.

  • colorAttachmentCount is the number of color attachments specified in the render pass instance.

  • pColorAttachmentFormats is a pointer to an array of VkFormat values defining the format of color attachments.

  • depthAttachmentFormat is a VkFormat value defining the format of the depth attachment.

  • stencilAttachmentFormat is a VkFormat value defining the format of the stencil attachment.

  • rasterizationSamples is a VkSampleCountFlagBits specifying the number of samples used in rasterization.

If the pNext chain of VkCommandBufferInheritanceInfo includes a VkCommandBufferInheritanceRenderingInfo structure, then that structure controls parameters of dynamic render pass instances that the VkCommandBuffer can be executed within. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE, or VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in VkCommandBufferBeginInfo::flags, parameters of this structure are ignored.

If colorAttachmentCount is 0 and the variableMultisampleRate feature is enabled, rasterizationSamples is ignored.

If depthAttachmentFormat, stencilAttachmentFormat, or any element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it indicates that the corresponding attachment is unused within the render pass and writes to those attachments are discarded.

Valid Usage
  • VUID-VkCommandBufferInheritanceRenderingInfo-colorAttachmentCount-06004
    If colorAttachmentCount is not 0, rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-VkCommandBufferInheritanceRenderingInfo-variableMultisampleRate-06005
    If the variableMultisampleRate feature is not enabled, rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06540
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a depth component

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06007
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkCommandBufferInheritanceRenderingInfo-pColorAttachmentFormats-06492
    If any element of pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT , or VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV if the linearColorAttachment feature is enabled

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06541
    If stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a stencil aspect

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06199
    If stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06200
    If depthAttachmentFormat is not VK_FORMAT_UNDEFINED and stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, depthAttachmentFormat must equal stencilAttachmentFormat

  • VUID-VkCommandBufferInheritanceRenderingInfo-multiview-06008
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkCommandBufferInheritanceRenderingInfo-viewMask-06009
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

Valid Usage (Implicit)
  • VUID-VkCommandBufferInheritanceRenderingInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO

  • VUID-VkCommandBufferInheritanceRenderingInfo-flags-parameter
    flags must be a valid combination of VkRenderingFlagBits values

  • VUID-VkCommandBufferInheritanceRenderingInfo-pColorAttachmentFormats-parameter
    If colorAttachmentCount is not 0, pColorAttachmentFormats must be a valid pointer to an array of colorAttachmentCount valid VkFormat values

  • VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-parameter
    depthAttachmentFormat must be a valid VkFormat value

  • VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-parameter
    stencilAttachmentFormat must be a valid VkFormat value

  • VUID-VkCommandBufferInheritanceRenderingInfo-rasterizationSamples-parameter
    If rasterizationSamples is not 0, rasterizationSamples must be a valid VkSampleCountFlagBits value

The VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_AMD_mixed_attachment_samples
typedef struct VkAttachmentSampleCountInfoAMD {
    VkStructureType                 sType;
    const void*                     pNext;
    uint32_t                        colorAttachmentCount;
    const VkSampleCountFlagBits*    pColorAttachmentSamples;
    VkSampleCountFlagBits           depthStencilAttachmentSamples;
} VkAttachmentSampleCountInfoAMD;

or the equivalent

// Provided by VK_KHR_dynamic_rendering with VK_NV_framebuffer_mixed_samples
typedef VkAttachmentSampleCountInfoAMD VkAttachmentSampleCountInfoNV;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • colorAttachmentCount is the number of color attachments specified in a render pass instance.

  • pColorAttachmentSamples is a pointer to an array of VkSampleCountFlagBits values defining the sample count of color attachments.

  • depthStencilAttachmentSamples is a VkSampleCountFlagBits value defining the sample count of a depth/stencil attachment.

If VkCommandBufferInheritanceInfo::renderPass is VK_NULL_HANDLE, VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is specified in VkCommandBufferBeginInfo::flags, and the pNext chain of VkCommandBufferInheritanceInfo includes VkAttachmentSampleCountInfoAMD, then this structure defines the sample counts of each attachment within the render pass instance. If VkAttachmentSampleCountInfoAMD is not included, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples is used as the sample count for each attachment. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE, or VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in VkCommandBufferBeginInfo::flags, parameters of this structure are ignored.

VkAttachmentSampleCountInfoAMD can also be included in the pNext chain of VkGraphicsPipelineCreateInfo. When a graphics pipeline is created without a VkRenderPass, if this structure is included in the pNext chain of VkGraphicsPipelineCreateInfo, it specifies the sample count of attachments used for rendering. If this structure is not specified, and the pipeline does not include a VkRenderPass, the value of VkPipelineMultisampleStateCreateInfo::rasterizationSamples is used as the sample count for each attachment. If a graphics pipeline is created with a valid VkRenderPass, parameters of this structure are ignored.

Valid Usage (Implicit)
  • VUID-VkAttachmentSampleCountInfoAMD-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD

Once recording starts, an application records a sequence of commands (vkCmd*) to set state in the command buffer, draw, dispatch, and other commands.

Several commands can also be recorded indirectly from VkBuffer content, see Device-Generated Commands.

To complete recording of a command buffer, call:

// Provided by VK_VERSION_1_0
VkResult vkEndCommandBuffer(
    VkCommandBuffer                             commandBuffer);
  • commandBuffer is the command buffer to complete recording.

The command buffer must have been in the recording state, and, if successful, is moved to the executable state.

If there was an error during recording, the application will be notified by an unsuccessful return code returned by vkEndCommandBuffer, and the command buffer will be moved to the invalid state.

In case the application recorded one or more video encode operations into the command buffer, implementations may return the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or if values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation.

Note

Applications should not rely on the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error being returned by any command as a means to verify Video Std parameters, as implementations are not required to report the error in any specific set of cases.

Valid Usage
  • VUID-vkEndCommandBuffer-commandBuffer-00059
    commandBuffer must be in the recording state

  • VUID-vkEndCommandBuffer-commandBuffer-00060
    If commandBuffer is a primary command buffer, there must not be an active render pass instance

  • VUID-vkEndCommandBuffer-commandBuffer-00061
    All queries made active during the recording of commandBuffer must have been made inactive

  • VUID-vkEndCommandBuffer-None-01978
    Conditional rendering must not be active

  • VUID-vkEndCommandBuffer-None-06991
    There must be no video session object bound

  • VUID-vkEndCommandBuffer-commandBuffer-01815
    If commandBuffer is a secondary command buffer, there must not be an outstanding vkCmdBeginDebugUtilsLabelEXT command recorded to commandBuffer that has not previously been ended by a call to vkCmdEndDebugUtilsLabelEXT

  • VUID-vkEndCommandBuffer-commandBuffer-00062
    If commandBuffer is a secondary command buffer, there must not be an outstanding vkCmdDebugMarkerBeginEXT command recorded to commandBuffer that has not previously been ended by a call to vkCmdDebugMarkerEndEXT

Valid Usage (Implicit)
  • VUID-vkEndCommandBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR

When a command buffer is in the executable state, it can be submitted to a queue for execution.

6.5. Command Buffer Submission

Note

Submission can be a high overhead operation, and applications should attempt to batch work together into as few calls to vkQueueSubmit or vkQueueSubmit2 as possible.

To submit command buffers to a queue, call:

// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);

or the equivalent command

// Provided by VK_KHR_synchronization2
VkResult vkQueueSubmit2KHR(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);
  • queue is the queue that the command buffers will be submitted to.

  • submitCount is the number of elements in the pSubmits array.

  • pSubmits is a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch.

  • fence is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

vkQueueSubmit2 is a queue submission command, with each batch defined by an element of pSubmits.

Semaphore operations submitted with vkQueueSubmit2 have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore section of the synchronization chapter.

If any command buffer submitted to this queue is in the executable state, it is moved to the pending state. Once execution of all submissions of a command buffer complete, it moves from the pending state, back to the executable state. If a command buffer was recorded with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves back to the invalid state.

If vkQueueSubmit2 fails, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced by the submitted command buffers and any semaphores referenced by pSubmits is unaffected by the call or its failure. If vkQueueSubmit2 fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST. See Lost Device.

Valid Usage
  • VUID-vkQueueSubmit2-fence-04894
    If fence is not VK_NULL_HANDLE, fence must be unsignaled

  • VUID-vkQueueSubmit2-fence-04895
    If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue

  • VUID-vkQueueSubmit2-synchronization2-03866
    The synchronization2 feature must be enabled

  • VUID-vkQueueSubmit2-commandBuffer-03867
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits referenced an VkEvent, that event must not be referenced by a command that has been submitted to another queue and is still in the pending state

  • VUID-vkQueueSubmit2-semaphore-03868
    The semaphore member of any binary semaphore element of the pSignalSemaphoreInfos member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device

  • VUID-vkQueueSubmit2-stageMask-03869
    The stageMask member of any element of the pSignalSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to

  • VUID-vkQueueSubmit2-stageMask-03870
    The stageMask member of any element of the pWaitSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to

  • VUID-vkQueueSubmit2-semaphore-03871
    When a semaphore wait operation for a binary semaphore is executed, as defined by the semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits, there must be no other queues waiting on the same semaphore

  • VUID-vkQueueSubmit2-semaphore-03873
    The semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits that was created with a VkSemaphoreTypeKHR of VK_SEMAPHORE_TYPE_BINARY_KHR must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends must have also been submitted for execution

  • VUID-vkQueueSubmit2-commandBuffer-03874
    The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit2-commandBuffer-03875
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit2-commandBuffer-03876
    Any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit2-commandBuffer-03877
    If any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit2-commandBuffer-03878
    The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to

  • VUID-vkQueueSubmit2-commandBuffer-03879
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits includes a Queue Family Transfer Acquire Operation, there must exist a previously submitted Queue Family Transfer Release Operation on a queue in the queue family identified by the acquire operation, with parameters matching the acquire operation as defined in the definition of such acquire operations, and which happens before the acquire operation

  • VUID-vkQueueSubmit2-commandBuffer-03880
    If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was a vkCmdBeginQuery whose queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the VkDevice that queue was retrieved from, throughout recording of those command buffers

  • VUID-vkQueueSubmit2-queue-06447
    If queue was not created with VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the flags member of any element of pSubmits must not include VK_SUBMIT_PROTECTED_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkQueueSubmit2-queue-parameter
    queue must be a valid VkQueue handle

  • VUID-vkQueueSubmit2-pSubmits-parameter
    If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo2 structures

  • VUID-vkQueueSubmit2-fence-parameter
    If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

  • VUID-vkQueueSubmit2-commonparent
    Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to queue must be externally synchronized

  • Host access to fence must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

The VkSubmitInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkSubmitInfo2 {
    VkStructureType                     sType;
    const void*                         pNext;
    VkSubmitFlags                       flags;
    uint32_t                            waitSemaphoreInfoCount;
    const VkSemaphoreSubmitInfo*        pWaitSemaphoreInfos;
    uint32_t                            commandBufferInfoCount;
    const VkCommandBufferSubmitInfo*    pCommandBufferInfos;
    uint32_t                            signalSemaphoreInfoCount;
    const VkSemaphoreSubmitInfo*        pSignalSemaphoreInfos;
} VkSubmitInfo2;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitInfo2 VkSubmitInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSubmitFlagBits.

  • waitSemaphoreInfoCount is the number of elements in pWaitSemaphoreInfos.

  • pWaitSemaphoreInfos is a pointer to an array of VkSemaphoreSubmitInfo structures defining semaphore wait operations.

  • commandBufferInfoCount is the number of elements in pCommandBufferInfos and the number of command buffers to execute in the batch.

  • pCommandBufferInfos is a pointer to an array of VkCommandBufferSubmitInfo structures describing command buffers to execute in the batch.

  • signalSemaphoreInfoCount is the number of elements in pSignalSemaphoreInfos.

  • pSignalSemaphoreInfos is a pointer to an array of VkSemaphoreSubmitInfo describing semaphore signal operations.

Valid Usage
  • VUID-VkSubmitInfo2-semaphore-03881
    If the same semaphore is used as the semaphore member of both an element of pSignalSemaphoreInfos and pWaitSemaphoreInfos, and that semaphore is a timeline semaphore, the value member of the pSignalSemaphoreInfos element must be greater than the value member of the pWaitSemaphoreInfos element

  • VUID-VkSubmitInfo2-semaphore-03882
    If the semaphore member of any element of pSignalSemaphoreInfos is a timeline semaphore, the value member of that element must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

  • VUID-VkSubmitInfo2-semaphore-03883
    If the semaphore member of any element of pSignalSemaphoreInfos is a timeline semaphore, the value member of that element must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo2-semaphore-03884
    If the semaphore member of any element of pWaitSemaphoreInfos is a timeline semaphore, the value member of that element must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo2-flags-03886
    If flags includes VK_SUBMIT_PROTECTED_BIT, all elements of pCommandBuffers must be protected command buffers

  • VUID-VkSubmitInfo2-flags-03887
    If flags does not include VK_SUBMIT_PROTECTED_BIT, each element of pCommandBuffers must not be a protected command buffer

  • VUID-VkSubmitInfo2KHR-commandBuffer-06192
    If any commandBuffer member of an element of pCommandBufferInfos contains any resumed render pass instances, they must be suspended by a render pass instance earlier in submission order within pCommandBufferInfos

  • VUID-VkSubmitInfo2KHR-commandBuffer-06010
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, they must be resumed by a render pass instance later in submission order within pCommandBufferInfos

  • VUID-VkSubmitInfo2KHR-commandBuffer-06011
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, there must be no action or synchronization commands between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo2KHR-commandBuffer-06012
    If any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, there must be no render pass instances between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo2KHR-variableSampleLocations-06013
    If the variableSampleLocations limit is not supported, and any commandBuffer member of an element of pCommandBufferInfos contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

Valid Usage (Implicit)
  • VUID-VkSubmitInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO_2

  • VUID-VkSubmitInfo2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkFrameBoundaryEXT, VkPerformanceQuerySubmitInfoKHR, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

  • VUID-VkSubmitInfo2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubmitInfo2-flags-parameter
    flags must be a valid combination of VkSubmitFlagBits values

  • VUID-VkSubmitInfo2-pWaitSemaphoreInfos-parameter
    If waitSemaphoreInfoCount is not 0, pWaitSemaphoreInfos must be a valid pointer to an array of waitSemaphoreInfoCount valid VkSemaphoreSubmitInfo structures

  • VUID-VkSubmitInfo2-pCommandBufferInfos-parameter
    If commandBufferInfoCount is not 0, pCommandBufferInfos must be a valid pointer to an array of commandBufferInfoCount valid VkCommandBufferSubmitInfo structures

  • VUID-VkSubmitInfo2-pSignalSemaphoreInfos-parameter
    If signalSemaphoreInfoCount is not 0, pSignalSemaphoreInfos must be a valid pointer to an array of signalSemaphoreInfoCount valid VkSemaphoreSubmitInfo structures

Bits which can be set in VkSubmitInfo2::flags, specifying submission behavior, are:

// Provided by VK_VERSION_1_3
typedef enum VkSubmitFlagBits {
    VK_SUBMIT_PROTECTED_BIT = 0x00000001,
    VK_SUBMIT_PROTECTED_BIT_KHR = VK_SUBMIT_PROTECTED_BIT,
} VkSubmitFlagBits;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitFlagBits VkSubmitFlagBitsKHR;
  • VK_SUBMIT_PROTECTED_BIT specifies that this batch is a protected submission.

// Provided by VK_VERSION_1_3
typedef VkFlags VkSubmitFlags;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSubmitFlags VkSubmitFlagsKHR;

VkSubmitFlags is a bitmask type for setting a mask of zero or more VkSubmitFlagBits.

The VkSemaphoreSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkSemaphoreSubmitInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkSemaphore              semaphore;
    uint64_t                 value;
    VkPipelineStageFlags2    stageMask;
    uint32_t                 deviceIndex;
} VkSemaphoreSubmitInfo;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkSemaphoreSubmitInfo VkSemaphoreSubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • semaphore is a VkSemaphore affected by this operation.

  • value is either the value used to signal semaphore or the value waited on by semaphore, if semaphore is a timeline semaphore. Otherwise it is ignored.

  • stageMask is a VkPipelineStageFlags2 mask of pipeline stages which limit the first synchronization scope of a semaphore signal operation, or second synchronization scope of a semaphore wait operation as described in the semaphore wait operation and semaphore signal operation sections of the synchronization chapter.

  • deviceIndex is the index of the device within a device group that executes the semaphore wait or signal operation.

Whether this structure defines a semaphore wait or signal operation is defined by how it is used.

Valid Usage
  • VUID-VkSemaphoreSubmitInfo-stageMask-03929
    If the geometryShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03930
    If the tessellationShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03931
    If the conditionalRendering feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03932
    If the fragmentDensityMap feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03933
    If the transformFeedback feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03934
    If the meshShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-03935
    If the taskShader feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-VkSemaphoreSubmitInfo-stageMask-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSemaphoreSubmitInfo-stageMask-04957
    If the subpassShading feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-VkSemaphoreSubmitInfo-stageMask-04995
    If the invocationMask feature is not enabled, stageMask must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-VkSemaphoreSubmitInfo-stageMask-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stageMask must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSemaphoreSubmitInfo-device-03888
    If the device that semaphore was created on is not a device group, deviceIndex must be 0

  • VUID-VkSemaphoreSubmitInfo-device-03889
    If the device that semaphore was created on is a device group, deviceIndex must be a valid device index

Valid Usage (Implicit)
  • VUID-VkSemaphoreSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO

  • VUID-VkSemaphoreSubmitInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSemaphoreSubmitInfo-semaphore-parameter
    semaphore must be a valid VkSemaphore handle

  • VUID-VkSemaphoreSubmitInfo-stageMask-parameter
    stageMask must be a valid combination of VkPipelineStageFlagBits2 values

The VkCommandBufferSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkCommandBuffer    commandBuffer;
    uint32_t           deviceMask;
} VkCommandBufferSubmitInfo;

or the equivalent

// Provided by VK_KHR_synchronization2
typedef VkCommandBufferSubmitInfo VkCommandBufferSubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • commandBuffer is a VkCommandBuffer to be submitted for execution.

  • deviceMask is a bitmask indicating which devices in a device group execute the command buffer. A deviceMask of 0 is equivalent to setting all bits corresponding to valid devices in the group to 1.

Valid Usage
  • VUID-VkCommandBufferSubmitInfo-commandBuffer-03890
    commandBuffer must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-VkCommandBufferSubmitInfo-deviceMask-03891
    If deviceMask is not 0, it must be a valid device mask

Valid Usage (Implicit)
  • VUID-VkCommandBufferSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO

  • VUID-VkCommandBufferSubmitInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkCommandBufferSubmitInfo-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

To submit command buffers to a queue, call:

// Provided by VK_VERSION_1_0
VkResult vkQueueSubmit(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo*                         pSubmits,
    VkFence                                     fence);
  • queue is the queue that the command buffers will be submitted to.

  • submitCount is the number of elements in the pSubmits array.

  • pSubmits is a pointer to an array of VkSubmitInfo structures, each specifying a command buffer submission batch.

  • fence is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

vkQueueSubmit is a queue submission command, with each batch defined by an element of pSubmits. Batches begin execution in the order they appear in pSubmits, but may complete out of order.

Fence and semaphore operations submitted with vkQueueSubmit have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore and fence sections of the synchronization chapter.

Details on the interaction of pWaitDstStageMask with synchronization are described in the semaphore wait operation section of the synchronization chapter.

The order that batches appear in pSubmits is used to determine submission order, and thus all the implicit ordering guarantees that respect it. Other than these implicit ordering guarantees and any explicit synchronization primitives, these batches may overlap or otherwise execute out of order.

If any command buffer submitted to this queue is in the executable state, it is moved to the pending state. Once execution of all submissions of a command buffer complete, it moves from the pending state, back to the executable state. If a command buffer was recorded with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to the invalid state.

If vkQueueSubmit fails, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced by the submitted command buffers and any semaphores referenced by pSubmits is unaffected by the call or its failure. If vkQueueSubmit fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST. See Lost Device.

Valid Usage
  • VUID-vkQueueSubmit-fence-00063
    If fence is not VK_NULL_HANDLE, fence must be unsignaled

  • VUID-vkQueueSubmit-fence-00064
    If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue

  • VUID-vkQueueSubmit-pCommandBuffers-00065
    Any calls to vkCmdSetEvent, vkCmdResetEvent or vkCmdWaitEvents that have been recorded into any of the command buffer elements of the pCommandBuffers member of any element of pSubmits, must not reference any VkEvent that is referenced by any of those commands in a command buffer that has been submitted to another queue and is still in the pending state

  • VUID-vkQueueSubmit-pWaitDstStageMask-00066
    Any stage flag included in any element of the pWaitDstStageMask member of any element of pSubmits must be a pipeline stage supported by one of the capabilities of queue, as specified in the table of supported pipeline stages

  • VUID-vkQueueSubmit-pSignalSemaphores-00067
    Each binary semaphore element of the pSignalSemaphores member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device

  • VUID-vkQueueSubmit-pWaitSemaphores-00068
    When a semaphore wait operation referring to a binary semaphore defined by any element of the pWaitSemaphores member of any element of pSubmits executes on queue, there must be no other queues waiting on the same semaphore

  • VUID-vkQueueSubmit-pWaitSemaphores-03238
    All elements of the pWaitSemaphores member of all elements of pSubmits created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends must have also been submitted for execution

  • VUID-vkQueueSubmit-pCommandBuffers-00070
    Each element of the pCommandBuffers member of each element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit-pCommandBuffers-00071
    If any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit-pCommandBuffers-00072
    Any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits must be in the pending or executable state

  • VUID-vkQueueSubmit-pCommandBuffers-00073
    If any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state

  • VUID-vkQueueSubmit-pCommandBuffers-00074
    Each element of the pCommandBuffers member of each element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to

  • VUID-vkQueueSubmit-pSubmits-02207
    If any element of pSubmits->pCommandBuffers includes a Queue Family Transfer Acquire Operation, there must exist a previously submitted Queue Family Transfer Release Operation on a queue in the queue family identified by the acquire operation, with parameters matching the acquire operation as defined in the definition of such acquire operations, and which happens-before the acquire operation

  • VUID-vkQueueSubmit-pCommandBuffers-03220
    If a command recorded into any element of pCommandBuffers was a vkCmdBeginQuery whose queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the VkDevice that queue was retrieved from, throughout recording of those command buffers

  • VUID-vkQueueSubmit-pSubmits-02808
    Any resource created with VK_SHARING_MODE_EXCLUSIVE that is read by an operation specified by pSubmits must not be owned by any queue family other than the one which queue belongs to, at the time it is executed

  • VUID-vkQueueSubmit-pSubmits-04626
    Any resource created with VK_SHARING_MODE_CONCURRENT that is accessed by an operation specified by pSubmits must have included the queue family of queue at resource creation time

  • VUID-vkQueueSubmit-queue-06448
    If queue was not created with VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must be no element of pSubmits that includes an VkProtectedSubmitInfo structure in its pNext chain with protectedSubmit equal to VK_TRUE

Valid Usage (Implicit)
  • VUID-vkQueueSubmit-queue-parameter
    queue must be a valid VkQueue handle

  • VUID-vkQueueSubmit-pSubmits-parameter
    If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo structures

  • VUID-vkQueueSubmit-fence-parameter
    If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

  • VUID-vkQueueSubmit-commonparent
    Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to queue must be externally synchronized

  • Host access to fence must be externally synchronized

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

The VkSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubmitInfo {
    VkStructureType                sType;
    const void*                    pNext;
    uint32_t                       waitSemaphoreCount;
    const VkSemaphore*             pWaitSemaphores;
    const VkPipelineStageFlags*    pWaitDstStageMask;
    uint32_t                       commandBufferCount;
    const VkCommandBuffer*         pCommandBuffers;
    uint32_t                       signalSemaphoreCount;
    const VkSemaphore*             pSignalSemaphores;
} VkSubmitInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreCount is the number of semaphores upon which to wait before executing the command buffers for the batch.

  • pWaitSemaphores is a pointer to an array of VkSemaphore handles upon which to wait before the command buffers for this batch begin execution. If semaphores to wait on are provided, they define a semaphore wait operation.

  • pWaitDstStageMask is a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur.

  • commandBufferCount is the number of command buffers to execute in the batch.

  • pCommandBuffers is a pointer to an array of VkCommandBuffer handles to execute in the batch.

  • signalSemaphoreCount is the number of semaphores to be signaled once the commands specified in pCommandBuffers have completed execution.

  • pSignalSemaphores is a pointer to an array of VkSemaphore handles which will be signaled when the command buffers for this batch have completed execution. If semaphores to be signaled are provided, they define a semaphore signal operation.

The order that command buffers appear in pCommandBuffers is used to determine submission order, and thus all the implicit ordering guarantees that respect it. Other than these implicit ordering guarantees and any explicit synchronization primitives, these command buffers may overlap or otherwise execute out of order.

Valid Usage
  • VUID-VkSubmitInfo-pWaitDstStageMask-04090
    If the geometryShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04091
    If the tessellationShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04092
    If the conditionalRendering feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04093
    If the fragmentDensityMap feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04094
    If the transformFeedback feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04095
    If the meshShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-04096
    If the taskShader feature is not enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubmitInfo-pWaitDstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubmitInfo-pWaitDstStageMask-03937
    If the synchronization2 feature is not enabled, pWaitDstStageMask must not be 0

  • VUID-VkSubmitInfo-pWaitDstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, pWaitDstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubmitInfo-pCommandBuffers-00075
    Each element of pCommandBuffers must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-VkSubmitInfo-pWaitDstStageMask-00078
    Each element of pWaitDstStageMask must not include VK_PIPELINE_STAGE_HOST_BIT

  • VUID-VkSubmitInfo-pWaitSemaphores-03239
    If any element of pWaitSemaphores or pSignalSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then the pNext chain must include a VkTimelineSemaphoreSubmitInfo structure

  • VUID-VkSubmitInfo-pNext-03240
    If the pNext chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of pWaitSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its waitSemaphoreValueCount member must equal waitSemaphoreCount

  • VUID-VkSubmitInfo-pNext-03241
    If the pNext chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of pSignalSemaphores was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its signalSemaphoreValueCount member must equal signalSemaphoreCount

  • VUID-VkSubmitInfo-pSignalSemaphores-03242
    For each element of pSignalSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

  • VUID-VkSubmitInfo-pWaitSemaphores-03243
    For each element of pWaitSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pWaitSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo-pSignalSemaphores-03244
    For each element of pSignalSemaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference

  • VUID-VkSubmitInfo-pNext-04120
    If the pNext chain of this structure does not include a VkProtectedSubmitInfo structure with protectedSubmit set to VK_TRUE, then each element of the pCommandBuffers array must be an unprotected command buffer

  • VUID-VkSubmitInfo-pNext-04148
    If the pNext chain of this structure includes a VkProtectedSubmitInfo structure with protectedSubmit set to VK_TRUE, then each element of the pCommandBuffers array must be a protected command buffer

  • VUID-VkSubmitInfo-pCommandBuffers-06193
    If pCommandBuffers contains any resumed render pass instances, they must be suspended by a render pass instance earlier in submission order within pCommandBuffers

  • VUID-VkSubmitInfo-pCommandBuffers-06014
    If pCommandBuffers contains any suspended render pass instances, they must be resumed by a render pass instance later in submission order within pCommandBuffers

  • VUID-VkSubmitInfo-pCommandBuffers-06015
    If pCommandBuffers contains any suspended render pass instances, there must be no action or synchronization commands executed in a primary or secondary command buffer between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo-pCommandBuffers-06016
    If pCommandBuffers contains any suspended render pass instances, there must be no render pass instances between that render pass instance and the render pass instance that resumes it

  • VUID-VkSubmitInfo-variableSampleLocations-06017
    If the variableSampleLocations limit is not supported, and any element of pCommandBuffers contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

Valid Usage (Implicit)
  • VUID-VkSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO

  • VUID-VkSubmitInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkAmigoProfilingSubmitInfoSEC, VkD3D12FenceSubmitInfoKHR, VkDeviceGroupSubmitInfo, VkFrameBoundaryEXT, VkPerformanceQuerySubmitInfoKHR, VkProtectedSubmitInfo, VkTimelineSemaphoreSubmitInfo, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

  • VUID-VkSubmitInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubmitInfo-pWaitSemaphores-parameter
    If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid VkSemaphore handles

  • VUID-VkSubmitInfo-pWaitDstStageMask-parameter
    If waitSemaphoreCount is not 0, pWaitDstStageMask must be a valid pointer to an array of waitSemaphoreCount valid combinations of VkPipelineStageFlagBits values

  • VUID-VkSubmitInfo-pCommandBuffers-parameter
    If commandBufferCount is not 0, pCommandBuffers must be a valid pointer to an array of commandBufferCount valid VkCommandBuffer handles

  • VUID-VkSubmitInfo-pSignalSemaphores-parameter
    If signalSemaphoreCount is not 0, pSignalSemaphores must be a valid pointer to an array of signalSemaphoreCount valid VkSemaphore handles

  • VUID-VkSubmitInfo-commonparent
    Each of the elements of pCommandBuffers, the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

To specify the values to use when waiting for and signaling semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, add a VkTimelineSemaphoreSubmitInfo structure to the pNext chain of the VkSubmitInfo structure when using vkQueueSubmit or the VkBindSparseInfo structure when using vkQueueBindSparse . The VkTimelineSemaphoreSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkTimelineSemaphoreSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreValueCount;
    const uint64_t*    pWaitSemaphoreValues;
    uint32_t           signalSemaphoreValueCount;
    const uint64_t*    pSignalSemaphoreValues;
} VkTimelineSemaphoreSubmitInfo;

or the equivalent

// Provided by VK_KHR_timeline_semaphore
typedef VkTimelineSemaphoreSubmitInfo VkTimelineSemaphoreSubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreValueCount is the number of semaphore wait values specified in pWaitSemaphoreValues.

  • pWaitSemaphoreValues is a pointer to an array of waitSemaphoreValueCount values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores to wait for.

  • signalSemaphoreValueCount is the number of semaphore signal values specified in pSignalSemaphoreValues.

  • pSignalSemaphoreValues is a pointer to an array signalSemaphoreValueCount values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores to set when signaled.

If the semaphore in VkSubmitInfo::pWaitSemaphores or VkSubmitInfo::pSignalSemaphores corresponding to an entry in pWaitSemaphoreValues or pSignalSemaphoreValues respectively was not created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, the implementation must ignore the value in the pWaitSemaphoreValues or pSignalSemaphoreValues entry.

Valid Usage (Implicit)
  • VUID-VkTimelineSemaphoreSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO

  • VUID-VkTimelineSemaphoreSubmitInfo-pWaitSemaphoreValues-parameter
    If waitSemaphoreValueCount is not 0, and pWaitSemaphoreValues is not NULL, pWaitSemaphoreValues must be a valid pointer to an array of waitSemaphoreValueCount uint64_t values

  • VUID-VkTimelineSemaphoreSubmitInfo-pSignalSemaphoreValues-parameter
    If signalSemaphoreValueCount is not 0, and pSignalSemaphoreValues is not NULL, pSignalSemaphoreValues must be a valid pointer to an array of signalSemaphoreValueCount uint64_t values

To specify the values to use when waiting for and signaling semaphores whose current payload refers to a Direct3D 12 fence, add a VkD3D12FenceSubmitInfoKHR structure to the pNext chain of the VkSubmitInfo structure. The VkD3D12FenceSubmitInfoKHR structure is defined as:

// Provided by VK_KHR_external_semaphore_win32
typedef struct VkD3D12FenceSubmitInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreValuesCount;
    const uint64_t*    pWaitSemaphoreValues;
    uint32_t           signalSemaphoreValuesCount;
    const uint64_t*    pSignalSemaphoreValues;
} VkD3D12FenceSubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreValuesCount is the number of semaphore wait values specified in pWaitSemaphoreValues.

  • pWaitSemaphoreValues is a pointer to an array of waitSemaphoreValuesCount values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores to wait for.

  • signalSemaphoreValuesCount is the number of semaphore signal values specified in pSignalSemaphoreValues.

  • pSignalSemaphoreValues is a pointer to an array of signalSemaphoreValuesCount values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores to set when signaled.

If the semaphore in VkSubmitInfo::pWaitSemaphores or VkSubmitInfo::pSignalSemaphores corresponding to an entry in pWaitSemaphoreValues or pSignalSemaphoreValues respectively does not currently have a payload referring to a Direct3D 12 fence, the implementation must ignore the value in the pWaitSemaphoreValues or pSignalSemaphoreValues entry.

Note

As the introduction of the external semaphore handle type VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of timeline semaphores, support for importing semaphore payloads from external handles of that type into semaphores created (implicitly or explicitly) with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY is preserved for backwards compatibility. However, applications should prefer importing such handle types into semaphores created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, and use the VkTimelineSemaphoreSubmitInfo structure instead of the VkD3D12FenceSubmitInfoKHR structure to specify the values to use when waiting for and signaling such semaphores.

Valid Usage
  • VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079
    waitSemaphoreValuesCount must be the same value as VkSubmitInfo::waitSemaphoreCount, where this structure is in the pNext chain of a VkSubmitInfo structure

  • VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080
    signalSemaphoreValuesCount must be the same value as VkSubmitInfo::signalSemaphoreCount, where this structure is in the pNext chain of a VkSubmitInfo structure

Valid Usage (Implicit)
  • VUID-VkD3D12FenceSubmitInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR

  • VUID-VkD3D12FenceSubmitInfoKHR-pWaitSemaphoreValues-parameter
    If waitSemaphoreValuesCount is not 0, and pWaitSemaphoreValues is not NULL, pWaitSemaphoreValues must be a valid pointer to an array of waitSemaphoreValuesCount uint64_t values

  • VUID-VkD3D12FenceSubmitInfoKHR-pSignalSemaphoreValues-parameter
    If signalSemaphoreValuesCount is not 0, and pSignalSemaphoreValues is not NULL, pSignalSemaphoreValues must be a valid pointer to an array of signalSemaphoreValuesCount uint64_t values

When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may be used in addition to Vulkan semaphores to synchronize the work. Keyed mutexes are a property of a properly created shareable Direct3D 11 resource. They can only be used if the imported resource was created with the D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag.

To acquire keyed mutexes before submitted work and/or release them after, add a VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the pNext chain of the VkSubmitInfo structure.

The VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as:

// Provided by VK_KHR_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    uint32_t                 acquireCount;
    const VkDeviceMemory*    pAcquireSyncs;
    const uint64_t*          pAcquireKeys;
    const uint32_t*          pAcquireTimeouts;
    uint32_t                 releaseCount;
    const VkDeviceMemory*    pReleaseSyncs;
    const uint64_t*          pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • acquireCount is the number of entries in the pAcquireSyncs, pAcquireKeys, and pAcquireTimeouts arrays.

  • pAcquireSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pAcquireKeys is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries in pAcquireSyncs.

  • pAcquireTimeouts is a pointer to an array of timeout values, in millisecond units, for each acquire specified in pAcquireKeys.

  • releaseCount is the number of entries in the pReleaseSyncs and pReleaseKeys arrays.

  • pReleaseSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pReleaseKeys is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries in pReleaseSyncs.

Valid Usage
  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081
    Each member of pAcquireSyncs and pReleaseSyncs must be a device memory object imported by setting VkImportMemoryWin32HandleInfoKHR::handleType to VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT

Valid Usage (Implicit)
  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-parameter
    If acquireCount is not 0, pAcquireSyncs must be a valid pointer to an array of acquireCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireKeys-parameter
    If acquireCount is not 0, pAcquireKeys must be a valid pointer to an array of acquireCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireTimeouts-parameter
    If acquireCount is not 0, pAcquireTimeouts must be a valid pointer to an array of acquireCount uint32_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pReleaseSyncs-parameter
    If releaseCount is not 0, pReleaseSyncs must be a valid pointer to an array of releaseCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pReleaseKeys-parameter
    If releaseCount is not 0, pReleaseKeys must be a valid pointer to an array of releaseCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-commonparent
    Both of the elements of pAcquireSyncs, and the elements of pReleaseSyncs that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may be used in addition to Vulkan semaphores to synchronize the work. Keyed mutexes are a property of a properly created shareable Direct3D 11 resource. They can only be used if the imported resource was created with the D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag.

To acquire keyed mutexes before submitted work and/or release them after, add a VkWin32KeyedMutexAcquireReleaseInfoNV structure to the pNext chain of the VkSubmitInfo structure.

The VkWin32KeyedMutexAcquireReleaseInfoNV structure is defined as:

// Provided by VK_NV_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoNV {
    VkStructureType          sType;
    const void*              pNext;
    uint32_t                 acquireCount;
    const VkDeviceMemory*    pAcquireSyncs;
    const uint64_t*          pAcquireKeys;
    const uint32_t*          pAcquireTimeoutMilliseconds;
    uint32_t                 releaseCount;
    const VkDeviceMemory*    pReleaseSyncs;
    const uint64_t*          pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoNV;
  • acquireCount is the number of entries in the pAcquireSyncs, pAcquireKeys, and pAcquireTimeoutMilliseconds arrays.

  • pAcquireSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pAcquireKeys is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries in pAcquireSyncs.

  • pAcquireTimeoutMilliseconds is a pointer to an array of timeout values, in millisecond units, for each acquire specified in pAcquireKeys.

  • releaseCount is the number of entries in the pReleaseSyncs and pReleaseKeys arrays.

  • pReleaseSyncs is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources.

  • pReleaseKeys is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries in pReleaseSyncs.

Valid Usage (Implicit)
  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireSyncs-parameter
    If acquireCount is not 0, pAcquireSyncs must be a valid pointer to an array of acquireCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireKeys-parameter
    If acquireCount is not 0, pAcquireKeys must be a valid pointer to an array of acquireCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pAcquireTimeoutMilliseconds-parameter
    If acquireCount is not 0, pAcquireTimeoutMilliseconds must be a valid pointer to an array of acquireCount uint32_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pReleaseSyncs-parameter
    If releaseCount is not 0, pReleaseSyncs must be a valid pointer to an array of releaseCount valid VkDeviceMemory handles

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-pReleaseKeys-parameter
    If releaseCount is not 0, pReleaseKeys must be a valid pointer to an array of releaseCount uint64_t values

  • VUID-VkWin32KeyedMutexAcquireReleaseInfoNV-commonparent
    Both of the elements of pAcquireSyncs, and the elements of pReleaseSyncs that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

If the pNext chain of VkSubmitInfo includes a VkProtectedSubmitInfo structure, then the structure indicates whether the batch is protected. The VkProtectedSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkProtectedSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           protectedSubmit;
} VkProtectedSubmitInfo;
  • protectedSubmit specifies whether the batch is protected. If protectedSubmit is VK_TRUE, the batch is protected. If protectedSubmit is VK_FALSE, the batch is unprotected. If the VkSubmitInfo::pNext chain does not include this structure, the batch is unprotected.

Valid Usage (Implicit)
  • VUID-VkProtectedSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO

If the pNext chain of VkSubmitInfo includes a VkDeviceGroupSubmitInfo structure, then that structure includes device indices and masks specifying which physical devices execute semaphore operations and command buffers.

The VkDeviceGroupSubmitInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupSubmitInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           waitSemaphoreCount;
    const uint32_t*    pWaitSemaphoreDeviceIndices;
    uint32_t           commandBufferCount;
    const uint32_t*    pCommandBufferDeviceMasks;
    uint32_t           signalSemaphoreCount;
    const uint32_t*    pSignalSemaphoreDeviceIndices;
} VkDeviceGroupSubmitInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupSubmitInfo VkDeviceGroupSubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • waitSemaphoreCount is the number of elements in the pWaitSemaphoreDeviceIndices array.

  • pWaitSemaphoreDeviceIndices is a pointer to an array of waitSemaphoreCount device indices indicating which physical device executes the semaphore wait operation in the corresponding element of VkSubmitInfo::pWaitSemaphores.

  • commandBufferCount is the number of elements in the pCommandBufferDeviceMasks array.

  • pCommandBufferDeviceMasks is a pointer to an array of commandBufferCount device masks indicating which physical devices execute the command buffer in the corresponding element of VkSubmitInfo::pCommandBuffers. A physical device executes the command buffer if the corresponding bit is set in the mask.

  • signalSemaphoreCount is the number of elements in the pSignalSemaphoreDeviceIndices array.

  • pSignalSemaphoreDeviceIndices is a pointer to an array of signalSemaphoreCount device indices indicating which physical device executes the semaphore signal operation in the corresponding element of VkSubmitInfo::pSignalSemaphores.

If this structure is not present, semaphore operations and command buffers execute on device index zero.

Valid Usage
  • VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082
    waitSemaphoreCount must equal VkSubmitInfo::waitSemaphoreCount

  • VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083
    commandBufferCount must equal VkSubmitInfo::commandBufferCount

  • VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084
    signalSemaphoreCount must equal VkSubmitInfo::signalSemaphoreCount

  • VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085
    All elements of pWaitSemaphoreDeviceIndices and pSignalSemaphoreDeviceIndices must be valid device indices

  • VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086
    All elements of pCommandBufferDeviceMasks must be valid device masks

Valid Usage (Implicit)
  • VUID-VkDeviceGroupSubmitInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO

  • VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-parameter
    If waitSemaphoreCount is not 0, pWaitSemaphoreDeviceIndices must be a valid pointer to an array of waitSemaphoreCount uint32_t values

  • VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-parameter
    If commandBufferCount is not 0, pCommandBufferDeviceMasks must be a valid pointer to an array of commandBufferCount uint32_t values

  • VUID-VkDeviceGroupSubmitInfo-pSignalSemaphoreDeviceIndices-parameter
    If signalSemaphoreCount is not 0, pSignalSemaphoreDeviceIndices must be a valid pointer to an array of signalSemaphoreCount uint32_t values

If the pNext chain of VkSubmitInfo includes a VkPerformanceQuerySubmitInfoKHR structure, then the structure indicates which counter pass is active for the batch in that submit.

The VkPerformanceQuerySubmitInfoKHR structure is defined as:

// Provided by VK_KHR_performance_query
typedef struct VkPerformanceQuerySubmitInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           counterPassIndex;
} VkPerformanceQuerySubmitInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • counterPassIndex specifies which counter pass index is active.

If the VkSubmitInfo::pNext chain does not include this structure, the batch defaults to use counter pass index 0.

Valid Usage
  • VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221
    counterPassIndex must be less than the number of counter passes required by any queries within the batch. The required number of counter passes for a performance query is obtained by calling vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR

Valid Usage (Implicit)
  • VUID-VkPerformanceQuerySubmitInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR

6.6. Queue Forward Progress

When using binary semaphores, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application on any queue. After any call to vkQueueSubmit (or other queue operation), for every queued wait on a semaphore created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY there must be a prior signal of that semaphore that will not be consumed by a different wait on the semaphore.

When using timeline semaphores, wait-before-signal behavior is well-defined and applications can submit work via vkQueueSubmit defining a timeline semaphore wait operation before submitting a corresponding semaphore signal operation. For each timeline semaphore wait operation defined by a call to vkQueueSubmit, the application must ensure that a corresponding semaphore signal operation is executed before forward progress can be made.

If a command buffer submission waits for any events to be signaled, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application. Events signaled by the host must be signaled before the command buffer waits on those events.

Note

The ability for commands to wait on the host to set an events was originally added to allow low-latency updates to resources between host and device. However, to ensure quality of service, implementations would necessarily detect extended stalls in execution and timeout after a short period. As this period is not defined in the Vulkan specification, it is impossible to correctly validate any application with any wait period. Since the original users of this functionality were highly limited and platform-specific, this functionality is now considered defunct and should not be used.

6.7. Secondary Command Buffer Execution

A secondary command buffer must not be directly submitted to a queue. Instead, secondary command buffers are recorded to execute as part of a primary command buffer with the command:

// Provided by VK_VERSION_1_0
void vkCmdExecuteCommands(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    commandBufferCount,
    const VkCommandBuffer*                      pCommandBuffers);
  • commandBuffer is a handle to a primary command buffer that the secondary command buffers are executed in.

  • commandBufferCount is the length of the pCommandBuffers array.

  • pCommandBuffers is a pointer to an array of commandBufferCount secondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.

If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded into any other primary command buffer which is currently in the executable or recording state, that primary command buffer becomes invalid.

Valid Usage
  • VUID-vkCmdExecuteCommands-pCommandBuffers-00088
    Each element of pCommandBuffers must have been allocated with a level of VK_COMMAND_BUFFER_LEVEL_SECONDARY

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00089
    Each element of pCommandBuffers must be in the pending or executable state

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00091
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not be in the pending state

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00092
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not have already been recorded to commandBuffer

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00093
    If any element of pCommandBuffers was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must not appear more than once in pCommandBuffers

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00094
    Each element of pCommandBuffers must have been allocated from a VkCommandPool that was created for the same queue family as the VkCommandPool from which commandBuffer was allocated

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00096
    If vkCmdExecuteCommands is being called within a render pass instance, each element of pCommandBuffers must have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00099
    If vkCmdExecuteCommands is being called within a render pass instance, and any element of pCommandBuffers was recorded with VkCommandBufferInheritanceInfo::framebuffer not equal to VK_NULL_HANDLE, that VkFramebuffer must match the VkFramebuffer used in the current render pass instance

  • VUID-vkCmdExecuteCommands-contents-06018
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, its contents parameter must have been set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06019
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::subpass set to the index of the subpass which the given command buffer will be executed in

  • VUID-vkCmdExecuteCommands-pBeginInfo-06020
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRenderPass, the render passes specified in the pBeginInfo->pInheritanceInfo->renderPass members of the vkBeginCommandBuffer commands used to begin recording each element of pCommandBuffers must be compatible with the current render pass

  • VUID-vkCmdExecuteCommands-pNext-02865
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the pNext chain of VkCommandBufferBeginInfo

  • VUID-vkCmdExecuteCommands-pNext-02866
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::transform identical to VkRenderPassTransformBeginInfoQCOM::transform

  • VUID-vkCmdExecuteCommands-pNext-02867
    If vkCmdExecuteCommands is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in the pNext chain of VkRenderPassBeginInfo, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::renderArea identical to VkRenderPassBeginInfo::renderArea

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00100
    If vkCmdExecuteCommands is not being called within a render pass instance, each element of pCommandBuffers must not have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

  • VUID-vkCmdExecuteCommands-commandBuffer-00101
    If the inheritedQueries feature is not enabled, commandBuffer must not have any queries active

  • VUID-vkCmdExecuteCommands-commandBuffer-00102
    If commandBuffer has a VK_QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::occlusionQueryEnable set to VK_TRUE

  • VUID-vkCmdExecuteCommands-commandBuffer-00103
    If commandBuffer has a VK_QUERY_TYPE_OCCLUSION query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::queryFlags having all bits set that are set for the query

  • VUID-vkCmdExecuteCommands-commandBuffer-00104
    If commandBuffer has a VK_QUERY_TYPE_PIPELINE_STATISTICS query active, then each element of pCommandBuffers must have been recorded with VkCommandBufferInheritanceInfo::pipelineStatistics having all bits set that are set in the VkQueryPool the query uses

  • VUID-vkCmdExecuteCommands-pCommandBuffers-00105
    Each element of pCommandBuffers must not begin any query types that are active in commandBuffer

  • VUID-vkCmdExecuteCommands-commandBuffer-07594
    commandBuffer must not have any queries other than VK_QUERY_TYPE_OCCLUSION and VK_QUERY_TYPE_PIPELINE_STATISTICS active

  • VUID-vkCmdExecuteCommands-commandBuffer-01820
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, each element of pCommandBuffers must be a protected command buffer

  • VUID-vkCmdExecuteCommands-commandBuffer-01821
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, each element of pCommandBuffers must be an unprotected command buffer

  • VUID-vkCmdExecuteCommands-None-02286
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdExecuteCommands-commandBuffer-06533
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in commandBuffer in the current subpass will write to an image subresource as an attachment, commands recorded in elements of pCommandBuffers must not read from the memory backing that image subresource in any other way

  • VUID-vkCmdExecuteCommands-commandBuffer-06534
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in commandBuffer in the current subpass will read from an image subresource used as an attachment in any way other than as an attachment, commands recorded in elements of pCommandBuffers must not write to that image subresource as an attachment

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06535
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in a given element of pCommandBuffers will write to an image subresource as an attachment, commands recorded in elements of pCommandBuffers at a higher index must not read from the memory backing that image subresource in any other way

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06536
    If vkCmdExecuteCommands is being called within a render pass instance and any recorded command in a given element of pCommandBuffers will read from an image subresource used as an attachment in any way other than as an attachment, commands recorded in elements of pCommandBuffers at a higher index must not write to that image subresource as an attachment

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06021
    If pCommandBuffers contains any suspended render pass instances, there must be no action or synchronization commands between that render pass instance and any render pass instance that resumes it

  • VUID-vkCmdExecuteCommands-pCommandBuffers-06022
    If pCommandBuffers contains any suspended render pass instances, there must be no render pass instances between that render pass instance and any render pass instance that resumes it

  • VUID-vkCmdExecuteCommands-variableSampleLocations-06023
    If the variableSampleLocations limit is not supported, and any element of pCommandBuffers contains any suspended render pass instances, where a graphics pipeline has been bound, any pipelines bound in the render pass instance that resumes it, or any subsequent render pass instances that resume from that one and so on, must use the same sample locations

  • VUID-vkCmdExecuteCommands-flags-06024
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, its VkRenderingInfo::flags parameter must have included VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

  • VUID-vkCmdExecuteCommands-pBeginInfo-06025
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the render passes specified in the pBeginInfo->pInheritanceInfo->renderPass members of the vkBeginCommandBuffer commands used to begin recording each element of pCommandBuffers must be VK_NULL_HANDLE

  • VUID-vkCmdExecuteCommands-flags-06026
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the flags member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::flags parameter to vkCmdBeginRendering, excluding VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

  • VUID-vkCmdExecuteCommands-colorAttachmentCount-06027
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the colorAttachmentCount member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::colorAttachmentCount parameter to vkCmdBeginRendering

  • VUID-vkCmdExecuteCommands-imageView-06028
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of the pColorAttachmentFormats member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-imageView-07606
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is VK_NULL_HANDLE, the corresponding element of the pColorAttachmentFormats member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-pDepthAttachment-06029
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-pStencilAttachment-06030
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the stencilAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the format used to create that image view

  • VUID-vkCmdExecuteCommands-pDepthAttachment-06774
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering was VK_NULL_HANDLE, the value of the depthAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-pStencilAttachment-06775
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering was VK_NULL_HANDLE, the value of the stencilAttachmentFormat member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be VK_FORMAT_UNDEFINED

  • VUID-vkCmdExecuteCommands-viewMask-06031
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the viewMask member of the VkCommandBufferInheritanceRenderingInfo structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the VkRenderingInfo::viewMask parameter to vkCmdBeginRendering

  • VUID-vkCmdExecuteCommands-pNext-06032
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of the pColorAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06033
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthStencilAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06034
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of the depthStencilAttachmentSamples member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in the pNext chain of VkCommandBufferBeginInfo::pInheritanceInfo used to begin recording each element of pCommandBuffers must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06035
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the imageView member of an element of the VkRenderingInfo::pColorAttachments parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06036
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pDepthAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

  • VUID-vkCmdExecuteCommands-pNext-06037
    If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if the VkRenderingInfo::pStencilAttachment->imageView parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples must be equal to the sample count used to create that image view

Valid Usage (Implicit)
  • VUID-vkCmdExecuteCommands-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdExecuteCommands-pCommandBuffers-parameter
    pCommandBuffers must be a valid pointer to an array of commandBufferCount valid VkCommandBuffer handles

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

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

  • VUID-vkCmdExecuteCommands-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdExecuteCommands-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

  • VUID-vkCmdExecuteCommands-commandBufferCount-arraylength
    commandBufferCount must be greater than 0

  • VUID-vkCmdExecuteCommands-commonparent
    Both of commandBuffer, and the elements of pCommandBuffers 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 Video Coding Scope Supported Queue Types Command Type

Primary

Both

Outside

Transfer
Graphics
Compute

Indirection

6.8. Command Buffer Device Mask

Each command buffer has a piece of state storing the current device mask of the command buffer. This mask controls which physical devices within the logical device all subsequent commands will execute on, including state-setting commands, action commands, and synchronization commands.

Scissor, exclusive scissor, and viewport state (excluding the count of each) can be set to different values on each physical device (only when set as dynamic state), and each physical device will render using its local copy of the state. Other state is shared between physical devices, such that all physical devices use the most recently set values for the state. However, when recording an action command that uses a piece of state, the most recent command that set that state must have included all physical devices that execute the action command in its current device mask.

The command buffer’s device mask is orthogonal to the pCommandBufferDeviceMasks member of VkDeviceGroupSubmitInfo. Commands only execute on a physical device if the device index is set in both device masks.

If the pNext chain of VkCommandBufferBeginInfo includes a VkDeviceGroupCommandBufferBeginInfo structure, then that structure includes an initial device mask for the command buffer.

The VkDeviceGroupCommandBufferBeginInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupCommandBufferBeginInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceMask;
} VkDeviceGroupCommandBufferBeginInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupCommandBufferBeginInfo VkDeviceGroupCommandBufferBeginInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceMask is the initial value of the command buffer’s device mask.

The initial device mask also acts as an upper bound on the set of devices that can ever be in the device mask in the command buffer.

If this structure is not present, the initial value of a command buffer’s device mask is set to include all physical devices in the logical device when the command buffer begins recording.

Valid Usage
  • VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106
    deviceMask must be a valid device mask value

  • VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107
    deviceMask must not be zero

Valid Usage (Implicit)
  • VUID-VkDeviceGroupCommandBufferBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO

To update the current device mask of a command buffer, call:

// Provided by VK_VERSION_1_1
void vkCmdSetDeviceMask(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    deviceMask);

or the equivalent command

// Provided by VK_KHR_device_group
void vkCmdSetDeviceMaskKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    deviceMask);
  • commandBuffer is command buffer whose current device mask is modified.

  • deviceMask is the new value of the current device mask.

deviceMask is used to filter out subsequent commands from executing on all physical devices whose bit indices are not set in the mask, except commands beginning a render pass instance, commands transitioning to the next subpass in the render pass instance, and commands ending a render pass instance, which always execute on the set of physical devices whose bit indices are included in the deviceMask member of the VkDeviceGroupRenderPassBeginInfo structure passed to the command beginning the corresponding render pass instance.

Valid Usage
  • VUID-vkCmdSetDeviceMask-deviceMask-00108
    deviceMask must be a valid device mask value

  • VUID-vkCmdSetDeviceMask-deviceMask-00109
    deviceMask must not be zero

  • VUID-vkCmdSetDeviceMask-deviceMask-00110
    deviceMask must not include any set bits that were not in the VkDeviceGroupCommandBufferBeginInfo::deviceMask value when the command buffer began recording

  • VUID-vkCmdSetDeviceMask-deviceMask-00111
    If vkCmdSetDeviceMask is called inside a render pass instance, deviceMask must not include any set bits that were not in the VkDeviceGroupRenderPassBeginInfo::deviceMask value when the render pass instance began recording

Valid Usage (Implicit)
  • VUID-vkCmdSetDeviceMask-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

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

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

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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Both

Graphics
Compute
Transfer

State