VKCMDEXECUTECOMMANDS(3)

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

C SPECIFICATION

    void vkCmdExecuteCommands(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    commandBufferCount,
        const VkCommandBuffer*                      pCommandBuffers);

PARAMETERS

commandBuffer
    The primary command buffer from which to call the secondary command buffers.

commandBuffersCount
    Length of the pCommandBuffers array.

pCommandBuffers
    An array of secondary command buffer handles.

DESCRIPTION

vkCmdExecuteCommands executes the contents of the secondary command buffers, in the order they appear in the pCommandBuffers array.

If any of the secondary command buffers contains commands that may only be executed inside a renderpass, then they may only be executed between calls to vkCmdBeginRenderPass and vkCmdEndRenderPass and the active renderpass must have a VkSubpassContents property of VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS. The commandBuffer argument must be a primary command buffer. The renderpass and framebuffer provided when beginning the secondary command buffer must match the VkRenderPass and VkFramebuffer provided to vkCmdBeginRenderPass.

If a secondary command buffer was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT usage, then only a single call to the secondary command buffer may exist in any primary command buffer at one time. If this usage bit is clear, then the secondary command buffer may be called multiple times from the same or multiple primary command buffers.

A secondary command buffer must be finished recording, via vkEndCommandBuffer, before it can be referenced in a call to vkCmdExecuteCommands. It must not be reset or destroyed before primary command buffers referencing it have completed executing.

A secondary command buffer can safely be passed to multiple vkCmdExecuteCommands (affecting different primary command buffers) simultaneously, only if it was recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag.

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

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

    • commandBuffer must have been created with a level of VK_COMMAND_BUFFER_LEVEL_PRIMARY

    • Any given element of pCommandBuffers must have been created 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 created 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 created with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag

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

    • 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 the subpass member of the inheritanceInfo structure 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 the framebuffer member of the VkCommandBufferInheritanceInfo structure not equal to VK_NULL_HANDLE, that VkFramebuffer must be compatible with the VkFramebuffer used in the current render pass instance

    • 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 VkCommandBufferBeginInfo::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 VkCommandBufferBeginInfo::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

vkAllocateCommandBuffers, vkFreeCommandBuffers, vkCmdBeginRenderPass, vkCmdEndRenderPass

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.