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 thepCommandBuffers
array.pCommandBuffers
is a pointer to an array ofcommandBufferCount
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 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::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
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::rasterizationSamples
must 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
commandBuffer
must be externally synchronized - Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized ::