C Specification
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:
// 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 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.
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.
If the nestedCommandBuffer
feature
is enabled it is valid usage for vkCmdExecuteCommands
to also be
recorded to a secondary command buffer.
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00088
Each element ofpCommandBuffers
must have been allocated with alevel
ofVK_COMMAND_BUFFER_LEVEL_SECONDARY
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00089
Each element ofpCommandBuffers
must be in the pending or executable state -
VUID-vkCmdExecuteCommands-pCommandBuffers-00091
If any element ofpCommandBuffers
was not recorded with theVK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not be in the pending state -
VUID-vkCmdExecuteCommands-pCommandBuffers-00092
If any element ofpCommandBuffers
was not recorded with theVK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not have already been recorded tocommandBuffer
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00093
If any element ofpCommandBuffers
was not recorded with theVK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, it must not appear more than once inpCommandBuffers
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00094
Each element ofpCommandBuffers
must have been allocated from aVkCommandPool
that was created for the same queue family as theVkCommandPool
from whichcommandBuffer
was allocated -
VUID-vkCmdExecuteCommands-pCommandBuffers-00096
IfvkCmdExecuteCommands
is being called within a render pass instance, each element ofpCommandBuffers
must have been recorded with theVK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00099
IfvkCmdExecuteCommands
is being called within a render pass instance, and any element ofpCommandBuffers
was recorded with VkCommandBufferInheritanceInfo::framebuffer
not equal to VK_NULL_HANDLE, thatVkFramebuffer
must match theVkFramebuffer
used in the current render pass instance -
VUID-vkCmdExecuteCommands-contents-06018
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRenderPass, itscontents
parameter must have been set toVK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS
, orVK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT
-
VUID-vkCmdExecuteCommands-pCommandBuffers-06019
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRenderPass, each element ofpCommandBuffers
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
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRenderPass, the render passes specified in thepBeginInfo->pInheritanceInfo->renderPass
members of the vkBeginCommandBuffer commands used to begin recording each element ofpCommandBuffers
must be compatible with the current render pass -
VUID-vkCmdExecuteCommands-pNext-02865
IfvkCmdExecuteCommands
is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in thepNext
chain of VkRenderPassBeginInfo, then each element ofpCommandBuffers
must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM in thepNext
chain of VkCommandBufferBeginInfo -
VUID-vkCmdExecuteCommands-pNext-02866
IfvkCmdExecuteCommands
is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in thepNext
chain of VkRenderPassBeginInfo, then each element ofpCommandBuffers
must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::transform
identical to VkRenderPassTransformBeginInfoQCOM::transform
-
VUID-vkCmdExecuteCommands-pNext-02867
IfvkCmdExecuteCommands
is being called within a render pass instance that included VkRenderPassTransformBeginInfoQCOM in thepNext
chain of VkRenderPassBeginInfo, then each element ofpCommandBuffers
must have been recorded with VkCommandBufferInheritanceRenderPassTransformInfoQCOM::renderArea
identical to VkRenderPassBeginInfo::renderArea
-
VUID-vkCmdExecuteCommands-pCommandBuffers-00100
IfvkCmdExecuteCommands
is not being called within a render pass instance, each element ofpCommandBuffers
must not have been recorded with theVK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
-
VUID-vkCmdExecuteCommands-commandBuffer-00101
If theinheritedQueries
feature is not enabled,commandBuffer
must not have any queries active -
VUID-vkCmdExecuteCommands-commandBuffer-00102
IfcommandBuffer
has aVK_QUERY_TYPE_OCCLUSION
query active, then each element ofpCommandBuffers
must have been recorded withVkCommandBufferInheritanceInfo
::occlusionQueryEnable
set toVK_TRUE
-
VUID-vkCmdExecuteCommands-commandBuffer-00103
IfcommandBuffer
has aVK_QUERY_TYPE_OCCLUSION
query active, then each element ofpCommandBuffers
must have been recorded withVkCommandBufferInheritanceInfo
::queryFlags
having all bits set that are set for the query -
VUID-vkCmdExecuteCommands-commandBuffer-00104
IfcommandBuffer
has aVK_QUERY_TYPE_PIPELINE_STATISTICS
query active, then each element ofpCommandBuffers
must have been recorded withVkCommandBufferInheritanceInfo
::pipelineStatistics
having all bits set that are set in theVkQueryPool
the query uses -
VUID-vkCmdExecuteCommands-pCommandBuffers-00105
Each element ofpCommandBuffers
must not begin any query types that are active incommandBuffer
-
VUID-vkCmdExecuteCommands-commandBuffer-07594
commandBuffer
must not have any queries other thanVK_QUERY_TYPE_OCCLUSION
andVK_QUERY_TYPE_PIPELINE_STATISTICS
active -
VUID-vkCmdExecuteCommands-commandBuffer-01820
IfcommandBuffer
is a protected command buffer andprotectedNoFault
is not supported, each element ofpCommandBuffers
must be a protected command buffer -
VUID-vkCmdExecuteCommands-commandBuffer-01821
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported, each element ofpCommandBuffers
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
IfvkCmdExecuteCommands
is being called within a render pass instance and any recorded command incommandBuffer
in the current subpass will write to an image subresource as an attachment, commands recorded in elements ofpCommandBuffers
must not read from the memory backing that image subresource in any other way -
VUID-vkCmdExecuteCommands-commandBuffer-06534
IfvkCmdExecuteCommands
is being called within a render pass instance and any recorded command incommandBuffer
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 ofpCommandBuffers
must not write to that image subresource as an attachment -
VUID-vkCmdExecuteCommands-pCommandBuffers-06535
IfvkCmdExecuteCommands
is being called within a render pass instance and any recorded command in a given element ofpCommandBuffers
will write to an image subresource as an attachment, commands recorded in elements ofpCommandBuffers
at a higher index must not read from the memory backing that image subresource in any other way -
VUID-vkCmdExecuteCommands-pCommandBuffers-06536
IfvkCmdExecuteCommands
is being called within a render pass instance and any recorded command in a given element ofpCommandBuffers
will read from an image subresource used as an attachment in any way other than as an attachment, commands recorded in elements ofpCommandBuffers
at a higher index must not write to that image subresource as an attachment -
VUID-vkCmdExecuteCommands-pCommandBuffers-06021
IfpCommandBuffers
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
IfpCommandBuffers
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 thevariableSampleLocations
limit is not supported, and any element ofpCommandBuffers
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
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, its VkRenderingInfo::flags
parameter must have includedVK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT
-
VUID-vkCmdExecuteCommands-pBeginInfo-06025
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, the render passes specified in thepBeginInfo->pInheritanceInfo->renderPass
members of the vkBeginCommandBuffer commands used to begin recording each element ofpCommandBuffers
must be VK_NULL_HANDLE -
VUID-vkCmdExecuteCommands-flags-06026
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, theflags
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the VkRenderingInfo::flags
parameter to vkCmdBeginRendering, excludingVK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT
-
VUID-vkCmdExecuteCommands-colorAttachmentCount-06027
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, thecolorAttachmentCount
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the VkRenderingInfo::colorAttachmentCount
parameter to vkCmdBeginRendering -
VUID-vkCmdExecuteCommands-imageView-06028
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, if theimageView
member of an element of the VkRenderingInfo::pColorAttachments
parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of thepColorAttachmentFormats
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the format used to create that image view -
VUID-vkCmdExecuteCommands-imageView-07606
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, if theimageView
member of an element of the VkRenderingInfo::pColorAttachments
parameter to vkCmdBeginRendering is VK_NULL_HANDLE, the corresponding element of thepColorAttachmentFormats
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must beVK_FORMAT_UNDEFINED
-
VUID-vkCmdExecuteCommands-pDepthAttachment-06029
IfvkCmdExecuteCommands
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 thedepthAttachmentFormat
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the format used to create that image view -
VUID-vkCmdExecuteCommands-pStencilAttachment-06030
IfvkCmdExecuteCommands
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 thestencilAttachmentFormat
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the format used to create that image view -
VUID-vkCmdExecuteCommands-pDepthAttachment-06774
IfvkCmdExecuteCommands
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 thedepthAttachmentFormat
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must beVK_FORMAT_UNDEFINED
-
VUID-vkCmdExecuteCommands-pStencilAttachment-06775
IfvkCmdExecuteCommands
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 thestencilAttachmentFormat
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must beVK_FORMAT_UNDEFINED
-
VUID-vkCmdExecuteCommands-viewMask-06031
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, theviewMask
member of the VkCommandBufferInheritanceRenderingInfo structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the VkRenderingInfo::viewMask
parameter to vkCmdBeginRendering -
VUID-vkCmdExecuteCommands-pNext-06032
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
chain of VkCommandBufferInheritanceInfo includes a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if theimageView
member of an element of the VkRenderingInfo::pColorAttachments
parameter to vkCmdBeginRendering is not VK_NULL_HANDLE, the corresponding element of thepColorAttachmentSamples
member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the sample count used to create that image view -
VUID-vkCmdExecuteCommands-pNext-06033
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
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 thedepthStencilAttachmentSamples
member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the sample count used to create that image view -
VUID-vkCmdExecuteCommands-pNext-06034
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
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 thedepthStencilAttachmentSamples
member of the VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure included in thepNext
chain of VkCommandBufferBeginInfo::pInheritanceInfo
used to begin recording each element ofpCommandBuffers
must be equal to the sample count used to create that image view -
VUID-vkCmdExecuteCommands-pNext-06035
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, if theimageView
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
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
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
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering and thepNext
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
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering, with any color attachment using a resolve mode ofVK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID
, thepNext
chain of VkCommandBufferInheritanceInfo used to create each element ofpCommandBuffers
must include a VkExternalFormatANDROID structure with anexternalFormat
matching that used to create the resolve attachment in the render pass -
VUID-vkCmdExecuteCommands-pNext-09300
IfvkCmdExecuteCommands
is being called within a render pass instance begun with vkCmdBeginRendering with any color attachment using a resolve mode ofVK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID
, and thepNext
chain of VkCommandBufferInheritanceInfo does not include a VkAttachmentSampleCountInfoAMD or VkAttachmentSampleCountInfoNV structure, the value of VkCommandBufferInheritanceRenderingInfo::rasterizationSamples
must beVK_SAMPLE_COUNT_1_BIT
-
VUID-vkCmdExecuteCommands-commandBuffer-09375
commandBuffer
must not be a secondary command buffer unless thenestedCommandBuffer
feature is enabled -
VUID-vkCmdExecuteCommands-nestedCommandBuffer-09376
If thenestedCommandBuffer
feature is enabled, the command buffer nesting level of each element ofpCommandBuffers
must be less thanmaxCommandBufferNestingLevel
-
VUID-vkCmdExecuteCommands-nestedCommandBufferRendering-09377
If thenestedCommandBufferRendering
feature is not enabled, andcommandBuffer
is a secondary command buffer,commandBuffer
must not have been recorded withVK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
-
VUID-vkCmdExecuteCommands-nestedCommandBufferSimultaneousUse-09378
If thenestedCommandBufferSimultaneousUse
feature is not enabled, andcommandBuffer
is a secondary command buffer, each element ofpCommandBuffers
must not have been recorded withVK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
-
VUID-vkCmdExecuteCommands-pCommandBuffers-09504
IfvkCmdExecuteCommands
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 ofpCommandBuffers
and in the current state ofcommandBuffer
must match -
VUID-vkCmdExecuteCommands-pCommandBuffers-09505
IfvkCmdExecuteCommands
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 ofpCommandBuffers
and in the current state ofcommandBuffer
must match
-
VUID-vkCmdExecuteCommands-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle -
VUID-vkCmdExecuteCommands-pCommandBuffers-parameter
pCommandBuffers
must be a valid pointer to an array ofcommandBufferCount
valid VkCommandBuffer handles -
VUID-vkCmdExecuteCommands-commandBuffer-recording
commandBuffer
must be in the recording state -
VUID-vkCmdExecuteCommands-commandBuffer-cmdpool
TheVkCommandPool
thatcommandBuffer
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 than0
-
VUID-vkCmdExecuteCommands-commonparent
Both ofcommandBuffer
, and the elements ofpCommandBuffers
must have been created, allocated, or retrieved from the same VkDevice
-
Host access to
commandBuffer
must be externally synchronized -
Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary |
Both |
Outside |
Transfer |
Indirection |
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.