8. Render Pass
Draw commands must be recorded within a render pass instance. Each render pass instance defines a set of image resources, referred to as attachments, used during rendering.
To begin a render pass instance, call:
// Provided by VK_VERSION_1_3
void vkCmdBeginRendering(
VkCommandBuffer commandBuffer,
const VkRenderingInfo* pRenderingInfo);or the equivalent command
// Provided by VK_KHR_dynamic_rendering
void vkCmdBeginRenderingKHR(
VkCommandBuffer commandBuffer,
const VkRenderingInfo* pRenderingInfo);-
commandBufferis the command buffer in which to record the command. -
pRenderingInfois a pointer to a VkRenderingInfo structure specifying details of the render pass instance to begin.
After beginning a render pass instance, the command buffer is ready to record draw commands.
If pRenderingInfo->flags includes VK_RENDERING_RESUMING_BIT then
this render pass is resumed from a render pass instance that has been
suspended earlier in submission order.
The VkRenderingInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkRenderingInfo {
VkStructureType sType;
const void* pNext;
VkRenderingFlags flags;
VkRect2D renderArea;
uint32_t layerCount;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkRenderingAttachmentInfo* pColorAttachments;
const VkRenderingAttachmentInfo* pDepthAttachment;
const VkRenderingAttachmentInfo* pStencilAttachment;
} VkRenderingInfo;or the equivalent
// Provided by VK_KHR_dynamic_rendering, VK_QCOM_tile_properties with VK_KHR_dynamic_rendering or VK_VERSION_1_3
typedef VkRenderingInfo VkRenderingInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkRenderingFlagBits. -
renderAreais the render area that is affected by the render pass instance. -
layerCountis the number of layers rendered to in each attachment whenviewMaskis0. -
viewMaskis the view mask indicating the indices of attachment layers that will be rendered when it is not0. -
colorAttachmentCountis the number of elements inpColorAttachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkRenderingAttachmentInfo structures describing any color attachments used. -
pDepthAttachmentis a pointer to a VkRenderingAttachmentInfo structure describing a depth attachment. -
pStencilAttachmentis a pointer to a VkRenderingAttachmentInfo structure describing a stencil attachment.
If viewMask is not 0, multiview is enabled.
If there is an instance of VkDeviceGroupRenderPassBeginInfo included
in the pNext chain and its deviceRenderAreaCount member is not
0, then renderArea is ignored, and the render area is defined
per-device by that structure.
If multiview is enabled, and the multiviewPerViewRenderAreas feature is enabled, and there is an
instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM
included in the pNext chain with perViewRenderAreaCount not
equal to 0, then the elements of
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas
override renderArea and define a render area for each view.
In this case, renderArea must be set to an area at least as large as
the union of all the per-view render areas.
Each element of the pColorAttachments array corresponds to an output
location in the shader, i.e. if the shader declares an output variable
decorated with a Location value of X, then it uses the attachment
provided in pColorAttachments[X].
If the imageView member of any element of pColorAttachments is
VK_NULL_HANDLE,
and resolveMode is not
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID,
writes to the corresponding location by a fragment are discarded.
Bits which can be set in VkRenderingInfo::flags describing
additional properties of the render pass are:
// Provided by VK_VERSION_1_3
typedef enum VkRenderingFlagBits {
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT = 0x00000001,
VK_RENDERING_SUSPENDING_BIT = 0x00000002,
VK_RENDERING_RESUMING_BIT = 0x00000004,
// Provided by VK_EXT_nested_command_buffer
VK_RENDERING_CONTENTS_INLINE_BIT_EXT = 0x00000010,
// Provided by VK_EXT_legacy_dithering with VK_KHR_dynamic_rendering or VK_VERSION_1_3
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000008,
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR = VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT,
VK_RENDERING_SUSPENDING_BIT_KHR = VK_RENDERING_SUSPENDING_BIT,
VK_RENDERING_RESUMING_BIT_KHR = VK_RENDERING_RESUMING_BIT,
} VkRenderingFlagBits;or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlagBits VkRenderingFlagBitsKHR;-
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BITspecifies that draw calls for the render pass instance will be recorded in secondary command buffers. If thenestedCommandBufferfeature is enabled, the draw calls can come from both inline and vkCmdExecuteCommands. -
VK_RENDERING_RESUMING_BITspecifies that the render pass instance is resuming an earlier suspended render pass instance. -
VK_RENDERING_SUSPENDING_BITspecifies that the render pass instance will be suspended. -
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies that Legacy Dithering is enabled for the render pass instance. -
VK_RENDERING_CONTENTS_INLINE_BIT_EXTspecifies that draw calls for the render pass instance can be recorded inline within the current command buffer. When thenestedCommandBufferfeature is enabled this can be combined with theVK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BITbit to allow draw calls to be recorded both inline and in secondary command buffers.
The contents of pRenderingInfo must match between suspended render
pass instances and the render pass instances that resume them, other than
the presence or absence of the VK_RENDERING_RESUMING_BIT,
VK_RENDERING_SUSPENDING_BIT, and
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT flags.
No action or synchronization commands, or other render pass instances, are
allowed between suspending and resuming render pass instances.
// Provided by VK_VERSION_1_3
typedef VkFlags VkRenderingFlags;or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlags VkRenderingFlagsKHR;VkRenderingFlags is a bitmask type for setting a mask of zero or more
VkRenderingFlagBits.
The VkRenderingAttachmentInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkRenderingAttachmentInfo {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkImageLayout imageLayout;
VkResolveModeFlagBits resolveMode;
VkImageView resolveImageView;
VkImageLayout resolveImageLayout;
VkAttachmentLoadOp loadOp;
VkAttachmentStoreOp storeOp;
VkClearValue clearValue;
} VkRenderingAttachmentInfo;or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingAttachmentInfo VkRenderingAttachmentInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used for rendering. -
imageLayoutis the layout thatimageViewwill be in during rendering. -
resolveModeis a VkResolveModeFlagBits value defining how data written toimageViewwill be resolved intoresolveImageView. -
resolveImageViewis an image view used to write resolved data at the end of rendering. -
resolveImageLayoutis the layout thatresolveImageViewwill be in during rendering. -
loadOpis a VkAttachmentLoadOp value defining the load operation for the attachment. -
storeOpis a VkAttachmentStoreOp value defining the store operation for the attachment. -
clearValueis a VkClearValue structure defining values used to clearimageViewwhenloadOpisVK_ATTACHMENT_LOAD_OP_CLEAR.
Values in imageView are loaded and stored according to the values of
loadOp and storeOp, within the render area
for each device
specified in VkRenderingInfo.
If imageView is VK_NULL_HANDLE,
and resolveMode is not
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID,
other members of this structure are ignored; writes to this attachment will
be discarded, and no load,
store, or multisample resolve operations will be performed.
If resolveMode is VK_RESOLVE_MODE_NONE, then
resolveImageView is ignored.
If resolveMode is not VK_RESOLVE_MODE_NONE, and
resolveImageView is not VK_NULL_HANDLE, a
render pass multisample resolve operation
is defined for the attachment subresource.
If resolveMode is
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the
nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
values are only undefined once load
operations have completed.
|
Note
The resolve mode and store operation are independent; it is valid to write both resolved and unresolved values, and equally valid to discard the unresolved values while writing the resolved ones. |
Store and resolve operations are only performed at the end of a render pass
instance that does not specify the VK_RENDERING_SUSPENDING_BIT_KHR
flag.
Load operations are only performed at the beginning of a render pass
instance that does not specify the VK_RENDERING_RESUMING_BIT_KHR flag.
Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance.
If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
and resolveMode is
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, values in the
color attachment will be loaded from the resolve attachment at the start of
rendering, and may also be reloaded any time after a resolve occurs or the
resolve attachment is written to; if this occurs it must happen-before any
writes to the color attachment are performed which happen-after the resolve
that triggers this.
If any color component in the external format is subsampled, values will be
read from the nearest sample in the image when they are loaded.
The VkRenderingFragmentShadingRateAttachmentInfoKHR structure is
defined as:
// Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
typedef struct VkRenderingFragmentShadingRateAttachmentInfoKHR {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkImageLayout imageLayout;
VkExtent2D shadingRateAttachmentTexelSize;
} VkRenderingFragmentShadingRateAttachmentInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used as a fragment shading rate attachment. -
imageLayoutis the layout thatimageViewwill be in during rendering. -
shadingRateAttachmentTexelSizespecifies the number of pixels corresponding to each texel inimageView.
This structure can be included in the pNext chain of
VkRenderingInfo to define a
fragment shading rate
attachment.
If imageView is VK_NULL_HANDLE, or if this structure is not
specified, the implementation behaves as if a valid shading rate attachment
was specified with all texels specifying a single pixel per fragment.
The VkRenderingFragmentDensityMapAttachmentInfoEXT structure is
defined as:
// Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
typedef struct VkRenderingFragmentDensityMapAttachmentInfoEXT {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkImageLayout imageLayout;
} VkRenderingFragmentDensityMapAttachmentInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used as a fragment density map attachment. -
imageLayoutis the layout thatimageViewwill be in during rendering.
This structure can be included in the pNext chain of
VkRenderingInfo to define a fragment density map.
If this structure is not included in the pNext chain, imageView
is treated as VK_NULL_HANDLE.
To query the render area granularity for a render pass instance, call:
// Provided by VK_KHR_maintenance5
void vkGetRenderingAreaGranularityKHR(
VkDevice device,
const VkRenderingAreaInfoKHR* pRenderingAreaInfo,
VkExtent2D* pGranularity);-
deviceis the logical device that owns the render pass instance. -
pRenderingAreaInfois a pointer to a VkRenderingAreaInfoKHR structure specifying details of the render pass instance to query the render area granularity for. -
pGranularityis a pointer to a VkExtent2D structure in which the granularity is returned.
The conditions leading to an optimal renderArea are:
-
the
offset.xmember inrenderAreais a multiple of thewidthmember of the returned VkExtent2D (the horizontal granularity). -
the
offset.ymember inrenderAreais a multiple of theheightmember of the returned VkExtent2D (the vertical granularity). -
either the
extent.widthmember inrenderAreais a multiple of the horizontal granularity oroffset.x+extent.widthis equal to thewidthof each attachment used in the render pass instance. -
either the
extent.heightmember inrenderAreais a multiple of the vertical granularity oroffset.y+extent.heightis equal to theheightof each attachment used in the render pass instance.
The VkRenderingAreaInfoKHR structure is defined as:
// Provided by VK_KHR_maintenance5
typedef struct VkRenderingAreaInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkFormat* pColorAttachmentFormats;
VkFormat depthAttachmentFormat;
VkFormat stencilAttachmentFormat;
} VkRenderingAreaInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewMaskis the viewMask used for rendering. -
colorAttachmentCountis the number of entries inpColorAttachmentFormats -
pColorAttachmentFormatsis a pointer to an array of VkFormat values defining the format of color attachments used in the render pass instance. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment used in the render pass instance. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment used in the render pass instance.
The VkRenderPassStripeBeginInfoARM structure is defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeBeginInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t stripeInfoCount;
const VkRenderPassStripeInfoARM* pStripeInfos;
} VkRenderPassStripeBeginInfoARM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stripeInfoCountis the number of stripes in this render pass instance -
pStripeInfosis a pointer to an array ofstripeInfoCountVkRenderPassStripeInfoARM structures describing the stripes used by the render pass instance.
This structure can be included in the pNext chain of
VkRenderPassBeginInfo
or VkRenderingInfo
to define how the render pass instance is split into stripes.
The VkRenderPassStripeInfoARM structure is defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeInfoARM {
VkStructureType sType;
const void* pNext;
VkRect2D stripeArea;
} VkRenderPassStripeInfoARM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stripeAreais the stripe area, and is described in more detail below.
stripeArea is the render area that is affected by this stripe of the
render pass instance.
It must be a subregion of the renderArea of the render pass instance.
To end a render pass instance, call:
// Provided by VK_VERSION_1_3
void vkCmdEndRendering(
VkCommandBuffer commandBuffer);or the equivalent command
// Provided by VK_KHR_dynamic_rendering
void vkCmdEndRenderingKHR(
VkCommandBuffer commandBuffer);-
commandBufferis the command buffer in which to record the command.
If the value of pRenderingInfo->flags used to begin this render pass
instance included VK_RENDERING_SUSPENDING_BIT, then this render pass
is suspended and will be resumed later in
submission order.
|
Note
For more complex rendering graphs, it is possible to pre-define a static render pass object, which as well as allowing draw commands, allows the definition of framebuffer-local dependencies between multiple subpasses. These objects have a lot of setup cost compared to vkCmdBeginRendering, but use of subpass dependencies can confer important performance benefits on some devices. |
The VkTilePropertiesQCOM structure is defined as:
// Provided by VK_QCOM_tile_properties
typedef struct VkTilePropertiesQCOM {
VkStructureType sType;
void* pNext;
VkExtent3D tileSize;
VkExtent2D apronSize;
VkOffset2D origin;
} VkTilePropertiesQCOM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tileSizeis the dimensions of a tile, with width and height describing the width and height of a tile in pixels, and depth corresponding to the number of slices the tile spans. -
apronSizeis the dimension of the apron. -
originis the top-left corner of the first tile in attachment space.
All tiles will be tightly packed around the first tile, with edges being multiples of tile width and/or height from the origin.
|
Note
Reported value for |
To query the tile properties when using dynamic rendering, call:
// Provided by VK_QCOM_tile_properties
VkResult vkGetDynamicRenderingTilePropertiesQCOM(
VkDevice device,
const VkRenderingInfo* pRenderingInfo,
VkTilePropertiesQCOM* pProperties);-
deviceis a logical device associated with the render pass. -
pRenderingInfois a pointer to the VkRenderingInfo structure specifying details of the render pass instance in dynamic rendering. -
pPropertiesis a pointer to a VkTilePropertiesQCOM structure in which the properties are returned.
8.1. Render Pass Objects
A render pass object represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are used over the course of the subpasses.
Render passes are represented by VkRenderPass handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkRenderPass)An attachment description describes the properties of an attachment including its format, sample count, and how its contents are treated at the beginning and end of each render pass instance.
A subpass represents a phase of rendering that reads and writes a subset of the attachments in a render pass. Rendering commands are recorded into a particular subpass of a render pass instance.
A subpass description describes the subset of attachments that is involved in the execution of a subpass. Each subpass can read from some attachments as input attachments, write to some as color attachments or depth/stencil attachments, perform shader resolve operations to color_attachments or depth/stencil_attachments, and perform multisample resolve operations to resolve attachments. A subpass description can also include a set of preserve attachments, which are attachments that are not read or written by the subpass but whose contents must be preserved throughout the subpass.
A subpass uses an attachment if the attachment is a color, depth/stencil,
resolve,
depth/stencil resolve,
fragment shading rate,
or input attachment for that subpass (as determined by the
pColorAttachments, pDepthStencilAttachment,
pResolveAttachments,
VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment,
VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment->attachment,
and pInputAttachments members of VkSubpassDescription,
respectively).
A subpass does not use an attachment if that attachment is preserved by the
subpass.
The first use of an attachment is in the lowest numbered subpass that uses
that attachment.
Similarly, the last use of an attachment is in the highest numbered
subpass that uses that attachment.
The subpasses in a render pass all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass can only read attachment contents written by previous subpasses at that same (x,y,layer) location. For multi-pixel fragments, the pixel read from an input attachment is selected from the pixels covered by that fragment in an implementation-dependent manner. However, this selection must be made consistently for any fragment with the same shading rate for the lifetime of the VkDevice.
|
Note
By describing a complete set of subpasses in advance, render passes provide the implementation an opportunity to optimize the storage and transfer of attachment data between subpasses. In practice, this means that subpasses with a simple framebuffer-space dependency may be merged into a single tiled rendering pass, keeping the attachment data on-chip for the duration of a render pass instance. However, it is also quite common for a render pass to only contain a single subpass. |
Subpass dependencies describe execution and memory dependencies between subpasses.
A subpass dependency chain is a sequence of subpass dependencies in a render pass, where the source subpass of each subpass dependency (after the first) equals the destination subpass of the previous dependency.
Execution of subpasses may overlap or execute out of order with regards to other subpasses, unless otherwise enforced by an execution dependency. Each subpass only respects submission order for commands recorded in the same subpass, and the vkCmdBeginRenderPass and vkCmdEndRenderPass commands that delimit the render pass - commands within other subpasses are not included. This affects most other implicit ordering guarantees.
A render pass describes the structure of subpasses and attachments
independent of any specific image views for the attachments.
The specific image views that will be used for the attachments, and their
dimensions, are specified in VkFramebuffer objects.
Framebuffers are created with respect to a specific render pass that the
framebuffer is compatible with (see Render Pass
Compatibility).
Collectively, a render pass and a framebuffer define the complete render
target state for one or more subpasses as well as the algorithmic
dependencies between the subpasses.
The various pipeline stages of the drawing commands for a given subpass may execute concurrently and/or out of order, both within and across drawing commands, whilst still respecting pipeline order. However for a given (x,y,layer,sample) sample location, certain per-sample operations are performed in rasterization order.
VK_ATTACHMENT_UNUSED is a constant indicating that a render pass
attachment is not used.
#define VK_ATTACHMENT_UNUSED (~0U)8.2. Render Pass Creation
To create a render pass, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateRenderPass(
VkDevice device,
const VkRenderPassCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkRenderPass* pRenderPass);-
deviceis the logical device that creates the render pass. -
pCreateInfois a pointer to a VkRenderPassCreateInfo structure describing the parameters of the render pass. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pRenderPassis a pointer to a VkRenderPass handle in which the resulting render pass object is returned.
The VkRenderPassCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkRenderPassCreateInfo {
VkStructureType sType;
const void* pNext;
VkRenderPassCreateFlags flags;
uint32_t attachmentCount;
const VkAttachmentDescription* pAttachments;
uint32_t subpassCount;
const VkSubpassDescription* pSubpasses;
uint32_t dependencyCount;
const VkSubpassDependency* pDependencies;
} VkRenderPassCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkRenderPassCreateFlagBits -
attachmentCountis the number of attachments used by this render pass. -
pAttachmentsis a pointer to an array ofattachmentCountVkAttachmentDescription structures describing the attachments used by the render pass. -
subpassCountis the number of subpasses to create. -
pSubpassesis a pointer to an array ofsubpassCountVkSubpassDescription structures describing each subpass. -
dependencyCountis the number of memory dependencies between pairs of subpasses. -
pDependenciesis a pointer to an array ofdependencyCountVkSubpassDependency structures describing dependencies between pairs of subpasses.
|
Note
Care should be taken to avoid a data race here; if any subpasses access attachments with overlapping memory locations, and one of those accesses is a write, a subpass dependency needs to be included between them. |
Bits which can be set in VkRenderPassCreateInfo::flags,
describing additional properties of the render pass, are:
// Provided by VK_VERSION_1_0
typedef enum VkRenderPassCreateFlagBits {
// Provided by VK_QCOM_render_pass_transform
VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM = 0x00000002,
} VkRenderPassCreateFlagBits;-
VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOMspecifies that the created render pass is compatible with render pass transform.
// Provided by VK_VERSION_1_0
typedef VkFlags VkRenderPassCreateFlags;VkRenderPassCreateFlags is a bitmask type for setting a mask of zero
or more VkRenderPassCreateFlagBits.
If the VkRenderPassCreateInfo::pNext chain includes a
VkRenderPassMultiviewCreateInfo structure, then that structure
includes an array of view masks, view offsets, and correlation masks for the
render pass.
The VkRenderPassMultiviewCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkRenderPassMultiviewCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t subpassCount;
const uint32_t* pViewMasks;
uint32_t dependencyCount;
const int32_t* pViewOffsets;
uint32_t correlationMaskCount;
const uint32_t* pCorrelationMasks;
} VkRenderPassMultiviewCreateInfo;or the equivalent
// Provided by VK_KHR_multiview
typedef VkRenderPassMultiviewCreateInfo VkRenderPassMultiviewCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subpassCountis zero or the number of subpasses in the render pass. -
pViewMasksis a pointer to an array ofsubpassCountview masks, where each mask is a bitfield of view indices describing which views rendering is broadcast to in each subpass, when multiview is enabled. IfsubpassCountis zero, each view mask is treated as zero. -
dependencyCountis zero or the number of dependencies in the render pass. -
pViewOffsetsis a pointer to an array ofdependencyCountview offsets, one for each dependency. IfdependencyCountis zero, each dependency’s view offset is treated as zero. Each view offset controls which views in the source subpass the views in the destination subpass depend on. -
correlationMaskCountis zero or the number of correlation masks. -
pCorrelationMasksis a pointer to an array ofcorrelationMaskCountview masks indicating sets of views that may be more efficient to render concurrently.
When a subpass uses a non-zero view mask, multiview functionality is
considered to be enabled.
Multiview is all-or-nothing for a render pass - that is, either all
subpasses must have a non-zero view mask (though some subpasses may have
only one view) or all must be zero.
Multiview causes all drawing and clear commands in the subpass to behave as
if they were broadcast to each view, where a view is represented by one
layer of the framebuffer attachments.
All draws and clears are broadcast to each view index whose bit is set in
the view mask.
The view index is provided in the ViewIndex shader input variable, and
color, depth/stencil, and input attachments all read/write the layer of the
framebuffer corresponding to the view index.
If the view mask is zero for all subpasses, multiview is considered to be disabled and all drawing commands execute normally, without this additional broadcasting.
Some implementations may not support multiview in conjunction with mesh shaders, geometry shaders or tessellation shaders.
When multiview is enabled, the VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a
dependency can be used to express a view-local dependency, meaning that
each view in the destination subpass depends on a single view in the source
subpass.
Unlike pipeline barriers, a subpass dependency can potentially have a
different view mask in the source subpass and the destination subpass.
If the dependency is view-local, then each view (dstView) in the
destination subpass depends on the view dstView +
pViewOffsets[dependency] in the source subpass.
If there is not such a view in the source subpass, then this dependency does
not affect that view in the destination subpass.
If the dependency is not view-local, then all views in the destination
subpass depend on all views in the source subpass, and the view offset is
ignored.
A non-zero view offset is not allowed in a self-dependency.
The elements of pCorrelationMasks are a set of masks of views
indicating that views in the same mask may exhibit spatial coherency
between the views, making it more efficient to render them concurrently.
Correlation masks must not have a functional effect on the results of the
multiview rendering.
When multiview is enabled, at the beginning of each subpass all non-render pass state is undefined. In particular, each time vkCmdBeginRenderPass or vkCmdNextSubpass is called the graphics pipeline must be bound, any relevant descriptor sets or vertex/index buffers must be bound, and any relevant dynamic state or push constants must be set before they are used.
A multiview subpass can declare that its shaders will write per-view
attributes for all views in a single invocation, by setting the
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass
description.
The only supported per-view attributes are position and viewport mask, and
per-view position and viewport masks are written to output array variables
decorated with PositionPerViewNV and ViewportMaskPerViewNV,
respectively.
If VK_NV_viewport_array2 is not supported and enabled,
ViewportMaskPerViewNV must not be used.
Values written to elements of PositionPerViewNV and
ViewportMaskPerViewNV must not depend on the ViewIndex.
The shader must also write to an output variable decorated with
Position, and the value written to Position must equal the value
written to PositionPerViewNV[ViewIndex].
Similarly, if ViewportMaskPerViewNV is written to then the shader must
also write to an output variable decorated with ViewportMaskNV, and the
value written to ViewportMaskNV must equal the value written to
ViewportMaskPerViewNV[ViewIndex].
Implementations will either use values taken from Position and
ViewportMaskNV and invoke the shader once for each view, or will use
values taken from PositionPerViewNV and ViewportMaskPerViewNV and
invoke the shader fewer times.
The values written to Position and ViewportMaskNV must not depend
on the values written to PositionPerViewNV and
ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate
the unused outputs).
All attributes that do not have *PerViewNV counterparts must not depend
on ViewIndex.
Per-view attributes are all-or-nothing for a subpass.
That is, all pipelines compiled against a subpass that includes the
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must write
per-view attributes to the *PerViewNV[] shader outputs, in addition to the
non-per-view (e.g. Position) outputs.
Pipelines compiled against a subpass that does not include this bit must
not include the *PerViewNV[] outputs in their interfaces.
The VkMultiviewPerViewAttributesInfoNVX structure is defined as:
// Provided by VK_KHR_dynamic_rendering with VK_NVX_multiview_per_view_attributes
typedef struct VkMultiviewPerViewAttributesInfoNVX {
VkStructureType sType;
const void* pNext;
VkBool32 perViewAttributes;
VkBool32 perViewAttributesPositionXOnly;
} VkMultiviewPerViewAttributesInfoNVX;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perViewAttributesspecifies that shaders compiled for this pipeline write the attributes for all views in a single invocation of each vertex processing stage. All pipelines executed within a render pass instance that includes this bit must write per-view attributes to the*PerViewNV[]shader outputs, in addition to the non-per-view (e.g.Position) outputs. -
perViewAttributesPositionXOnlyspecifies that shaders compiled for this pipeline use per-view positions which only differ in value in the x component. Per-view viewport mask can also be used.
When dynamic render pass instances are being used, instead of specifying
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX or
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX in the subpass
description flags, the per-attribute properties of the render pass instance
must be specified by the VkMultiviewPerViewAttributesInfoNVX
structure Include the VkMultiviewPerViewAttributesInfoNVX structure in
the pNext chain of VkGraphicsPipelineCreateInfo when creating a
graphics pipeline for dynamic rendering, VkRenderingInfo when starting
a dynamic render pass instance, and VkCommandBufferInheritanceInfo
when specifying the dynamic render pass instance parameters for secondary
command buffers.
If the VkRenderPassCreateInfo::pNext chain includes a
VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that
structure includes a fragment density map attachment for the render pass.
The VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined
as:
// Provided by VK_EXT_fragment_density_map
typedef struct VkRenderPassFragmentDensityMapCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkAttachmentReference fragmentDensityMapAttachment;
} VkRenderPassFragmentDensityMapCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapAttachmentis the fragment density map to use for the render pass.
The fragment density map is read at an implementation-dependent time with
the following constraints determined by the attachment’s image view
flags:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXTspecifies that the fragment density map will be read by the device duringVK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT -
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXTspecifies that the fragment density map will be read by the host during vkEndCommandBuffer of the primary command buffer that the render pass is recorded into -
Otherwise the fragment density map will be read by the host during vkCmdBeginRenderPass
The fragment density map may additionally be read by the device during
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT for any mode.
If this structure is not present, it is as if
fragmentDensityMapAttachment was given as VK_ATTACHMENT_UNUSED.
The VkAttachmentDescription structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkAttachmentDescription {
VkAttachmentDescriptionFlags flags;
VkFormat format;
VkSampleCountFlagBits samples;
VkAttachmentLoadOp loadOp;
VkAttachmentStoreOp storeOp;
VkAttachmentLoadOp stencilLoadOp;
VkAttachmentStoreOp stencilStoreOp;
VkImageLayout initialLayout;
VkImageLayout finalLayout;
} VkAttachmentDescription;-
flagsis a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. -
formatis a VkFormat value specifying the format of the image view that will be used for the attachment. -
samplesis a VkSampleCountFlagBits value specifying the number of samples of the image. -
loadOpis a VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used. -
storeOpis a VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used. -
stencilLoadOpis a VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used. -
stencilStoreOpis a VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used. -
initialLayoutis the layout the attachment image subresource will be in when a render pass instance begins. -
finalLayoutis the layout the attachment image subresource will be transitioned to when a render pass instance ends.
If the attachment uses a color format, then loadOp and storeOp
are used, and stencilLoadOp and stencilStoreOp are ignored.
If the format has depth and/or stencil components, loadOp and
storeOp apply only to the depth data, while stencilLoadOp and
stencilStoreOp define how the stencil data is handled.
loadOp and stencilLoadOp define the
load operations for the attachment.
storeOp and stencilStoreOp define the
store operations for the attachment.
If an attachment is not used by any subpass, loadOp, storeOp,
stencilStoreOp, and stencilLoadOp will be ignored for that
attachment, and no load or store ops will be performed.
However, any transition specified by initialLayout and
finalLayout will still be executed.
If flags includes VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then
the attachment is treated as if it shares physical memory with another
attachment in the same render pass.
This information limits the ability of the implementation to reorder certain
operations (like layout transitions and the loadOp) such that it is
not improperly reordered against other uses of the same physical memory via
a different attachment.
This is described in more detail below.
If a render pass uses multiple attachments that alias the same device
memory, those attachments must each include the
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment
description flags.
Attachments aliasing the same memory occurs in multiple ways:
-
Multiple attachments being assigned the same image view as part of framebuffer creation.
-
Attachments using distinct image views that correspond to the same image subresource of an image.
-
Attachments using views of distinct image subresources which are bound to overlapping memory ranges.
|
Note
Render passes must include subpass dependencies (either directly or via a
subpass dependency chain) between any two subpasses that operate on the same
attachment or aliasing attachments and those subpass dependencies must
include execution and memory dependencies separating uses of the aliases, if
at least one of those subpasses writes to one of the aliases.
These dependencies must not include the |
Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index must not be used multiple times in a single subpass, with one exception: two subpass attachments can use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can be used simultaneously as an input and color or depth/stencil attachment, but must not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments.
If a set of attachments alias each other, then all except the first to be
used in the render pass must use an initialLayout of
VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases
make their contents undefined.
Once an alias has been used and a different alias has been used after it,
the first alias must not be used in any later subpasses.
However, an application can assign the same image view to multiple aliasing
attachment indices, which allows that image view to be used multiple times
even if other aliases are used in between.
|
Note
Once an attachment needs the |
Bits which can be set in VkAttachmentDescription::flags,
describing additional properties of the attachment, are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentDescriptionFlagBits {
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
} VkAttachmentDescriptionFlagBits;-
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BITspecifies that the attachment aliases the same device memory as other attachments.
// Provided by VK_VERSION_1_0
typedef VkFlags VkAttachmentDescriptionFlags;VkAttachmentDescriptionFlags is a bitmask type for setting a mask of
zero or more VkAttachmentDescriptionFlagBits.
The VkRenderPassInputAttachmentAspectCreateInfo structure is defined
as:
// Provided by VK_VERSION_1_1
typedef struct VkRenderPassInputAttachmentAspectCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t aspectReferenceCount;
const VkInputAttachmentAspectReference* pAspectReferences;
} VkRenderPassInputAttachmentAspectCreateInfo;or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkRenderPassInputAttachmentAspectCreateInfo VkRenderPassInputAttachmentAspectCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
aspectReferenceCountis the number of elements in thepAspectReferencesarray. -
pAspectReferencesis a pointer to an array ofaspectReferenceCountVkInputAttachmentAspectReference structures containing a mask describing which aspect(s) can be accessed for a given input attachment within a given subpass.
To specify which aspects of an input attachment can be read, add a
VkRenderPassInputAttachmentAspectCreateInfo structure to the
pNext chain of the VkRenderPassCreateInfo structure:
An application can access any aspect of an input attachment that does not
have a specified aspect mask in the pAspectReferences array.
Otherwise, an application must not access aspect(s) of an input attachment
other than those in its specified aspect mask.
The VkInputAttachmentAspectReference structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkInputAttachmentAspectReference {
uint32_t subpass;
uint32_t inputAttachmentIndex;
VkImageAspectFlags aspectMask;
} VkInputAttachmentAspectReference;or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkInputAttachmentAspectReference VkInputAttachmentAspectReferenceKHR;-
subpassis an index into thepSubpassesarray of the parentVkRenderPassCreateInfostructure. -
inputAttachmentIndexis an index into thepInputAttachmentsof the specified subpass. -
aspectMaskis a mask of which aspect(s) can be accessed within the specified subpass.
This structure specifies an aspect mask for a specific input attachment of a specific subpass in the render pass.
subpass and inputAttachmentIndex index into the render pass as:
pCreateInfo->pSubpasses[subpass].pInputAttachments[inputAttachmentIndex]The VkSubpassDescription structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSubpassDescription {
VkSubpassDescriptionFlags flags;
VkPipelineBindPoint pipelineBindPoint;
uint32_t inputAttachmentCount;
const VkAttachmentReference* pInputAttachments;
uint32_t colorAttachmentCount;
const VkAttachmentReference* pColorAttachments;
const VkAttachmentReference* pResolveAttachments;
const VkAttachmentReference* pDepthStencilAttachment;
uint32_t preserveAttachmentCount;
const uint32_t* pPreserveAttachments;
} VkSubpassDescription;-
flagsis a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass. -
pipelineBindPointis a VkPipelineBindPoint value specifying the pipeline type supported for this subpass. -
inputAttachmentCountis the number of input attachments. -
pInputAttachmentsis a pointer to an array of VkAttachmentReference structures defining the input attachments for this subpass and their layouts. -
colorAttachmentCountis the number of color attachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkAttachmentReference structures defining the color attachments for this subpass and their layouts. -
pResolveAttachmentsisNULLor a pointer to an array ofcolorAttachmentCountVkAttachmentReference structures defining the resolve attachments for this subpass and their layouts. -
pDepthStencilAttachmentis a pointer to a VkAttachmentReference structure specifying the depth/stencil attachment for this subpass and its layout. -
preserveAttachmentCountis the number of preserved attachments. -
pPreserveAttachmentsis a pointer to an array ofpreserveAttachmentCountrender pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.
Each element of the pInputAttachments array corresponds to an input
attachment index in a fragment shader, i.e. if a shader declares an image
variable decorated with a InputAttachmentIndex value of X, then it
uses the attachment provided in pInputAttachments[X].
Input attachments must also be bound to the pipeline in a descriptor set.
If the attachment member of any element of pInputAttachments is
VK_ATTACHMENT_UNUSED, the application must not read from the
corresponding input attachment index.
Fragment shaders can use subpass input variables to access the contents of
an input attachment at the fragment’s (x, y, layer) framebuffer coordinates.
Input attachments must not be used by any subpasses within a render pass
that enables render pass transform.
Each element of the pColorAttachments array corresponds to an output
location in the shader, i.e. if the shader declares an output variable
decorated with a Location value of X, then it uses the attachment
provided in pColorAttachments[X].
If the attachment member of any element of pColorAttachments is
VK_ATTACHMENT_UNUSED,
or if Color Write Enable has been
disabled for the corresponding attachment index,
then writes to the corresponding location by a fragment shader are
discarded.
If
flags does not include
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if
pResolveAttachments is not NULL, each of its elements corresponds to
a color attachment (the element in pColorAttachments at the same
index), and a multisample resolve
operation is defined for each attachment unless the resolve attachment
index is VK_ATTACHMENT_UNUSED.
Similarly, if
flags does not include
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and
VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment
is not NULL and does not have the value VK_ATTACHMENT_UNUSED, it
corresponds to the depth/stencil attachment in
pDepthStencilAttachment, and
multisample resolve operation for depth
and stencil are defined by
VkSubpassDescriptionDepthStencilResolve::depthResolveMode and
VkSubpassDescriptionDepthStencilResolve::stencilResolveMode,
respectively.
If VkSubpassDescriptionDepthStencilResolve::depthResolveMode is
VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does
not have a depth aspect, no resolve operation is performed for the depth
attachment.
If VkSubpassDescriptionDepthStencilResolve::stencilResolveMode
is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment
does not have a stencil aspect, no resolve operation is performed for the
stencil attachment.
If the image subresource range referenced by the depth/stencil attachment is
created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the
multisample resolve operation uses the
sample locations state specified in the sampleLocationsInfo member of
the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations
for the subpass.
If pDepthStencilAttachment is NULL, or if its attachment index is
VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment
will be used in the subpass.
The contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:
-
The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass.
-
There is a subpass S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.
-
The attachment is not used or preserved in subpass S.
In addition, the contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:
-
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOMis set. -
The attachment is used as a color or depth/stencil in the subpass.
Once the contents of an attachment become undefined in subpass S, they remain undefined for subpasses in subpass dependency chains starting with subpass S until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass S1 if those subpasses use or preserve the attachment.
Bits which can be set in VkSubpassDescription::flags,
specifying usage of the subpass, are:
// Provided by VK_VERSION_1_0
typedef enum VkSubpassDescriptionFlagBits {
// Provided by VK_NVX_multiview_per_view_attributes
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX = 0x00000001,
// Provided by VK_NVX_multiview_per_view_attributes
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX = 0x00000002,
// Provided by VK_QCOM_render_pass_shader_resolve
VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM = 0x00000004,
// Provided by VK_QCOM_render_pass_shader_resolve
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM = 0x00000008,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT = 0x00000010,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT = 0x00000020,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT = 0x00000040,
// Provided by VK_EXT_legacy_dithering
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000080,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
} VkSubpassDescriptionFlagBits;-
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVXspecifies that shaders compiled for this subpass write the attributes for all views in a single invocation of each pre-rasterization shader stage. All pipelines compiled against a subpass that includes this bit must write per-view attributes to the*PerViewNV[]shader outputs, in addition to the non-per-view (e.g.Position) outputs. -
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVXspecifies that shaders compiled for this subpass use per-view positions which only differ in value in the x component. Per-view viewport mask can also be used. -
VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOMspecifies that the framebuffer region is the fragment region, that is, the minimum region dependencies are by pixel rather than by sample, such that any fragment shader invocation can access any sample associated with that fragment shader invocation. -
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOMspecifies that the subpass performs shader resolve operations. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies that Legacy Dithering is enabled for this subpass.
|
Note
Shader resolve operations allow for custom resolve operations, but overdrawing pixels may have a performance and/or power cost. Furthermore, since the content of any depth stencil attachment or color attachment is undefined at the beginning of a shader resolve subpass, any depth testing, stencil testing, or blending operation which sources these undefined values also has undefined result value. |
// Provided by VK_VERSION_1_0
typedef VkFlags VkSubpassDescriptionFlags;VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero
or more VkSubpassDescriptionFlagBits.
The VkAttachmentReference structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkAttachmentReference {
uint32_t attachment;
VkImageLayout layout;
} VkAttachmentReference;-
attachmentis either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo::pAttachments, orVK_ATTACHMENT_UNUSEDto signify that this attachment is not used. -
layoutis a VkImageLayout value specifying the layout the attachment uses during the subpass.
VK_SUBPASS_EXTERNAL is a special subpass index value expanding
synchronization scope outside a subpass.
It is described in more detail by VkSubpassDependency.
#define VK_SUBPASS_EXTERNAL (~0U)The VkSubpassDependency structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSubpassDependency {
uint32_t srcSubpass;
uint32_t dstSubpass;
VkPipelineStageFlags srcStageMask;
VkPipelineStageFlags dstStageMask;
VkAccessFlags srcAccessMask;
VkAccessFlags dstAccessMask;
VkDependencyFlags dependencyFlags;
} VkSubpassDependency;-
srcSubpassis the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
dstSubpassis the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlagsis a bitmask of VkDependencyFlagBits.
If srcSubpass is equal to dstSubpass then the
VkSubpassDependency does not directly define a
dependency.
Instead, it enables pipeline barriers to be used in a render pass instance
within the identified subpass, where the scopes of one pipeline barrier
must be a subset of those described by one subpass dependency.
Subpass dependencies specified in this way that include
framebuffer-space stages in the
srcStageMask must only include
framebuffer-space stages in
dstStageMask, and must include VK_DEPENDENCY_BY_REGION_BIT.
When a subpass dependency is specified in this way for a subpass that has
more than one view in its view mask, its dependencyFlags must include
VK_DEPENDENCY_VIEW_LOCAL_BIT.
If srcSubpass and dstSubpass are not equal, when a render pass
instance which includes a subpass dependency is submitted to a queue, it
defines a dependency between the subpasses
identified by srcSubpass and dstSubpass.
If srcSubpass is equal to VK_SUBPASS_EXTERNAL, the first
synchronization scope includes
commands that occur earlier in submission
order than the vkCmdBeginRenderPass used to begin the render pass
instance.
Otherwise, the first set of commands includes all commands submitted as part
of the subpass instance identified by srcSubpass and any
load, store, or multisample resolve
operations on attachments used in srcSubpass.
In either case, the first synchronization scope is limited to operations on
the pipeline stages determined by the
source stage mask specified by
srcStageMask.
If dstSubpass is equal to VK_SUBPASS_EXTERNAL, the second
synchronization scope includes
commands that occur later in submission
order than the vkCmdEndRenderPass used to end the render pass
instance.
Otherwise, the second set of commands includes all commands submitted as
part of the subpass instance identified by dstSubpass and any
load, store, and multisample resolve
operations on attachments used in dstSubpass.
In either case, the second synchronization scope is limited to operations on
the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
The first access scope is
limited to accesses in the pipeline stages determined by the
source stage mask specified by
srcStageMask.
It is also limited to access types in the source access mask specified by srcAccessMask.
The second access scope is
limited to accesses in the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
It is also limited to access types in the destination access mask specified by dstAccessMask.
The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitions within the render pass.
|
Note
For non-attachment resources, the memory dependency expressed by subpass
dependency is nearly identical to that of a VkMemoryBarrier (with
matching For attachments however, subpass dependencies work more like a
VkImageMemoryBarrier defined similarly to the VkMemoryBarrier
above, the queue family indices set to
|
When multiview is enabled, the execution of the multiple views of one
subpass may not occur simultaneously or even back-to-back, and rather may
be interleaved with the execution of other subpasses.
The load and store operations apply to attachments on a per-view basis.
For example, an attachment using VK_ATTACHMENT_LOAD_OP_CLEAR will have
each view cleared on first use, but the first use of one view may be
temporally distant from the first use of another view.
|
Note
A good mental model for multiview is to think of a multiview subpass as if it were a collection of individual (per-view) subpasses that are logically grouped together and described as a single multiview subpass in the API. Similarly, a multiview attachment can be thought of like several individual attachments that happen to be layers in a single image. A view-local dependency between two multiview subpasses acts like a set of one-to-one dependencies between corresponding pairs of per-view subpasses. A view-global dependency between two multiview subpasses acts like a set of N × M dependencies between all pairs of per-view subpasses in the source and destination. Thus, it is a more compact representation which also makes clear the commonality and reuse that is present between views in a subpass. This interpretation motivates the answers to questions like “when does the load op apply” - it is on the first use of each view of an attachment, as if each view was a separate attachment. The content of each view follows the description in attachment content behavior. In particular, if an attachment is preserved, all views within the attachment are preserved. |
If any two subpasses of a render pass activate transform feedback to the same bound transform feedback buffers, a subpass dependency must be included (either directly or via some intermediate subpasses) between them.
If there is no subpass dependency from VK_SUBPASS_EXTERNAL to the
first subpass that uses an attachment, then an implicit subpass dependency
exists from VK_SUBPASS_EXTERNAL to the first subpass it is used in.
The implicit subpass dependency only exists if there exists an automatic
layout transition away from initialLayout.
The subpass dependency operates as if defined with the following parameters:
VkSubpassDependency implicitDependency = {
.srcSubpass = VK_SUBPASS_EXTERNAL,
.dstSubpass = firstSubpass, // First subpass attachment is used in
.srcStageMask = VK_PIPELINE_STAGE_NONE,
.dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
.srcAccessMask = 0,
.dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
.dependencyFlags = 0
};Similarly, if there is no subpass dependency from the last subpass that uses
an attachment to VK_SUBPASS_EXTERNAL, then an implicit subpass
dependency exists from the last subpass it is used in to
VK_SUBPASS_EXTERNAL.
The implicit subpass dependency only exists if there exists an automatic
layout transition into finalLayout.
The subpass dependency operates as if defined with the following parameters:
VkSubpassDependency implicitDependency = {
.srcSubpass = lastSubpass, // Last subpass attachment is used in
.dstSubpass = VK_SUBPASS_EXTERNAL,
.srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
.dstStageMask = VK_PIPELINE_STAGE_NONE,
.srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
.dstAccessMask = 0,
.dependencyFlags = 0
};As subpasses may overlap or execute out of order with regards to other subpasses unless a subpass dependency chain describes otherwise, the layout transitions required between subpasses cannot be known to an application. Instead, an application provides the layout that each attachment must be in at the start and end of a render pass, and the layout it must be in during each subpass it is used in. The implementation then must execute layout transitions between subpasses in order to guarantee that the images are in the layouts required by each subpass, and in the final layout at the end of the render pass.
Automatic layout transitions apply to the entire image subresource attached
to the framebuffer.
If
multiview is not enabled and
the attachment is a view of a 1D or 2D image, the automatic layout
transitions apply to the number of layers specified by
VkFramebufferCreateInfo::layers.
If multiview is enabled and the attachment is a view of a 1D or 2D image,
the automatic layout transitions apply to the layers corresponding to views
which are used by some subpass in the render pass, even if that subpass does
not reference the given attachment.
If the attachment view is a 2D or 2D array view of a 3D image, even if the
attachment view only refers to a subset of the slices of the selected mip
level of the 3D image, automatic layout transitions apply to the entire
subresource referenced which is the entire mip level in this case.
Automatic layout transitions away from the layout used in a subpass
happen-after the availability operations for all dependencies with that
subpass as the srcSubpass.
Automatic layout transitions into the layout used in a subpass happen-before
the visibility operations for all dependencies with that subpass as the
dstSubpass.
Automatic layout transitions away from initialLayout happen-after the
availability operations for all dependencies with a srcSubpass equal
to VK_SUBPASS_EXTERNAL, where dstSubpass uses the attachment
that will be transitioned.
For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
automatic layout transitions away from initialLayout happen-after the
availability operations for all dependencies with a srcSubpass equal
to VK_SUBPASS_EXTERNAL, where dstSubpass uses any aliased
attachment.
Automatic layout transitions into finalLayout happen-before the
visibility operations for all dependencies with a dstSubpass equal to
VK_SUBPASS_EXTERNAL, where srcSubpass uses the attachment that
will be transitioned.
For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
automatic layout transitions into finalLayout happen-before the
visibility operations for all dependencies with a dstSubpass equal to
VK_SUBPASS_EXTERNAL, where srcSubpass uses any aliased
attachment.
The image layout of the depth aspect of a depth/stencil attachment referring
to an image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
on the last sample locations used to render to the attachment, thus
automatic layout transitions use the sample locations state specified in
VkRenderPassSampleLocationsBeginInfoEXT.
Automatic layout transitions of an attachment referring to a depth/stencil
image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the
sample locations the image subresource range referenced by the attachment
was last rendered with.
If the current render pass does not use the attachment as a depth/stencil
attachment in any subpass that happens-before, the automatic layout
transition uses the sample locations state specified in the
sampleLocationsInfo member of the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pAttachmentInitialSampleLocations
array for which the attachmentIndex member equals the attachment index
of the attachment, if one is specified.
Otherwise, the automatic layout transition uses the sample locations state
specified in the sampleLocationsInfo member of the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations
array for which the subpassIndex member equals the index of the
subpass that last used the attachment as a depth/stencil attachment, if one
is specified.
If no sample locations state has been specified for an automatic layout
transition performed on an attachment referring to a depth/stencil image
created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
the contents of the depth aspect of the depth/stencil attachment become
undefined as if the layout of the attachment was transitioned from the
VK_IMAGE_LAYOUT_UNDEFINED layout.
If two subpasses use the same attachment, and both subpasses use the attachment in a read-only layout, no subpass dependency needs to be specified between those subpasses. If an implementation treats those layouts separately, it must insert an implicit subpass dependency between those subpasses to separate the uses in each layout. The subpass dependency operates as if defined with the following parameters:
// Used for input attachments
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
VkAccessFlags inputAttachmentDstAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;
// Used for depth/stencil attachments
VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
VkAccessFlags depthStencilAttachmentDstAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;
VkSubpassDependency implicitDependency = {
.srcSubpass = firstSubpass;
.dstSubpass = secondSubpass;
.srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
.dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
.srcAccessMask = 0;
.dstAccessMask = inputAttachmentDstAccess | depthStencilAttachmentDstAccess;
.dependencyFlags = 0;
};When
drawing using shader objects,
or when
the graphics pipeline is created with
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates, the
application must specify which types of attachments that are written to
during a render pass will also be accessed as non-attachments in the render
pass.
To dynamically set whether a pipeline can access a resource as a non-attachment while it is also used as an attachment that is written to, call:
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
void vkCmdSetAttachmentFeedbackLoopEnableEXT(
VkCommandBuffer commandBuffer,
VkImageAspectFlags aspectMask);-
commandBufferis the command buffer into which the command will be recorded. -
aspectMaskspecifies the types of attachments for which feedback loops will be enabled. Attachment types whose aspects are not included inaspectMaskwill have feedback loops disabled.
For attachments that are written to in a render pass, only attachments with
the aspects specified in aspectMask can be accessed as
non-attachments by subsequent drawing commands.
A more extensible version of render pass creation is also defined below.
To create a render pass, call:
// Provided by VK_VERSION_1_2
VkResult vkCreateRenderPass2(
VkDevice device,
const VkRenderPassCreateInfo2* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkRenderPass* pRenderPass);or the equivalent command
// Provided by VK_KHR_create_renderpass2
VkResult vkCreateRenderPass2KHR(
VkDevice device,
const VkRenderPassCreateInfo2* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkRenderPass* pRenderPass);-
deviceis the logical device that creates the render pass. -
pCreateInfois a pointer to a VkRenderPassCreateInfo2 structure describing the parameters of the render pass. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pRenderPassis a pointer to a VkRenderPass handle in which the resulting render pass object is returned.
This command is functionally identical to vkCreateRenderPass, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkRenderPassCreateInfo2 structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkRenderPassCreateInfo2 {
VkStructureType sType;
const void* pNext;
VkRenderPassCreateFlags flags;
uint32_t attachmentCount;
const VkAttachmentDescription2* pAttachments;
uint32_t subpassCount;
const VkSubpassDescription2* pSubpasses;
uint32_t dependencyCount;
const VkSubpassDependency2* pDependencies;
uint32_t correlatedViewMaskCount;
const uint32_t* pCorrelatedViewMasks;
} VkRenderPassCreateInfo2;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkRenderPassCreateInfo2 VkRenderPassCreateInfo2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
attachmentCountis the number of attachments used by this render pass. -
pAttachmentsis a pointer to an array ofattachmentCountVkAttachmentDescription2 structures describing the attachments used by the render pass. -
subpassCountis the number of subpasses to create. -
pSubpassesis a pointer to an array ofsubpassCountVkSubpassDescription2 structures describing each subpass. -
dependencyCountis the number of dependencies between pairs of subpasses. -
pDependenciesis a pointer to an array ofdependencyCountVkSubpassDependency2 structures describing dependencies between pairs of subpasses. -
correlatedViewMaskCountis the number of correlation masks. -
pCorrelatedViewMasksis a pointer to an array of view masks indicating sets of views that may be more efficient to render concurrently.
Parameters defined by this structure with the same name as those in
VkRenderPassCreateInfo have the identical effect to those parameters;
the child structures are variants of those used in
VkRenderPassCreateInfo which add sType and pNext
parameters, allowing them to be extended.
If the VkSubpassDescription2::viewMask member of any element of
pSubpasses is not zero, multiview functionality is considered to be
enabled for this render pass.
correlatedViewMaskCount and pCorrelatedViewMasks have the same
effect as VkRenderPassMultiviewCreateInfo::correlationMaskCount
and VkRenderPassMultiviewCreateInfo::pCorrelationMasks,
respectively.
The VkAttachmentDescription2 structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescription2 {
VkStructureType sType;
const void* pNext;
VkAttachmentDescriptionFlags flags;
VkFormat format;
VkSampleCountFlagBits samples;
VkAttachmentLoadOp loadOp;
VkAttachmentStoreOp storeOp;
VkAttachmentLoadOp stencilLoadOp;
VkAttachmentStoreOp stencilStoreOp;
VkImageLayout initialLayout;
VkImageLayout finalLayout;
} VkAttachmentDescription2;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentDescription2 VkAttachmentDescription2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. -
formatis a VkFormat value specifying the format of the image that will be used for the attachment. -
samplesis a VkSampleCountFlagBits value specifying the number of samples of the image. -
loadOpis a VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used. -
storeOpis a VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used. -
stencilLoadOpis a VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used. -
stencilStoreOpis a VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used. -
initialLayoutis the layout the attachment image subresource will be in when a render pass instance begins. -
finalLayoutis the layout the attachment image subresource will be transitioned to when a render pass instance ends.
Parameters defined by this structure with the same name as those in VkAttachmentDescription have the identical effect to those parameters.
If the separateDepthStencilLayouts feature is enabled, and format is
a depth/stencil format, initialLayout and finalLayout can be
set to a layout that only specifies the layout of the depth aspect.
If the pNext chain includes a
VkAttachmentDescriptionStencilLayout structure, then the
stencilInitialLayout and stencilFinalLayout members specify the
initial and final layouts of the stencil aspect of a depth/stencil format,
and initialLayout and finalLayout only apply to the depth
aspect.
For depth-only formats, the VkAttachmentDescriptionStencilLayout
structure is ignored.
For stencil-only formats, the initial and final layouts of the stencil
aspect are taken from the VkAttachmentDescriptionStencilLayout
structure if present, or initialLayout and finalLayout if not
present.
If format is a depth/stencil format, and either initialLayout or
finalLayout does not specify a layout for the stencil aspect, then the
application must specify the initial and final layouts of the stencil
aspect by including a VkAttachmentDescriptionStencilLayout structure
in the pNext chain.
loadOp and storeOp are ignored for fragment shading rate
attachments.
No access to the shading rate attachment is performed in loadOp and
storeOp.
Instead, access to
VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR is performed
as fragments are rasterized.
The VkAttachmentDescriptionStencilLayout structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescriptionStencilLayout {
VkStructureType sType;
void* pNext;
VkImageLayout stencilInitialLayout;
VkImageLayout stencilFinalLayout;
} VkAttachmentDescriptionStencilLayout;or the equivalent
// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentDescriptionStencilLayout VkAttachmentDescriptionStencilLayoutKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilInitialLayoutis the layout the stencil aspect of the attachment image subresource will be in when a render pass instance begins. -
stencilFinalLayoutis the layout the stencil aspect of the attachment image subresource will be transitioned to when a render pass instance ends.
The VkSubpassDescription2 structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescription2 {
VkStructureType sType;
const void* pNext;
VkSubpassDescriptionFlags flags;
VkPipelineBindPoint pipelineBindPoint;
uint32_t viewMask;
uint32_t inputAttachmentCount;
const VkAttachmentReference2* pInputAttachments;
uint32_t colorAttachmentCount;
const VkAttachmentReference2* pColorAttachments;
const VkAttachmentReference2* pResolveAttachments;
const VkAttachmentReference2* pDepthStencilAttachment;
uint32_t preserveAttachmentCount;
const uint32_t* pPreserveAttachments;
} VkSubpassDescription2;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDescription2 VkSubpassDescription2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass. -
pipelineBindPointis a VkPipelineBindPoint value specifying the pipeline type supported for this subpass. -
viewMaskis a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled. -
inputAttachmentCountis the number of input attachments. -
pInputAttachmentsis a pointer to an array of VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts. -
colorAttachmentCountis the number of color attachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkAttachmentReference2 structures defining the color attachments for this subpass and their layouts. -
pResolveAttachmentsisNULLor a pointer to an array ofcolorAttachmentCountVkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts. -
pDepthStencilAttachmentis a pointer to a VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout. -
preserveAttachmentCountis the number of preserved attachments. -
pPreserveAttachmentsis a pointer to an array ofpreserveAttachmentCountrender pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.
Parameters defined by this structure with the same name as those in VkSubpassDescription have the identical effect to those parameters.
viewMask has the same effect for the described subpass as
VkRenderPassMultiviewCreateInfo::pViewMasks has on each
corresponding subpass.
If a VkFragmentShadingRateAttachmentInfoKHR structure is included in
the pNext chain, pFragmentShadingRateAttachment is not NULL,
and its attachment member is not VK_ATTACHMENT_UNUSED, the
identified attachment defines a fragment shading rate attachment for that
subpass.
If any element of pResolveAttachments is an image specified with an
VkExternalFormatANDROID, values in the corresponding color attachment
will be resolved to the resolve attachment in the same manner as specified
for VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID.
If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
values in the color attachment will be loaded from the resolve attachment at
the start of rendering, and may also be reloaded any time after a resolve
occurs or the resolve attachment is written to; if this occurs it must
happen-before any writes to the color attachment are performed which
happen-after the resolve that triggers this.
If any color component in the external format is subsampled, values will be
read from the nearest sample in the image when they are loaded.
If the color attachment is also used as an input attachment, the same
behavior applies.
Setting the color attachment to VK_ATTACHMENT_UNUSED when an external
resolve attachment is used and the
nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE
will not result in color attachment writes to be discarded for that
attachment.
When nullColorAttachmentWithExternalFormatResolve is VK_TRUE, the
color output from the subpass can still be read via an input attachment; but
the application cannot bind an image view for the color attachment as there
is no such image view bound.
Instead to access the data as an input attachment applications can use the
resolve attachment in its place - using the resolve attachment image for the
descriptor, and setting the corresponding element of pInputAttachments
to the index of the resolve attachment.
Loads or input attachment reads from the resolve attachment are performed as if using a VkSamplerYcbcrConversionCreateInfo with the following parameters:
VkSamplerYcbcrConversionCreateInfo createInfo = {
.sType = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO,
.pNext = NULL,
.format = VK_FORMAT_UNDEFINED,
.ycbcrModel = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
.ycbcrRange = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
.components = {
.r = VK_COMPONENT_SWIZZLE_B
.g = VK_COMPONENT_SWIZZLE_R
.b = VK_COMPONENT_SWIZZLE_G
.a = VK_COMPONENT_SWIZZLE_IDENTITY},
.xChromaOffset = properties.chromaOffsetX,
.yChromaOffset = properties.chromaOffsetY,
.chromaFilter = VK_FILTER_NEAREST,
.forceExplicitReconstruction = ... };where properties is equal to
VkPhysicalDeviceExternalFormatResolvePropertiesANDROID returned by the
device and forceExplicitReconstruction is effectively ignored as the
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY model is used.
The applied swizzle is the same effective swizzle that would be applied by
the VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY model, but no
range expansion is applied.
The VkSubpassDescriptionDepthStencilResolve structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescriptionDepthStencilResolve {
VkStructureType sType;
const void* pNext;
VkResolveModeFlagBits depthResolveMode;
VkResolveModeFlagBits stencilResolveMode;
const VkAttachmentReference2* pDepthStencilResolveAttachment;
} VkSubpassDescriptionDepthStencilResolve;or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkSubpassDescriptionDepthStencilResolve VkSubpassDescriptionDepthStencilResolveKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthResolveModeis a VkResolveModeFlagBits value describing the depth resolve mode. -
stencilResolveModeis a VkResolveModeFlagBits value describing the stencil resolve mode. -
pDepthStencilResolveAttachmentisNULLor a pointer to a VkAttachmentReference2 structure defining the depth/stencil resolve attachment for this subpass and its layout.
If the pNext chain of VkSubpassDescription2 includes a
VkSubpassDescriptionDepthStencilResolve structure, then that structure
describes multisample resolve operations
for the depth/stencil attachment in a subpass.
If this structure is not included in the pNext chain of
VkSubpassDescription2, or if it is and either
pDepthStencilResolveAttachment is NULL or its attachment index is
VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil resolve
attachment will be used in the subpass.
The VkFragmentShadingRateAttachmentInfoKHR structure is defined as:
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkFragmentShadingRateAttachmentInfoKHR {
VkStructureType sType;
const void* pNext;
const VkAttachmentReference2* pFragmentShadingRateAttachment;
VkExtent2D shadingRateAttachmentTexelSize;
} VkFragmentShadingRateAttachmentInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pFragmentShadingRateAttachmentisNULLor a pointer to a VkAttachmentReference2 structure defining the fragment shading rate attachment for this subpass. -
shadingRateAttachmentTexelSizespecifies the size of the portion of the framebuffer corresponding to each texel inpFragmentShadingRateAttachment.
If no shading rate attachment is specified, or if this structure is not specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment.
If the pNext chain of VkSubpassDescription2
or VkRenderingInfo
includes a VkMultisampledRenderToSingleSampledInfoEXT structure, then
that structure describes how multisampled rendering is performed on single
sampled attachments in that subpass.
The VkMultisampledRenderToSingleSampledInfoEXT structure is defined
as:
// Provided by VK_EXT_multisampled_render_to_single_sampled
typedef struct VkMultisampledRenderToSingleSampledInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 multisampledRenderToSingleSampledEnable;
VkSampleCountFlagBits rasterizationSamples;
} VkMultisampledRenderToSingleSampledInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
multisampledRenderToSingleSampledEnablecontrols whether multisampled rendering to single-sampled attachments is performed as described below. -
rasterizationSamplesis a VkSampleCountFlagBits specifying the number of samples used in rasterization.
If the pNext chain of VkSubpassDescription2
or VkRenderingInfo
includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose
multisampledRenderToSingleSampledEnable field is VK_TRUE, the
graphics pipelines must have
VkGraphicsPipelineCreateInfo::rasterizationSamples equal to
VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples,
and the subpass attachments can have a sample count of
VK_SAMPLE_COUNT_1_BIT.
For attachments with a sample count of VK_SAMPLE_COUNT_1_BIT,
multisampled rendering is performed to an intermediate multisampled image
with
VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples
samples, implicitly allocated by the implementation for the duration of the
subpass.
For such attachments:
-
If
loadOpequals toVK_ATTACHMENT_LOAD_OP_LOAD, samples of the implicit image are initialized by replicating the value from the corresponding pixel in the attachment. -
If
storeOporstencilStoreOpis equal toVK_ATTACHMENT_STORE_OP_STORE, the implicit image is implicitly resolved prior to storage in the attachment.
Memory constraints due to high primitive counts may result in an implicit
split of the subpass.
This is the equivalent of partial rasterization of geometry in a render pass
that ends in storeOp and stencilStoreOp equal to
VK_ATTACHMENT_STORE_OP_STORE, followed by another render pass with
loadOp and stencilLoadOp equal to
VK_ATTACHMENT_LOAD_OP_LOAD with appropriate barriers in between.
When VkMultisampledRenderToSingleSampledInfoEXT is used, the
implementation is allowed to resolve attachments with a sample count of
VK_SAMPLE_COUNT_1_BIT and lose multisampled data on such splits.
The implementation may similarly split the render pass at subpass
boundaries even if they use the same value for
VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples.
The VkAttachmentReference2 structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReference2 {
VkStructureType sType;
const void* pNext;
uint32_t attachment;
VkImageLayout layout;
VkImageAspectFlags aspectMask;
} VkAttachmentReference2;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentReference2 VkAttachmentReference2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentis either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo2::pAttachments, orVK_ATTACHMENT_UNUSEDto signify that this attachment is not used. -
layoutis a VkImageLayout value specifying the layout the attachment uses during the subpass. -
aspectMaskis a mask of which aspect(s) can be accessed within the specified subpass as an input attachment.
Parameters defined by this structure with the same name as those in VkAttachmentReference have the identical effect to those parameters.
aspectMask is ignored when this structure is used to describe anything
other than an input attachment reference.
If the separateDepthStencilLayouts feature is enabled, and attachment
has a depth/stencil format, layout can be set to a layout that only
specifies the layout of the depth aspect.
If layout only specifies the layout of the depth aspect of the
attachment, the layout of the stencil aspect is specified by the
stencilLayout member of a VkAttachmentReferenceStencilLayout
structure included in the pNext chain.
Otherwise, layout describes the layout for all relevant image aspects.
The VkAttachmentReferenceStencilLayout structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReferenceStencilLayout {
VkStructureType sType;
void* pNext;
VkImageLayout stencilLayout;
} VkAttachmentReferenceStencilLayout;or the equivalent
// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentReferenceStencilLayout VkAttachmentReferenceStencilLayoutKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilLayoutis a VkImageLayout value specifying the layout the stencil aspect of the attachment uses during the subpass.
The VkSubpassDependency2 structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSubpassDependency2 {
VkStructureType sType;
const void* pNext;
uint32_t srcSubpass;
uint32_t dstSubpass;
VkPipelineStageFlags srcStageMask;
VkPipelineStageFlags dstStageMask;
VkAccessFlags srcAccessMask;
VkAccessFlags dstAccessMask;
VkDependencyFlags dependencyFlags;
int32_t viewOffset;
} VkSubpassDependency2;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDependency2 VkSubpassDependency2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubpassis the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
dstSubpassis the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlagsis a bitmask of VkDependencyFlagBits. -
viewOffsetcontrols which views in the source subpass the views in the destination subpass depend on.
Parameters defined by this structure with the same name as those in VkSubpassDependency have the identical effect to those parameters.
viewOffset has the same effect for the described subpass dependency as
VkRenderPassMultiviewCreateInfo::pViewOffsets has on each
corresponding subpass dependency.
If a VkMemoryBarrier2 is included in the pNext chain,
srcStageMask, dstStageMask, srcAccessMask, and
dstAccessMask parameters are ignored.
The synchronization and access scopes instead are defined by the parameters
of VkMemoryBarrier2.
To destroy a render pass, call:
// Provided by VK_VERSION_1_0
void vkDestroyRenderPass(
VkDevice device,
VkRenderPass renderPass,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the render pass. -
renderPassis the handle of the render pass to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
8.3. Render Pass Compatibility
Framebuffers and graphics pipelines are created based on a specific render pass object. They must only be used with that render pass object, or one compatible with it.
Two attachment references are compatible if they have matching format and
sample count, or are both VK_ATTACHMENT_UNUSED or the pointer that
would contain the reference is NULL.
Two arrays of attachment references are compatible if all corresponding
pairs of attachments are compatible.
If the arrays are of different lengths, attachment references not present in
the smaller array are treated as VK_ATTACHMENT_UNUSED.
Two render passes are compatible if their corresponding color, input, resolve, and depth/stencil attachment references are compatible and if they are otherwise identical except for:
-
Initial and final image layout in attachment descriptions
-
Load and store operations in attachment descriptions
-
Image layout in attachment references
As an additional special case, if two render passes have a single subpass, the resolve attachment reference and depth/stencil resolve mode compatibility requirements are ignored.
A framebuffer is compatible with a render pass if it was created using the same render pass or a compatible render pass.
8.4. Framebuffers
Render passes operate in conjunction with framebuffers. Framebuffers represent a collection of specific memory attachments that a render pass instance uses.
Framebuffers are represented by VkFramebuffer handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFramebuffer)To create a framebuffer, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateFramebuffer(
VkDevice device,
const VkFramebufferCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkFramebuffer* pFramebuffer);-
deviceis the logical device that creates the framebuffer. -
pCreateInfois a pointer to a VkFramebufferCreateInfo structure describing additional information about framebuffer creation. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFramebufferis a pointer to a VkFramebuffer handle in which the resulting framebuffer object is returned.
The VkFramebufferCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkFramebufferCreateInfo {
VkStructureType sType;
const void* pNext;
VkFramebufferCreateFlags flags;
VkRenderPass renderPass;
uint32_t attachmentCount;
const VkImageView* pAttachments;
uint32_t width;
uint32_t height;
uint32_t layers;
} VkFramebufferCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkFramebufferCreateFlagBits -
renderPassis a render pass defining what render passes the framebuffer will be compatible with. See Render Pass Compatibility for details. -
attachmentCountis the number of attachments. -
pAttachmentsis a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. IfflagsincludesVK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this parameter is ignored. -
width,heightandlayersdefine the dimensions of the framebuffer. If the render pass uses multiview, thenlayersmust be one and each attachment requires a number of layers that is greater than the maximum bit index set in the view mask in the subpasses in which it is used.
It is legal for a subpass to use no color or depth/stencil attachments,
either because it has no attachment references or because all of them are
VK_ATTACHMENT_UNUSED.
This kind of subpass can use shader side effects such as image stores and
atomics to produce an output.
In this case, the subpass continues to use the width, height,
and layers of the framebuffer to define the dimensions of the
rendering area, and the rasterizationSamples from each pipeline’s
VkPipelineMultisampleStateCreateInfo to define the number of samples
used in rasterization; however, if
VkPhysicalDeviceFeatures::variableMultisampleRate is
VK_FALSE, then all pipelines to be bound with the subpass must have
the same value for
VkPipelineMultisampleStateCreateInfo::rasterizationSamples.
In all such cases, rasterizationSamples must be a valid
VkSampleCountFlagBits value that is set in
VkPhysicalDeviceLimits::framebufferNoAttachmentsSampleCounts.
The VkFramebufferAttachmentsCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentsCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t attachmentImageInfoCount;
const VkFramebufferAttachmentImageInfo* pAttachmentImageInfos;
} VkFramebufferAttachmentsCreateInfo;or the equivalent
// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentsCreateInfo VkFramebufferAttachmentsCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentImageInfoCountis the number of attachments being described. -
pAttachmentImageInfosis a pointer to an array of VkFramebufferAttachmentImageInfo structures, each structure describing a number of parameters of the corresponding attachment in a render pass instance.
The VkFramebufferAttachmentImageInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentImageInfo {
VkStructureType sType;
const void* pNext;
VkImageCreateFlags flags;
VkImageUsageFlags usage;
uint32_t width;
uint32_t height;
uint32_t layerCount;
uint32_t viewFormatCount;
const VkFormat* pViewFormats;
} VkFramebufferAttachmentImageInfo;or the equivalent
// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentImageInfo VkFramebufferAttachmentImageInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCreateFlagBits, matching the value of VkImageCreateInfo::flagsused to create an image that will be used with this framebuffer. -
usageis a bitmask of VkImageUsageFlagBits, matching the value of VkImageCreateInfo::usageused to create an image used with this framebuffer. -
widthis the width of the image view used for rendering. -
heightis the height of the image view used for rendering. -
layerCountis the number of array layers of the image view used for rendering. -
viewFormatCountis the number of entries in thepViewFormatsarray, matching the value of VkImageFormatListCreateInfo::viewFormatCountused to create an image used with this framebuffer. -
pViewFormatsis a pointer to an array of VkFormat values specifying all of the formats which can be used when creating views of the image, matching the value of VkImageFormatListCreateInfo::pViewFormatsused to create an image used with this framebuffer.
Images that can be used with the framebuffer when beginning a render pass, as specified by VkRenderPassAttachmentBeginInfo, must be created with parameters that are identical to those specified here.
Bits which can be set in VkFramebufferCreateInfo::flags,
specifying options for framebuffers, are:
// Provided by VK_VERSION_1_0
typedef enum VkFramebufferCreateFlagBits {
// Provided by VK_VERSION_1_2
VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT = 0x00000001,
// Provided by VK_KHR_imageless_framebuffer
VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR = VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT,
} VkFramebufferCreateFlagBits;-
VK_FRAMEBUFFER_CREATE_IMAGELESS_BITspecifies that image views are not specified, and only attachment compatibility information will be provided via a VkFramebufferAttachmentImageInfo structure.
// Provided by VK_VERSION_1_0
typedef VkFlags VkFramebufferCreateFlags;VkFramebufferCreateFlags is a bitmask type for setting a mask of zero
or more VkFramebufferCreateFlagBits.
To destroy a framebuffer, call:
// Provided by VK_VERSION_1_0
void vkDestroyFramebuffer(
VkDevice device,
VkFramebuffer framebuffer,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the framebuffer. -
framebufferis the handle of the framebuffer to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
8.5. Render Pass Load Operations
Render pass load operations define the initial values of an attachment during a render pass instance.
Load operations for attachments with a depth/stencil format execute in the
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage.
Load operations for attachments with a color format execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
The load operation for each sample in an attachment happens-before any
recorded command which accesses the sample in that render pass instance via
that attachment or an alias.
|
Note
Because load operations always happen first, external synchronization with
attachment access only needs to synchronize the load operations with
previous commands; not the operations within the render pass instance.
This does not apply when using |
Load operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a load operation (as defined by its access
masks) to a given attachment may read and write back any memory locations
within the image subresource bound for that attachment.
For depth/stencil images, writes to one aspect may also result in
read-modify-write operations for the other aspect.
If the subresource is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout,
implementations must not access pixels outside of the render area.
|
Note
As entire subresources could be accessed by load operations, applications cannot safely access values outside of the render area during a render pass instance when a load operation that modifies values is used. |
Load operations that can be used for a render pass are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentLoadOp {
VK_ATTACHMENT_LOAD_OP_LOAD = 0,
VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
// Provided by VK_KHR_load_store_op_none
VK_ATTACHMENT_LOAD_OP_NONE_KHR = 1000400000,
// Provided by VK_EXT_load_store_op_none
VK_ATTACHMENT_LOAD_OP_NONE_EXT = VK_ATTACHMENT_LOAD_OP_NONE_KHR,
} VkAttachmentLoadOp;-
VK_ATTACHMENT_LOAD_OP_LOADspecifies that the previous contents of the image within the render area will be preserved as the initial values. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_READ_BIT. -
VK_ATTACHMENT_LOAD_OP_CLEARspecifies that the contents within the render area will be cleared to a uniform value, which is specified when a render pass instance is begun. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -
VK_ATTACHMENT_LOAD_OP_DONT_CAREspecifies that the previous contents within the area need not be preserved; the contents of the attachment will be undefined inside the render area. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -
VK_ATTACHMENT_LOAD_OP_NONE_KHRspecifies that the previous contents of the image will be undefined inside the render pass. No access type is used as the image is not accessed.
During a render pass instance, input and color attachments with color
formats that have a component size of 8, 16, or 32 bits must be represented
in the attachment’s format throughout the instance.
Attachments with other floating- or fixed-point color formats, or with depth
components may be represented in a format with a precision higher than the
attachment format, but must be represented with the same range.
When such a component is loaded via the loadOp, it will be converted
into an implementation-dependent format used by the render pass.
Such components must be converted from the render pass format, to the
format of the attachment, before they are resolved or stored at the end of a
render pass instance via storeOp.
Conversions occur as described in Numeric
Representation and Computation and Fixed-Point
Data Conversions.
8.6. Render Pass Store Operations
Render pass store operations define how values written to an attachment during a render pass instance are stored to memory.
Store operations for attachments with a depth/stencil format execute in the
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage.
Store operations for attachments with a color format execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
The store operation for each sample in an attachment happens-after any
recorded command which accesses the sample via that attachment or an alias.
|
Note
Because store operations always happen after other accesses in a render pass
instance, external synchronization with attachment access in an earlier
render pass only needs to synchronize with the store operations; not the
operations within the render pass instance.
This does not apply when using |
Store operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a store operation (as defined by its access
masks) to a given attachment may read and write back any memory locations
within the image subresource bound for that attachment.
For depth/stencil images writes to one aspect may also result in
read-modify-write operations for the other aspect.
If the subresource is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout,
implementations must not access pixels outside of the render area.
|
Note
As entire subresources could be accessed by store operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a store operation that modifies values is used. |
Possible values of VkAttachmentDescription::storeOp and
stencilStoreOp, specifying how the contents of the attachment are
treated, are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentStoreOp {
VK_ATTACHMENT_STORE_OP_STORE = 0,
VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
// Provided by VK_VERSION_1_3
VK_ATTACHMENT_STORE_OP_NONE = 1000301000,
// Provided by VK_KHR_dynamic_rendering, VK_KHR_load_store_op_none
VK_ATTACHMENT_STORE_OP_NONE_KHR = VK_ATTACHMENT_STORE_OP_NONE,
// Provided by VK_QCOM_render_pass_store_ops
VK_ATTACHMENT_STORE_OP_NONE_QCOM = VK_ATTACHMENT_STORE_OP_NONE,
// Provided by VK_EXT_load_store_op_none
VK_ATTACHMENT_STORE_OP_NONE_EXT = VK_ATTACHMENT_STORE_OP_NONE,
} VkAttachmentStoreOp;-
VK_ATTACHMENT_STORE_OP_STOREspecifies the contents generated during the render pass and within the render area are written to memory. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -
VK_ATTACHMENT_STORE_OP_DONT_CAREspecifies the contents within the render area are not needed after rendering, and may be discarded; the contents of the attachment will be undefined inside the render area. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -
VK_ATTACHMENT_STORE_OP_NONEspecifies the contents within the render area are not accessed by the store operation as long as no values are written to the attachment during the render pass. If values are written during the render pass, this behaves identically toVK_ATTACHMENT_STORE_OP_DONT_CAREand with matching access semantics.
|
Note
|
8.7. Render Pass Multisample Resolve Operations
Render pass multisample resolve operations combine sample values from a single pixel in a multisample attachment and store the result to the corresponding pixel in a single sample attachment.
Multisample resolve operations for attachments execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
A final resolve operation for all pixels in the render area happens-after
any recorded command which writes a pixel via the multisample attachment to
be resolved or an explicit alias of it in the subpass that it is specified.
Any single sample attachment specified for use in a multisample resolve
operation may have its contents modified at any point once rendering begins
for the render pass instance.
Reads from the multisample attachment can be synchronized with
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.
Access to the single sample attachment can be synchronized with
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT and
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
These pipeline stage and access types are used whether the attachments are
color or depth/stencil attachments.
When using render pass objects, a subpass dependency specified with the above pipeline stages and access flags will ensure synchronization with multisample resolve operations for any attachments that were last accessed by that subpass. This allows later subpasses to read resolved values as input attachments.
Resolve operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a resolve operation (as defined by its
access masks) to a given attachment may read and write back any memory
locations within the image subresource bound for that attachment.
For depth/stencil images writes to one aspect may also result in
read-modify-write operations for the other aspect.
If the subresource is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout,
implementations must not access pixels outside of the render area.
|
Note
As entire subresources could be accessed by multisample resolve operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a multisample resolve operation is performed. |
Multisample values in a multisample attachment are combined according to the resolve mode used:
// Provided by VK_VERSION_1_2
typedef enum VkResolveModeFlagBits {
VK_RESOLVE_MODE_NONE = 0,
VK_RESOLVE_MODE_SAMPLE_ZERO_BIT = 0x00000001,
VK_RESOLVE_MODE_AVERAGE_BIT = 0x00000002,
VK_RESOLVE_MODE_MIN_BIT = 0x00000004,
VK_RESOLVE_MODE_MAX_BIT = 0x00000008,
// Provided by VK_ANDROID_external_format_resolve with VK_KHR_dynamic_rendering or VK_VERSION_1_3
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID = 0x00000010,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_NONE_KHR = VK_RESOLVE_MODE_NONE,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR = VK_RESOLVE_MODE_SAMPLE_ZERO_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_AVERAGE_BIT_KHR = VK_RESOLVE_MODE_AVERAGE_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_MIN_BIT_KHR = VK_RESOLVE_MODE_MIN_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_MAX_BIT_KHR = VK_RESOLVE_MODE_MAX_BIT,
} VkResolveModeFlagBits;or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlagBits VkResolveModeFlagBitsKHR;-
VK_RESOLVE_MODE_NONEindicates that no resolve operation is done. -
VK_RESOLVE_MODE_SAMPLE_ZERO_BITindicates that result of the resolve operation is equal to the value of sample 0. -
VK_RESOLVE_MODE_AVERAGE_BITindicates that result of the resolve operation is the average of the sample values. -
VK_RESOLVE_MODE_MIN_BITindicates that result of the resolve operation is the minimum of the sample values. -
VK_RESOLVE_MODE_MAX_BITindicates that result of the resolve operation is the maximum of the sample values. -
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROIDindicates that rather than a multisample resolve, a single sampled color attachment will be downsampled into a Y′CBCR format image specified by an external Android format. Unlike other resolve modes, implementations can resolve multiple times during rendering, or even bypass writing to the color attachment altogether, as long as the final value is resolved to the resolve attachment. Values in the G, B, and R channels of the color attachment will be written to the Y, CB, and CR channels of the external format image, respectively. Chroma values are calculated as if sampling with a linear filter from the color attachment at full rate, at the location the chroma values sit according to VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::chromaOffsetX, VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::chromaOffsetY, and the chroma sample rate of the resolved image.
If no resolve mode is otherwise specified, VK_RESOLVE_MODE_AVERAGE_BIT
is used.
|
Note
No range compression or Y′CBCR model conversion is performed by
|
// Provided by VK_VERSION_1_2
typedef VkFlags VkResolveModeFlags;or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlags VkResolveModeFlagsKHR;VkResolveModeFlags is a bitmask type for setting a mask of zero or
more VkResolveModeFlagBits.
8.8. Render Pass Commands
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:
// Provided by VK_VERSION_1_0
void vkCmdBeginRenderPass(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
VkSubpassContents contents);-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
contentsis a VkSubpassContents value specifying how the commands in the first subpass will be provided.
After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass.
Alternatively to begin a render pass, call:
// Provided by VK_VERSION_1_2
void vkCmdBeginRenderPass2(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
const VkSubpassBeginInfo* pSubpassBeginInfo);or the equivalent command
// Provided by VK_KHR_create_renderpass2
void vkCmdBeginRenderPass2KHR(
VkCommandBuffer commandBuffer,
const VkRenderPassBeginInfo* pRenderPassBegin,
const VkSubpassBeginInfo* pSubpassBeginInfo);-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
pSubpassBeginInfois a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering.
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:
// Provided by VK_VERSION_1_0
typedef struct VkRenderPassBeginInfo {
VkStructureType sType;
const void* pNext;
VkRenderPass renderPass;
VkFramebuffer framebuffer;
VkRect2D renderArea;
uint32_t clearValueCount;
const VkClearValue* pClearValues;
} VkRenderPassBeginInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassis the render pass to begin an instance of. -
framebufferis the framebuffer containing the attachments that are used with the render pass. -
renderAreais the render area that is affected by the render pass instance, and is described in more detail below. -
clearValueCountis the number of elements inpClearValues. -
pClearValuesis a pointer to an array ofclearValueCountVkClearValue structures containing clear values for each attachment, if the attachment uses aloadOpvalue ofVK_ATTACHMENT_LOAD_OP_CLEARor if the attachment has a depth/stencil format and uses astencilLoadOpvalue ofVK_ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements ofpClearValuesare 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.
The render area, after any transform specified by
VkRenderPassTransformBeginInfoQCOM::transform is applied, must
be contained within the framebuffer dimensions.
If render pass transform is
enabled, then renderArea must equal the framebuffer pre-transformed
dimensions.
After renderArea has been transformed by
VkRenderPassTransformBeginInfoQCOM::transform, the resulting
render area must be equal to the framebuffer dimensions.
If multiview is enabled in renderPass, and
multiviewPerViewRenderAreas feature is enabled, and there is an
instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM
included in the pNext chain with perViewRenderAreaCount not
equal to 0, then the elements of
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas
override renderArea and define a render area for each view.
In this case, renderArea must be set to an area at least as large as
the union of all the per-view render areas.
If the subpassShading feature is enabled,
then renderArea must equal 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. |
The image layout of the depth aspect of a depth/stencil attachment referring
to an image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
on the last sample locations used to render to the image subresource, thus
preserving the contents of such depth/stencil attachments across subpass
boundaries requires the application to specify these sample locations
whenever a layout transition of the attachment may occur.
This information can be provided by adding a
VkRenderPassSampleLocationsBeginInfoEXT structure to the pNext
chain of VkRenderPassBeginInfo.
The VkRenderPassSampleLocationsBeginInfoEXT structure is defined as:
// Provided by VK_EXT_sample_locations
typedef struct VkRenderPassSampleLocationsBeginInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t attachmentInitialSampleLocationsCount;
const VkAttachmentSampleLocationsEXT* pAttachmentInitialSampleLocations;
uint32_t postSubpassSampleLocationsCount;
const VkSubpassSampleLocationsEXT* pPostSubpassSampleLocations;
} VkRenderPassSampleLocationsBeginInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentInitialSampleLocationsCountis the number of elements in thepAttachmentInitialSampleLocationsarray. -
pAttachmentInitialSampleLocationsis a pointer to an array ofattachmentInitialSampleLocationsCountVkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element ofpAttachmentInitialSampleLocationscan specify the sample location state to use in the automatic layout transition performed to transition a depth/stencil attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it. -
postSubpassSampleLocationsCountis the number of elements in thepPostSubpassSampleLocationsarray. -
pPostSubpassSampleLocationsis a pointer to an array ofpostSubpassSampleLocationsCountVkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element ofpPostSubpassSampleLocationscan specify the sample location state to use in the automatic layout transition performed to transition the depth/stencil attachment used by the specified subpass to the image layout specified in a dependent subpass or to the final layout of the attachment in case the specified subpass is the last subpass using that attachment. In addition, if VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocationsisVK_FALSE, each element ofpPostSubpassSampleLocationsmust specify the sample location state that matches the sample locations used by all pipelines that will be bound to a command buffer during the specified subpass. IfvariableSampleLocationsisVK_TRUE, the sample locations used for rasterization do not depend onpPostSubpassSampleLocations.
The VkAttachmentSampleLocationsEXT structure is defined as:
// Provided by VK_EXT_sample_locations
typedef struct VkAttachmentSampleLocationsEXT {
uint32_t attachmentIndex;
VkSampleLocationsInfoEXT sampleLocationsInfo;
} VkAttachmentSampleLocationsEXT;-
attachmentIndexis the index of the attachment for which the sample locations state is provided. -
sampleLocationsInfois the sample locations state to use for the layout transition of the given attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it.
If the image referenced by the framebuffer attachment at index
attachmentIndex was not created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the
values specified in sampleLocationsInfo are ignored.
The VkSubpassSampleLocationsEXT structure is defined as:
// Provided by VK_EXT_sample_locations
typedef struct VkSubpassSampleLocationsEXT {
uint32_t subpassIndex;
VkSampleLocationsInfoEXT sampleLocationsInfo;
} VkSubpassSampleLocationsEXT;-
subpassIndexis the index of the subpass for which the sample locations state is provided. -
sampleLocationsInfois the sample locations state to use for the layout transition of the depth/stencil attachment away from the image layout the attachment is used with in the subpass specified insubpassIndex.
If the image referenced by the depth/stencil attachment used in the subpass
identified by subpassIndex was not created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the
subpass does not use a depth/stencil attachment, and
VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations
is VK_TRUE then the values specified in sampleLocationsInfo are
ignored.
To begin a render pass instance with render pass transform enabled, add the
VkRenderPassTransformBeginInfoQCOM to the pNext chain of
VkRenderPassBeginInfo structure passed to the
vkCmdBeginRenderPass command specifying the render pass transform.
The VkRenderPassTransformBeginInfoQCOM structure is defined as:
// Provided by VK_QCOM_render_pass_transform
typedef struct VkRenderPassTransformBeginInfoQCOM {
VkStructureType sType;
void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkRenderPassTransformBeginInfoQCOM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization.
The VkSubpassBeginInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSubpassBeginInfo {
VkStructureType sType;
const void* pNext;
VkSubpassContents contents;
} VkSubpassBeginInfo;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkSubpassBeginInfo VkSubpassBeginInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
contentsis a VkSubpassContents value specifying how the commands in the next subpass will be provided.
Possible values of vkCmdBeginRenderPass::contents, specifying
how the commands in the first subpass will be provided, are:
// Provided by VK_VERSION_1_0
typedef enum VkSubpassContents {
VK_SUBPASS_CONTENTS_INLINE = 0,
VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS = 1,
// Provided by VK_EXT_nested_command_buffer
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT = 1000451000,
} VkSubpassContents;-
VK_SUBPASS_CONTENTS_INLINEspecifies that 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. -
VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERSspecifies that the contents are recorded in secondary command buffers that will be called from the primary command buffer, and vkCmdExecuteCommands is the only valid command in the command buffer until vkCmdNextSubpass or vkCmdEndRenderPass. -
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXTspecifies that the contents of the subpass can be recorded both inline and in secondary command buffers executed from this command buffer with vkCmdExecuteCommands.
If the pNext chain of VkRenderPassBeginInfo
or VkRenderingInfo
includes a VkDeviceGroupRenderPassBeginInfo structure, then that
structure includes a device mask and set of render areas for the render pass
instance.
The VkDeviceGroupRenderPassBeginInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupRenderPassBeginInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceMask;
uint32_t deviceRenderAreaCount;
const VkRect2D* pDeviceRenderAreas;
} VkDeviceGroupRenderPassBeginInfo;or the equivalent
// Provided by VK_KHR_device_group
typedef VkDeviceGroupRenderPassBeginInfo VkDeviceGroupRenderPassBeginInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceMaskis the device mask for the render pass instance. -
deviceRenderAreaCountis the number of elements in thepDeviceRenderAreasarray. -
pDeviceRenderAreasis a pointer to an array of VkRect2D structures defining the render area for each physical device.
The deviceMask serves several purposes.
It is an upper bound on the set of physical devices that can be used during
the render pass instance, and the initial device mask when the render pass
instance begins.
In addition, commands transitioning to the next subpass in a render pass
instance and commands ending the render pass instance, and, accordingly
render pass load,
store, and multisample resolve operations and subpass dependencies corresponding to
the render pass instance, are executed on the physical devices included in
the device mask provided here.
If deviceRenderAreaCount is not zero, then the elements of
pDeviceRenderAreas override the value of
VkRenderPassBeginInfo::renderArea, and provide a render area
specific to each physical device.
These render areas serve the same purpose as
VkRenderPassBeginInfo::renderArea, including controlling the
region of attachments that are cleared by VK_ATTACHMENT_LOAD_OP_CLEAR
and that are resolved into resolve attachments.
If this structure is not present, the render pass instance’s device mask is
the value of VkDeviceGroupCommandBufferBeginInfo::deviceMask.
If this structure is not present or if deviceRenderAreaCount is zero,
VkRenderPassBeginInfo::renderArea is used for all physical
devices.
The VkRenderPassAttachmentBeginInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkRenderPassAttachmentBeginInfo {
VkStructureType sType;
const void* pNext;
uint32_t attachmentCount;
const VkImageView* pAttachments;
} VkRenderPassAttachmentBeginInfo;or the equivalent
// Provided by VK_KHR_imageless_framebuffer
typedef VkRenderPassAttachmentBeginInfo VkRenderPassAttachmentBeginInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentCountis the number of attachments. -
pAttachmentsis a pointer to an array ofVkImageViewhandles, each of which will be used as the corresponding attachment in the render pass instance.
If a render pass instance enables multiview and if the
multiviewPerViewRenderAreas
feature is enabled, the
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure can be
included in the pNext chain of VkRenderPassBeginInfo
or VkRenderingInfo
The VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure is
defined as:
// Provided by VK_QCOM_multiview_per_view_render_areas
typedef struct VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM {
VkStructureType sType;
const void* pNext;
uint32_t perViewRenderAreaCount;
const VkRect2D* pPerViewRenderAreas;
} VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perViewRenderAreaCountis the number of elements in thepPerViewRenderAreasarray. -
pPerViewRenderAreasis a pointer to an array of VkRect2D structures defining the render area for each view.
If perViewRenderAreaCount is not zero, then the elements of
pPerViewRenderAreas override the value of
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
and define per-view render areas for the individual views of a multiview
render pass.
The render area for the view with view index i is specified by
pPerViewRenderAreas[i].
The per-view render areas define per-view regions of attachments that are
loaded, stored, and resolved according to the loadOp, storeOp,
and resolveMode values of the render pass instance.
When per-view render areas are defined, the value of
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
must be set to a render area that includes the union of all per-view render
areas, may be used by the implementation for optimizations, but does not
affect loads, stores, or resolves.
If this structure is present and if perViewRenderAreaCount is not
zero, then perViewRenderAreaCount must be at least one greater than
the most significant bit set in any element of
VkRenderPassMultiviewCreateInfo::pViewMasks.
or VkRenderingInfo::viewMask
If this structure is not present or if perViewRenderAreaCount is zero,
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
is used for all views.
To query the render area granularity, call:
// Provided by VK_VERSION_1_0
void vkGetRenderAreaGranularity(
VkDevice device,
VkRenderPass renderPass,
VkExtent2D* pGranularity);-
deviceis the logical device that owns the render pass. -
renderPassis a handle to a render pass. -
pGranularityis a pointer to a VkExtent2D structure in which the granularity is returned.
The conditions leading to an optimal renderArea are:
-
the
offset.xmember inrenderAreais a multiple of thewidthmember of the returned VkExtent2D (the horizontal granularity). -
the
offset.ymember inrenderAreais a multiple of theheightmember of the returned VkExtent2D (the vertical granularity). -
either the
extent.widthmember inrenderAreais a multiple of the horizontal granularity oroffset.x+extent.widthis equal to thewidthof theframebufferin the VkRenderPassBeginInfo. -
either the
extent.heightmember inrenderAreais a multiple of the vertical granularity oroffset.y+extent.heightis equal to theheightof theframebufferin the VkRenderPassBeginInfo.
Subpass dependencies are not affected by the render area, and apply to the entire image subresources attached to the framebuffer as specified in the description of automatic layout transitions. 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:
// Provided by VK_VERSION_1_0
void vkCmdNextSubpass(
VkCommandBuffer commandBuffer,
VkSubpassContents contents);-
commandBufferis the command buffer in which to record the command. -
contentsspecifies 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.
After transitioning to the next subpass, the application can record the commands for that subpass.
To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:
// Provided by VK_VERSION_1_2
void vkCmdNextSubpass2(
VkCommandBuffer commandBuffer,
const VkSubpassBeginInfo* pSubpassBeginInfo,
const VkSubpassEndInfo* pSubpassEndInfo);or the equivalent command
// Provided by VK_KHR_create_renderpass2
void vkCmdNextSubpass2KHR(
VkCommandBuffer commandBuffer,
const VkSubpassBeginInfo* pSubpassBeginInfo,
const VkSubpassEndInfo* pSubpassEndInfo);-
commandBufferis the command buffer in which to record the command. -
pSubpassBeginInfois a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering. -
pSubpassEndInfois a pointer to a VkSubpassEndInfo structure containing information about how the previous subpass will be ended.
vkCmdNextSubpass2 is semantically identical to vkCmdNextSubpass,
except that it is extensible, and that contents is provided as part of
an extensible structure instead of as a flat parameter.
To record a command to end a render pass instance after recording the commands for the last subpass, call:
// Provided by VK_VERSION_1_0
void vkCmdEndRenderPass(
VkCommandBuffer commandBuffer);-
commandBufferis 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.
To record a command to end a render pass instance after recording the commands for the last subpass, call:
// Provided by VK_VERSION_1_2
void vkCmdEndRenderPass2(
VkCommandBuffer commandBuffer,
const VkSubpassEndInfo* pSubpassEndInfo);or the equivalent command
// Provided by VK_KHR_create_renderpass2
void vkCmdEndRenderPass2KHR(
VkCommandBuffer commandBuffer,
const VkSubpassEndInfo* pSubpassEndInfo);-
commandBufferis the command buffer in which to end the current render pass instance. -
pSubpassEndInfois a pointer to a VkSubpassEndInfo structure containing information about how the last subpass will be ended.
vkCmdEndRenderPass2 is semantically identical to
vkCmdEndRenderPass, except that it is extensible.
The VkSubpassEndInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSubpassEndInfo {
VkStructureType sType;
const void* pNext;
} VkSubpassEndInfo;or the equivalent
// Provided by VK_KHR_create_renderpass2
typedef VkSubpassEndInfo VkSubpassEndInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkSubpassEndInfo::pNext chain includes a
VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure, then that
structure includes an array of fragment density map offsets per layer for
the render pass.
The VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure is defined
as:
// Provided by VK_QCOM_fragment_density_map_offset
typedef struct VkSubpassFragmentDensityMapOffsetEndInfoQCOM {
VkStructureType sType;
const void* pNext;
uint32_t fragmentDensityOffsetCount;
const VkOffset2D* pFragmentDensityOffsets;
} VkSubpassFragmentDensityMapOffsetEndInfoQCOM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityOffsetCountis the number of offsets being specified. -
pFragmentDensityOffsetsis a pointer to an array of VkOffset2D structs, each of which describes the offset per layer.
The array elements are given per layer as defined by
Fetch Density Value, where
index = layer.
Each (x,y) offset is in framebuffer pixels and shifts the fetch of the
fragment density map by that amount.
Offsets can be positive or negative.
Offset values specified for any subpass that is not the last subpass in the
render pass are ignored.
If the VkSubpassEndInfo::pNext chain for the last subpass of a
render pass does not include
VkSubpassFragmentDensityMapOffsetEndInfoQCOM, or if
fragmentDensityOffsetCount is zero, then the offset (0,0) is
used for Fetch Density Value.
8.9. Render Pass Creation Feedback
A VkRenderPassCreationControlEXT structure can be included in the
pNext chain of VkRenderPassCreateInfo2 or pNext chain of
VkSubpassDescription2.
The VkRenderPassCreationControlEXT structure is defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationControlEXT {
VkStructureType sType;
const void* pNext;
VkBool32 disallowMerging;
} VkRenderPassCreationControlEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
disallowMergingis a boolean value indicating whether subpass merging will be disabled.
If a VkRenderPassCreationControlEXT structure is included in the
pNext chain of VkRenderPassCreateInfo2 and its value of
disallowMerging is VK_TRUE, the implementation will disable
subpass merging for the entire render pass.
If a VkRenderPassCreationControlEXT structure is included in the
pNext chain of VkSubpassDescription2 and its value of
disallowMerging is VK_TRUE, the implementation will disable
merging the described subpass with previous subpasses in the render pass.
To obtain feedback about the creation of a render pass, include a
VkRenderPassCreationFeedbackCreateInfoEXT structure in the pNext
chain of VkRenderPassCreateInfo2.
The VkRenderPassCreationFeedbackCreateInfoEXT structure is defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkRenderPassCreationFeedbackInfoEXT* pRenderPassFeedback;
} VkRenderPassCreationFeedbackCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pRenderPassFeedbackis a pointer to a VkRenderPassCreationFeedbackInfoEXT structure in which feedback is returned.
The VkRenderPassCreationFeedbackInfoEXT structure is defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackInfoEXT {
uint32_t postMergeSubpassCount;
} VkRenderPassCreationFeedbackInfoEXT;-
postMergeSubpassCountis the subpass count after merge.
Feedback about the creation of a subpass can be obtained by including a
VkRenderPassSubpassFeedbackCreateInfoEXT structure in the pNext
chain of VkSubpassDescription2.
VkRenderPassSubpassFeedbackCreateInfoEXT structure is defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkRenderPassSubpassFeedbackInfoEXT* pSubpassFeedback;
} VkRenderPassSubpassFeedbackCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pSubpassFeedbackis a pointer to a VkRenderPassSubpassFeedbackInfoEXT structure in which feedback is returned.
The VkRenderPassSubpassFeedbackInfoEXT structure is defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackInfoEXT {
VkSubpassMergeStatusEXT subpassMergeStatus;
char description[VK_MAX_DESCRIPTION_SIZE];
uint32_t postMergeIndex;
} VkRenderPassSubpassFeedbackInfoEXT;-
subpassMergeStatusis aVkSubpassMergeStatusEXTvalue specifying information about whether the subpass is merged with previous subpass and the reason why it is not merged. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which provides additional details. -
postMergeIndexis the subpass index after the subpass merging.
Possible values of
VkRenderPassSubpassFeedbackInfoEXT:subpassMergeStatus are:
// Provided by VK_EXT_subpass_merge_feedback
typedef enum VkSubpassMergeStatusEXT {
VK_SUBPASS_MERGE_STATUS_MERGED_EXT = 0,
VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXT = 1,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXT = 2,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXT = 3,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXT = 4,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXT = 5,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXT = 6,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXT = 7,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXT = 8,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXT = 9,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXT = 10,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXT = 11,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXT = 12,
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXT = 13,
} VkSubpassMergeStatusEXT;-
VK_SUBPASS_MERGE_STATUS_MERGED_EXTspecifies the subpass is merged with a previous subpass. -
VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXTspecifies the subpass is disallowed to merge with previous subpass. If the render pass does not allow subpass merging, then all subpass statuses are set to this value. If a subpass description does not allow subpass merging, then only that subpass’s status is set to this value. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXTspecifies the subpass is not merged because it contains side effects. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXTspecifies the subpass is not merged because sample count is not compatible with previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXTspecifies the subpass is not merged because view masks do not match with previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXTspecifies the subpass is not merged because of attachments aliasing between them. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXTspecifies the subpass is not merged because subpass dependencies do not allow merging. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXTspecifies the subpass is not merged because input attachment is not a color attachment from previous subpass or the formats are incompatible. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXTspecifies the subpass is not merged because of too many attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXTspecifies the subpass is not merged because of insufficient memory. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXTspecifies the subpass is not merged because of too many depth/stencil attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXTspecifies the subpass is not merged because a resolve attachment is reused as an input attachment in a subsequent subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXTspecifies the subpass is not merged because the render pass has only one subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXTspecifies other reasons why subpass is not merged. It is also the recommended default value that should be reported when a subpass is not merged and when no other value is appropriate.
8.10. Common Render Pass Data Races (Informative)
Due to the complexity of how rendering is performed, there are several ways an application can accidentally introduce a data race, usually by doing something that may seem benign but actually cannot be supported. This section indicates a number of the more common cases as guidelines to help avoid them.
8.10.1. Sampling From a Read-only Attachment
Vulkan includes read-only layouts for depth/stencil images, that allow the images to be both read during a render pass for the purposes of depth/stencil tests, and read as a non-attachment.
However, because VK_ATTACHMENT_STORE_OP_STORE and
VK_ATTACHMENT_STORE_OP_DONT_CARE may perform write operations, even if
no recorded command writes to an attachment, reading from an image while
also using it as an attachment with these store operations can result in a
data race.
If the reads from the non-attachment are performed in a fragment shader
where the accessed samples match those covered by the fragment shader, no
data race will occur as store operations are guaranteed to operate after
fragment shader execution for the set of samples the fragment covers.
Notably, input attachments can also be used for this case.
Reading other samples or in any other shader stage can result in unexpected
behavior due to the potential for a data race, and validation errors should
be generated for doing so.
In practice, many applications have shipped reading samples outside of the
covered fragment without any observable issue, but there is no guarantee
that this will always work, and it is not advisable to rely on this in new
or re-worked code bases.
As VK_ATTACHMENT_STORE_OP_NONE is guaranteed to perform no writes,
applications wishing to read an image as both an attachment and a
non-attachment should make use of this store operation, coupled with a load
operation that also performs no writes.
8.10.2. Non-overlapping Access Between Resources
When relying on non-overlapping accesses between attachments and other resources, it is important to note that load and store operations have fairly wide alignment requirements - potentially affecting entire subresources and adjacent depth/stencil aspects. This makes it invalid to access a non-attachment subresource that is simultaneously being used as an attachment where either access performs a write operation.
The only exception to this is if a subresource is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT image layout, in
which case the overlap is defined to occur at a per-pixel granularity, and
applications can read data from pixels outside the render area without
introducing a data race.
8.10.3. Depth/Stencil and Input Attachments
When rendering to only the depth OR stencil aspect of an image, an input
attachment accessing the other aspect will
not cause a data race only under very specific conditions.
To avoid a data race, the aspect not being written must be in a read-only
layout, and writes to it must be disabled in the draw state.
For example, to read from stencil while writing depth, the attachment must
be in VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL (or
equivalent), and the stencil write mask must be set to 0.
Similarly to read from depth while writing stencil, the attachment must be
in VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL (or
equivalent), and depth write enable must be set to VK_FALSE.
8.10.4. Synchronization Options
There are several synchronization options available to synchronize between accesses to resources within a render pass. Some of the options are outlined below:
-
A VkSubpassDependency in a render pass object can synchronize attachment writes and multisample resolve operations from a prior subpass for subsequent input attachment reads.
-
A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent input attachment reads.
-
A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent non-attachment reads if the attachment is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTimage layout. -
If a subresource is used as a color and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT -
If a subresource is used as a depth and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT -
If a subresource is used as a stencil and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT -
If a subresource is used as two separate non-attachment resources, writes to a pixel or individual sample in a fragment shader can be synchronized with access to the same pixel or sample in another fragment shader by using one of the fragment interlock execution modes.