C Specification

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);

Parameters

  • 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.

Description

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-contents-00095
    If vkCmdExecuteCommands is being called within a render pass instance, that render pass instance must have been begun with the contents parameter of vkCmdBeginRenderPass set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS

  • 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-00097
    If vkCmdExecuteCommands is being called within a render pass instance, 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-pInheritanceInfo-00098
    If vkCmdExecuteCommands is being called within a render pass instance, 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-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-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 inherited queries 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-01820
    If commandBuffer is a protected command buffer, then each element of pCommandBuffers must be a protected command buffer

  • VUID-vkCmdExecuteCommands-commandBuffer-01821
    If commandBuffer is an unprotected command buffer, then 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

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-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 Supported Queue Types Pipeline Type

Primary

Both

Transfer
Graphics
Compute

See Also

Document Notes

For more information, see the Vulkan Specification

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

Copyright (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0