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.