VKCMDEXECUTECOMMANDS(3)

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

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:

    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 an array of secondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.

DESCRIPTION

Once vkCmdExecuteCommands has been called, any prior executions of the secondary command buffers specified by pCommandBuffers in any other primary command buffer become invalidated, unless those secondary command buffers were recorded with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • pCommandBuffers must be a pointer to an array of commandBufferCount valid VkCommandBuffer handles

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

    • commandBuffer must be a primary VkCommandBuffer

    • commandBufferCount must be greater than 0

    • Both of commandBuffer, and the elements of pCommandBuffers must have been created, allocated, or retrieved from the same VkDevice

    • commandBuffer must have been allocated with a level of VK_COMMAND_BUFFER_LEVEL_PRIMARY

    • Any given element of pCommandBuffers must have been allocated with a level of VK_COMMAND_BUFFER_LEVEL_SECONDARY

    • Any given element of pCommandBuffers must not be already pending execution in commandBuffer, or appear twice in pCommandBuffers, unless it was recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag

    • Any given element of pCommandBuffers must not be already pending execution in any other VkCommandBuffer, unless it was recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag

    • Any given element of pCommandBuffers must be in the executable state

    • Any given 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

    • If vkCmdExecuteCommands is being called within a render pass instance, that render pass instance must have been begun with the contents parameter of vkCmdBeginRenderPass set to VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS

    • If vkCmdExecuteCommands is being called within a render pass instance, any given element of pCommandBuffers must have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

    • If vkCmdExecuteCommands is being called within a render pass instance, any given 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

    • If vkCmdExecuteCommands is being called within a render pass instance, any given element of pCommandBuffers must have been recorded with a render pass that is compatible with the current render pass - see ???

    • If vkCmdExecuteCommands is being called within a render pass instance, and any given 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

    • If vkCmdExecuteCommands is not being called within a render pass instance, any given element of pCommandBuffers must not have been recorded with the VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT

    • If the inherited queries feature is not enabled, commandBuffer must not have any queries active

    • 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

    • 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

    • 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

    • Any given element of pCommandBuffers must not begin any query types that are active in commandBuffer

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary | Both | TRANSFER GRAPHICS COMPUTE

SEE ALSO

VkCommandBuffer

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdExecuteCommands

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.