vkCmdExecuteCommands

Secondary command buffers must not be directly submitted to a queue. To record a secondary command buffer to execute as part of a primary command buffer, call:

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.

If the nestedCommandBuffer feature is enabled it is valid usage for vkCmdExecuteCommands to also be recorded to a secondary command buffer.

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-09680

If `vkCmdExecuteCommands` is being called within a render pass
instance begun with [vkCmdBeginRenderPass](/man/vkCmdBeginRenderPass), and
[vkCmdNextSubpass](/man/vkCmdNextSubpass) has not been called in the current render pass
instance, the `contents` parameter of [vkCmdBeginRenderPass](/man/vkCmdBeginRenderPass)
:normative{type="must"} have been `VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS`

, or VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT

VUID-vkCmdExecuteCommands-None-09681

If `vkCmdExecuteCommands` is being called within a render pass
instance begun with [vkCmdBeginRenderPass](/man/vkCmdBeginRenderPass), and
[vkCmdNextSubpass](/man/vkCmdNextSubpass) has been called in the current render pass
instance, the `contents` parameter of the last call to
[vkCmdNextSubpass](/man/vkCmdNextSubpass) :normative{type="must"} have been
`VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS`

, or VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR

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

VUID-vkCmdExecuteCommands-pNext-02867

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

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-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::rasterizationSamplesmust 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::rasterizationSamplesmust 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::rasterizationSamplesmust be equal to the sample count used to create that image view

VUID-vkCmdExecuteCommands-pNext-09299

If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, with any color attachment using a resolve mode of VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, the pNext chain of VkCommandBufferInheritanceInfo used to create each element of pCommandBuffers must include a VkExternalFormatANDROID structure with an externalFormat matching that used to create the resolve attachment in the render pass

VUID-vkCmdExecuteCommands-pNext-09300

If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering with any color attachment using a resolve mode of VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the pNext chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamplesmust be VK_SAMPLE_COUNT_1_BIT

VUID-vkCmdExecuteCommands-commandBuffer-09375

commandBuffer must not be a secondary command buffer unless the nestedCommandBuffer feature is enabled

VUID-vkCmdExecuteCommands-nestedCommandBuffer-09376

If the nestedCommandBuffer feature is enabled, and commandBuffer is a secondary command buffer, the command buffer nesting level of each element of pCommandBuffers must be less than maxCommandBufferNestingLevel

VUID-vkCmdExecuteCommands-nestedCommandBufferRendering-09377

If the nestedCommandBufferRendering feature is not enabled, and commandBuffer is a secondary command buffer, commandBuffer must not have been recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

VUID-vkCmdExecuteCommands-nestedCommandBufferSimultaneousUse-09378

If the nestedCommandBufferSimultaneousUse feature is not enabled, and commandBuffer is a secondary command buffer, each element of pCommandBuffers must not have been recorded with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT

VUID-vkCmdExecuteCommands-pCommandBuffers-09504

If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the color attachment mapping state specified by VkRenderingAttachmentLocationInfo in the inheritance info of each element of pCommandBuffers and in the current state of commandBuffer must match

VUID-vkCmdExecuteCommands-pCommandBuffers-09505

If vkCmdExecuteCommands is being called within a render pass instance begun with vkCmdBeginRendering, the input attachment mapping state specified by VkRenderingInputAttachmentIndexInfo in the inheritance info of each element of pCommandBuffers and in the current state of commandBuffer must match

VUID-vkCmdExecuteCommands-pCommandBuffers-10620

If this command is being recorded within a render pass instance with tile shading enabled, all elements of pCommandBuffers must have been recorded with VK_TILE_SHADING_RENDER_PASS_ENABLE_BIT_QCOM included in VkRenderPassTileShadingCreateInfoQCOM::flags

VUID-vkCmdExecuteCommands-pCommandBuffers-10621

If the per-tile execution model is enabled, all elements of pCommandBuffers must have been recorded with VK_TILE_SHADING_RENDER_PASS_PER_TILE_EXECUTION_BIT_QCOM included in VkRenderPassTileShadingCreateInfoQCOM::flags

VUID-vkCmdExecuteCommands-tileApronSize-10622

If this command is being recorded within a render pass instance, the tileApronSize used to create the render pass instance must equal the VkRenderPassTileShadingCreateInfoQCOM::tileApronSize used to record all elements of pCommandBuffers

VUID-vkCmdExecuteCommands-pCommandBuffers-10623

If any element of pCommandBuffers was recorded with VK_TILE_SHADING_RENDER_PASS_ENABLE_BIT_QCOM included in VkRenderPassTileShadingCreateInfoQCOM::flags, this command must be recorded in a render pass that has tile shading enabled

VUID-vkCmdExecuteCommands-pCommandBuffers-10624

If any element of pCommandBuffers was recorded with VK_TILE_SHADING_RENDER_PASS_PER_TILE_EXECUTION_BIT_QCOM included in VkRenderPassTileShadingCreateInfoQCOM::flags, per-tile execution model must be enabled

VUID-vkCmdExecuteCommands-tileApronSize-10625

If this command is not being recorded into a render pass instance, the VkRenderPassTileShadingCreateInfoQCOM::tileApronSize that was recorded into all elements of pCommandBuffers must equal (0,0)

Host Synchronization

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

vkCmdExecuteCommands

Valid Usage

Valid Usage (Implicit)

Host Synchronization