vkCmdNextSubpass(3)

C Specification

To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:

// Provided by VK_VERSION_1_0
void vkCmdNextSubpass(
    VkCommandBuffer                             commandBuffer,
    VkSubpassContents                           contents);

Parameters

commandBuffer is the command buffer in which to record the command.
contents specifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of vkCmdBeginRenderPass.

Description

The subpass index for a render pass begins at zero when vkCmdBeginRenderPass is recorded, and increments each time vkCmdNextSubpass is recorded.

Moving to the next subpass automatically performs any multisample resolve operations in the subpass being ended. End-of-subpass multisample resolves are treated as color attachment writes for the purposes of synchronization. This applies to resolve operations for both color and depth/stencil attachments. That is, they are considered to execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their writes are synchronized with VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. Synchronization between rendering within a subpass and any resolve operations at the end of the subpass occurs automatically, without need for explicit dependencies or pipeline barriers. However, if the resolve attachment is also used in a different subpass, an explicit dependency is needed.

After transitioning to the next subpass, the application can record the commands for that subpass.

Valid Usage

VUID-vkCmdNextSubpass-None-00909
The current subpass index must be less than the number of subpasses in the render pass minus one
VUID-vkCmdNextSubpass-None-02349
This command must not be recorded when transform feedback is active

Valid Usage (Implicit)

VUID-vkCmdNextSubpass-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdNextSubpass-contents-parameter
contents must be a valid VkSubpassContents value
VUID-vkCmdNextSubpass-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdNextSubpass-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support graphics operations
VUID-vkCmdNextSubpass-renderpass
This command must only be called inside of a render pass instance
VUID-vkCmdNextSubpass-bufferlevel
commandBuffer must be a primary VkCommandBuffer

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized