vkCmdExecuteCommands(3)

# vkCmdExecuteCommands(3) Manual Page

## Name

vkCmdExecuteCommands - Execute a secondary command buffer from a primary command buffer

Loading… please wait.

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

## See Also

VK_VERSION_1_0, VkCommandBuffer

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

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0