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

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

Valid Usage
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 VK_QUEUE_COMPUTE_BIT, VK_QUEUE_GRAPHICS_BIT, or VK_QUEUE_TRANSFER_BIT 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 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
Secondary

Both

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT
VK_QUEUE_TRANSFER_BIT

Indirection

Conditional Rendering

vkCmdExecuteCommands is not affected by conditional rendering

See Also

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 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0