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);
commandBufferis a handle to a primary command buffer that the secondary command buffers are executed in.commandBufferCountis the length of thepCommandBuffersarray.pCommandBuffersis a pointer to an array ofcommandBufferCountsecondary 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 set to
`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 set to
`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
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
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, 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 VkRenderingAttachmentLocationInfoKHR 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 VkRenderingInputAttachmentIndexInfoKHR
in the inheritance info of each element of pCommandBuffers and in
the current state of commandBuffer must match
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-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
commandBuffermust be externally synchronized - Host access to the
VkCommandPoolthatcommandBufferwas allocated from must be externally synchronized ::