An application records the commands for a render pass instance one subpass at a time, by beginning a render pass instance, iterating over the subpasses to record commands for that subpass, and then ending the render pass instance.
To begin a render pass instance, call:
void vkCmdBeginRenderPass(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
VkSubpassContents contents);
commandBuffer is the command buffer in which to record the
command.
pRenderPassBegin is a pointer to a VkRenderPassBeginInfo
structure (defined below) which indicates the render pass to begin an
instance of, and the framebuffer the instance uses.
contents specifies how the commands in the first subpass will be
provided, and is one of the values:
typedef enum VkSubpassContents {
VK_SUBPASS_CONTENTS_INLINE = 0,
VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS = 1,
} VkSubpassContents;
If contents is VK_SUBPASS_CONTENTS_INLINE, the contents of the
subpass will be recorded inline in the primary command buffer, and secondary
command buffers must not be executed within the subpass.
If contents is VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS,
the contents are recorded in secondary command buffers that will be called
from the primary command buffer, and vkCmdExecuteCommands is the only
valid command on the command buffer until vkCmdNextSubpass or
vkCmdEndRenderPass.
After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.
The VkRenderPassBeginInfo structure is defined as:
typedef struct VkRenderPassBeginInfo {
VkStructureType sType;
const void* pNext;
VkRenderPass renderPass;
VkFramebuffer framebuffer;
VkRect2D renderArea;
uint32_t clearValueCount;
const VkClearValue* pClearValues;
} VkRenderPassBeginInfo;
sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
renderPass is the render pass to begin an instance of.
framebuffer is the framebuffer containing the attachments that are
used with the render pass.
renderArea is the render area that is affected by the render pass
instance, and is described in more detail below.
clearValueCount is the number of elements in pClearValues.
pClearValues is an array of VkClearValue structures that
contains clear values for each attachment, if the attachment uses a
loadOp value of VK_ATTACHMENT_LOAD_OP_CLEAR or if the
attachment has a depth/stencil format and uses a stencilLoadOp
value of VK_ATTACHMENT_LOAD_OP_CLEAR.
The array is indexed by attachment number.
Only elements corresponding to cleared attachments are used.
Other elements of pClearValues are ignored.
renderArea is the render area that is affected by the render pass
instance.
The effects of attachment load, store and multisample resolve operations are
restricted to the pixels whose x and y coordinates fall within the render
area on all attachments.
The render area extends to all layers of framebuffer.
The application must ensure (using scissor if necessary) that all rendering
is contained within the render area, otherwise the pixels outside of the
render area become undefined and shader side effects may occur for
fragments outside the render area.
The render area must be contained within the framebuffer dimensions.
| Note | |
|---|---|
There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass. |
To query the render area granularity, call:
void vkGetRenderAreaGranularity(
VkDevice device,
VkRenderPass renderPass,
VkExtent2D* pGranularity);
device is the logical device that owns the render pass.
renderPass is a handle to a render pass.
pGranularity points to a VkExtent2D structure in which the
granularity is returned.
The conditions leading to an optimal renderArea are:
offset.x member in renderArea is a multiple of the
width member of the returned VkExtent2D (the horizontal
granularity).
offset.y member in renderArea is a multiple of the
height of the returned VkExtent2D (the vertical
granularity).
offset.width member in renderArea is a multiple
of the horizontal granularity or offset.x+offset.width is
equal to the width of the framebuffer in the
VkRenderPassBeginInfo.
offset.height member in renderArea is a multiple
of the vertical granularity or offset.y+offset.height is
equal to the height of the framebuffer in the
VkRenderPassBeginInfo.
Subpass dependencies are not affected by the render area, and apply to the entire image subresources attached to the framebuffer. Similarly, pipeline barriers are valid even if their effect extends outside the render area.
To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:
void vkCmdNextSubpass(
VkCommandBuffer commandBuffer,
VkSubpassContents contents);
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.
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.
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.
To record a command to end a render pass instance after recording the commands for the last subpass, call:
void vkCmdEndRenderPass(
VkCommandBuffer commandBuffer);
commandBuffer is the command buffer in which to end the current
render pass instance.
Ending a render pass instance performs any multisample resolve operations on the final subpass.