1700 lines
80 KiB
Plaintext
1700 lines
80 KiB
Plaintext
// Copyright (c) 2015-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[renderpass]]
|
|
= Render Pass
|
|
|
|
// refBegin VkRenderPass Opaque handle to a render pass object
|
|
|
|
A _render pass_ represents a collection of attachments, subpasses, and
|
|
dependencies between the subpasses, and describes how the attachments are
|
|
used over the course of the subpasses.
|
|
The use of a render pass in a command buffer is a _render pass instance_.
|
|
|
|
Render passes are represented by sname:VkRenderPass handles:
|
|
|
|
include::../api/handles/VkRenderPass.txt[]
|
|
|
|
// refEnd 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.
|
|
|
|
[[renderpass-subpass]]
|
|
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_, 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, or input attachment for that subpass (as determined by the
|
|
pname:pColorAttachments, pname:pDepthStencilAttachment,
|
|
pname:pResolveAttachments, and pname:pInputAttachments members of
|
|
slink: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.
|
|
|
|
[NOTE]
|
|
.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 <<synchronization-dependencies, 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 <<synchronization-submission-order, submission
|
|
order>> for commands recorded in the same subpass, and the
|
|
flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that
|
|
delimit the render pass - commands within other subpasses are not included.
|
|
This affects most other <<synchronization-implicit, 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 sname:VkFramebuffer objects.
|
|
Framebuffers are created with respect to a specific render pass that the
|
|
framebuffer is compatible with (see <<renderpass-compatibility,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 <<synchronization-pipeline-stages-order,
|
|
pipeline order>>.
|
|
However for a given (x,y,layer,sample) sample location, certain per-sample
|
|
operations are performed in <<primrast-order,rasterization order>>.
|
|
|
|
|
|
[[renderpass-creation]]
|
|
== Render Pass Creation
|
|
|
|
// refBegin vkCreateRenderPass Create a new render pass object
|
|
|
|
To create a render pass, call:
|
|
|
|
include::../api/protos/vkCreateRenderPass.txt[]
|
|
|
|
* pname:device is the logical device that creates the render pass.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
slink:VkRenderPassCreateInfo structure that describes the parameters of
|
|
the render pass.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pRenderPass points to a sname:VkRenderPass handle in which the
|
|
resulting render pass object is returned.
|
|
|
|
include::../validity/protos/vkCreateRenderPass.txt[]
|
|
|
|
// refBegin VkRenderPassCreateInfo Structure specifying parameters of a newly created render pass
|
|
|
|
The sname:VkRenderPassCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkRenderPassCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:attachmentCount is the number of attachments used by this render
|
|
pass, or zero indicating no attachments.
|
|
Attachments are referred to by zero-based indices in the range
|
|
[0,pname:attachmentCount).
|
|
* pname:pAttachments points to an array of pname:attachmentCount number of
|
|
slink:VkAttachmentDescription structures describing properties of the
|
|
attachments, or `NULL` if pname:attachmentCount is zero.
|
|
* pname:subpassCount is the number of subpasses to create for this render
|
|
pass.
|
|
Subpasses are referred to by zero-based indices in the range
|
|
[0,pname:subpassCount).
|
|
A render pass must: have at least one subpass.
|
|
* pname:pSubpasses points to an array of pname:subpassCount number of
|
|
slink:VkSubpassDescription structures describing properties of the
|
|
subpasses.
|
|
* pname:dependencyCount is the number of dependencies between pairs of
|
|
subpasses, or zero indicating no dependencies.
|
|
* pname:pDependencies points to an array of pname:dependencyCount number
|
|
of slink:VkSubpassDependency structures describing dependencies between
|
|
pairs of subpasses, or `NULL` if pname:dependencyCount is zero.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkRenderPassCreateInfo-None-00832]]
|
|
If any two subpasses operate on attachments with overlapping ranges of
|
|
the same sname:VkDeviceMemory object, and at least one subpass writes to
|
|
that area of sname:VkDeviceMemory, a subpass dependency must: be
|
|
included (either directly or via some intermediate subpasses) between
|
|
them
|
|
* [[VUID-VkRenderPassCreateInfo-attachment-00833]]
|
|
If the pname:attachment member of any element of
|
|
pname:pInputAttachments, pname:pColorAttachments,
|
|
pname:pResolveAttachments or pname:pDepthStencilAttachment, or the
|
|
attachment indexed by any element of pname:pPreserveAttachments in any
|
|
given element of pname:pSubpasses is bound to a range of a
|
|
sname:VkDeviceMemory object that overlaps with any other attachment in
|
|
any subpass (including the same subpass), the
|
|
sname:VkAttachmentDescription structures describing them must: include
|
|
ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags
|
|
* [[VUID-VkRenderPassCreateInfo-attachment-00834]]
|
|
If the pname:attachment member of any element of
|
|
pname:pInputAttachments, pname:pColorAttachments,
|
|
pname:pResolveAttachments or pname:pDepthStencilAttachment, or any
|
|
element of pname:pPreserveAttachments in any given element of
|
|
pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, it must: be less
|
|
than pname:attachmentCount
|
|
* [[VUID-VkRenderPassCreateInfo-pPreserveAttachments-00835]]
|
|
The value of any element of the pname:pPreserveAttachments member in any
|
|
given element of pname:pSubpasses must: not be
|
|
ename:VK_ATTACHMENT_UNUSED
|
|
* [[VUID-VkRenderPassCreateInfo-pAttachments-00836]]
|
|
For any member of pname:pAttachments with a pname:loadOp equal to
|
|
ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
|
|
must: not specify a pname:layout equal to
|
|
pname:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or
|
|
pname:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.
|
|
* [[VUID-VkRenderPassCreateInfo-pDependencies-00837]]
|
|
For any element of pname:pDependencies, if the pname:srcSubpass is not
|
|
ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
|
|
pname:srcStageMask member of that dependency must: be a pipeline stage
|
|
supported by the <<synchronization-pipeline-stages-types, pipeline>>
|
|
identified by the pname:pipelineBindPoint member of the source subpass.
|
|
* [[VUID-VkRenderPassCreateInfo-pDependencies-00838]]
|
|
For any element of pname:pDependencies, if the pname:dstSubpass is not
|
|
ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
|
|
pname:dstStageMask member of that dependency must: be a pipeline stage
|
|
supported by the <<synchronization-pipeline-stages-types, pipeline>>
|
|
identified by the pname:pipelineBindPoint member of the source subpass.
|
|
****
|
|
|
|
include::../validity/structs/VkRenderPassCreateInfo.txt[]
|
|
|
|
ifdef::VK_KHX_multiview[]
|
|
|
|
[[renderpass-multiview]]
|
|
// refBegin VkRenderPassMultiviewCreateInfoKHX Structure containing multiview info for all subpasses
|
|
|
|
If the sname:VkRenderPassCreateInfo::pname:pNext list includes a
|
|
sname:VkRenderPassMultiviewCreateInfoKHX structure, then that structure
|
|
includes an array of view masks, view offsets, and correlation masks for the
|
|
render pass.
|
|
|
|
The sname:VkRenderPassMultiviewCreateInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkRenderPassMultiviewCreateInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:subpassCount is zero or is the number of subpasses in the render
|
|
pass.
|
|
* pname:pViewMasks points to an array of pname:subpassCount number of view
|
|
masks, where each mask is a bitfield of view indices describing which
|
|
views rendering is broadcast to in each subpass, when multiview is
|
|
enabled.
|
|
If pname:subpassCount is zero, each view mask is treated as zero.
|
|
* pname:dependencyCount is zero or the number of dependencies in the
|
|
render pass.
|
|
* pname:pViewOffsets points to an array of pname:dependencyCount view
|
|
offsets, one for each dependency.
|
|
If pname:dependencyCount is 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.
|
|
* pname:correlationMaskCount is zero or a number of correlation masks.
|
|
* pname:pCorrelationMasks is an array of view 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 code: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
|
|
<<features-features-multiview-gs,geometry shaders>> or
|
|
<<features-features-multiview-tess,tessellation shaders>>.
|
|
|
|
[[renderpass-multiview-view-local]]
|
|
When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX 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 ([eq]#dstView#) in the
|
|
destination subpass depends on the view [eq]#dstView {plus}
|
|
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 pname: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 flink:vkCmdBeginRenderPass or
|
|
flink: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.
|
|
|
|
ifdef::VK_NVX_multiview_per_view_attributes[]
|
|
|
|
A multiview subpass can: declare that its shaders will write per-view
|
|
attributes for all views in a single invocation, by setting the
|
|
ename: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 code:PositionPerViewNV and code:ViewportMaskPerViewNV,
|
|
respectively.
|
|
If +VK_NV_viewport_array2+ is not supported and enabled,
|
|
code:ViewportMaskPerViewNV must: not be used.
|
|
Values written to elements of code:PositionPerViewNV and
|
|
code:ViewportMaskPerViewNV must: not depend on the code:ViewIndex.
|
|
The shader must: also write to an output variable decorated with
|
|
code:Position, and the value written to code:Position must: equal the value
|
|
written to code:PositionPerViewNV[code:ViewIndex].
|
|
Similarly, if code:ViewportMaskPerViewNV is written to then the shader must:
|
|
also write to an output variable decorated with code:ViewportMaskNV, and the
|
|
value written to code:ViewportMaskNV must: equal the value written to
|
|
code:ViewportMaskPerViewNV[code:ViewIndex].
|
|
Implementations will either use values taken from code:Position and
|
|
code:ViewportMaskNV and invoke the shader once for each view, or will use
|
|
values taken from code:PositionPerViewNV and code:ViewportMaskPerViewNV and
|
|
invoke the shader fewer times.
|
|
The values written to code:Position and code:ViewportMaskNV must: not depend
|
|
on the values written to code:PositionPerViewNV and
|
|
code:ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate
|
|
the unused outputs).
|
|
All attributes that do not have *PerViewNV counterparts must: not depend on
|
|
code:ViewIndex.
|
|
|
|
Per-view attributes are all-or-nothing for a subpass.
|
|
That is, all pipelines compiled against a subpass that includes the
|
|
ename: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. code:Position) outputs.
|
|
Pipelines compiled against a subpass that does not include this bit must:
|
|
not include the *PerViewNV[] outputs in their interfaces.
|
|
|
|
endif::VK_NVX_multiview_per_view_attributes[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-subpassCount-00839]]
|
|
If pname:subpassCount is not zero, pname:subpassCount must: be equal to
|
|
the pname:subpassCount in the sname:VkRenderPassCreateInfo structure at
|
|
the start of the chain
|
|
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-dependencyCount-00840]]
|
|
If pname:dependencyCount is not zero, pname:dependencyCount must: be
|
|
equal to the pname:dependencyCount in the sname:VkRenderPassCreateInfo
|
|
structure at the start of the chain
|
|
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-pCorrelationMasks-00841]]
|
|
Each view index must: not be set in more than one element of
|
|
pname:pCorrelationMasks
|
|
* [[VUID-VkRenderPassMultiviewCreateInfoKHX-pViewOffsets-00842]]
|
|
If an element of pname:pViewOffsets is non-zero, the corresponding
|
|
slink:VkSubpassDependency structure must: have different values of
|
|
pname:srcSubpass and pname:dstSubpass.
|
|
****
|
|
|
|
include::../validity/structs/VkRenderPassMultiviewCreateInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_multiview[]
|
|
|
|
// refBegin VkAttachmentDescription Structure specifying an attachment description
|
|
|
|
The sname:VkAttachmentDescription structure is defined as:
|
|
|
|
include::../api/structs/VkAttachmentDescription.txt[]
|
|
|
|
* pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits
|
|
specifying additional properties of the attachment.
|
|
* pname:format is a elink:VkFormat value specifying the format of the
|
|
image that will be used for the attachment.
|
|
* pname:samples is the number of samples of the image as defined in
|
|
elink:VkSampleCountFlagBits.
|
|
* pname:loadOp is a elink: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.
|
|
* pname:storeOp is a elink: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.
|
|
* pname:stencilLoadOp is a elink: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.
|
|
* pname:stencilStoreOp is a elink: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.
|
|
* pname:initialLayout is the layout the attachment image subresource will
|
|
be in when a render pass instance begins.
|
|
* pname:finalLayout is the layout the attachment image subresource will be
|
|
transitioned to when a render pass instance ends.
|
|
During a render pass instance, an attachment can: use a different layout
|
|
in each subpass, if desired.
|
|
|
|
[[renderpass-load-store-ops]]
|
|
If the attachment uses a color format, then pname:loadOp and pname:storeOp
|
|
are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored.
|
|
If the format has depth and/or stencil components, pname:loadOp and
|
|
pname:storeOp apply only to the depth data, while pname:stencilLoadOp and
|
|
pname:stencilStoreOp define how the stencil data is handled.
|
|
pname:loadOp and pname:stencilLoadOp define the _load operations_ that
|
|
execute as part of the first subpass that uses the attachment.
|
|
pname:storeOp and pname:stencilStoreOp define the _store operations_ that
|
|
execute as part of the last subpass that uses the attachment.
|
|
|
|
The load operation for each value in an attachment used by a subpass
|
|
happens-before any command recorded into that subpass reads from that value.
|
|
Load operations for attachments with a depth/stencil format execute in the
|
|
ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage.
|
|
Load operations for attachments with a color format execute in the
|
|
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
|
|
|
|
Store operations for each value in an attachment used by a subpass
|
|
happen-after any command recorded into that subpass writes to that value.
|
|
Store operations for attachments with a depth/stencil format execute in the
|
|
ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage.
|
|
Store operations for attachments with a color format execute in the
|
|
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
|
|
|
|
If an attachment is not used by any subpass, then pname:loadOp,
|
|
pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored,
|
|
and the attachment's memory contents will not be modified by execution of a
|
|
render pass instance.
|
|
|
|
ifdef::VK_KHX_multiview[]
|
|
|
|
The load and store operations apply on the first and last use of each view
|
|
in the render pass, respectively.
|
|
If a view index of an attachment is not included in the view mask in any
|
|
subpass that uses it, then the load and store operations are ignored, and
|
|
the attachment's memory contents will not be modified by execution of a
|
|
render pass instance.
|
|
|
|
endif::VK_KHX_multiview[]
|
|
|
|
[[renderpass-precision]]
|
|
During a render pass instance, input/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 pname: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 pname:storeOp.
|
|
Conversions occur as described in <<fundamentals-numerics,Numeric
|
|
Representation and Computation>> and <<fundamentals-fixedconv, Fixed-Point
|
|
Data Conversions>>.
|
|
|
|
[[renderpass-aliasing]]
|
|
If pname:flags includes ename: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 pname: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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkAttachmentDescription-finalLayout-00843]]
|
|
pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED
|
|
****
|
|
|
|
include::../validity/structs/VkAttachmentDescription.txt[]
|
|
|
|
// refBegin VkAttachmentDescriptionFlagBits Bitmask specifying additional properties of an attachment
|
|
|
|
Bits which can: be set in slink:VkAttachmentDescription::pname:flags
|
|
describing additional properties of the attachment are:
|
|
|
|
include::../api/enums/VkAttachmentDescriptionFlagBits.txt[]
|
|
|
|
* ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the
|
|
attachment aliases the same device memory as other attachments.
|
|
|
|
// refEnd VkAttachmentDescriptionFlagBits
|
|
|
|
// refBegin VkAttachmentLoadOp Specify how contents of an attachment are treated at the beginning of a subpass
|
|
|
|
Possible values of slink:VkAttachmentDescription::pname:loadOp and
|
|
pname:stencilLoadOp, specifying how the contents of the attachment are
|
|
treated, are:
|
|
|
|
include::../api/enums/VkAttachmentLoadOp.txt[]
|
|
|
|
* ename:VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of
|
|
the image within the render area will be preserved.
|
|
For attachments with a depth/stencil format, this uses the access type
|
|
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT.
|
|
For attachments with a color format, this uses the access type
|
|
ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.
|
|
* ename:VK_ATTACHMENT_LOAD_OP_CLEAR specifies 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 type
|
|
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
|
|
For attachments with a color format, this uses the access type
|
|
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
|
* ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies 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 type
|
|
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
|
|
For attachments with a color format, this uses the access type
|
|
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
|
|
|
// refEnd VkAttachmentLoadOp
|
|
|
|
// refBegin VkAttachmentStoreOp Specify how contents of an attachment are treated at the end of a subpass
|
|
|
|
Possible values of slink:VkAttachmentDescription::pname:storeOp and
|
|
pname:stencilStoreOp, specifying how the contents of the attachment are
|
|
treated, are:
|
|
|
|
include::../api/enums/VkAttachmentStoreOp.txt[]
|
|
|
|
* ename:VK_ATTACHMENT_STORE_OP_STORE specifies 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 type
|
|
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
|
|
For attachments with a color format, this uses the access type
|
|
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
|
* ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies 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 type
|
|
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
|
|
For attachments with a color format, this uses the access type
|
|
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
|
|
|
// refEnd VkAttachmentStoreOp
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
TODO (Jon) - the following text may need to be moved back to combine with
|
|
flink:vkCreateRenderPass above for automatic ref page generation.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
If a render pass uses multiple attachments that alias the same device
|
|
memory, those attachments must: each include the
|
|
ename: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
|
|
[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 ename:VK_DEPENDENCY_BY_REGION_BIT
|
|
if the aliases are views of distinct image subresources which overlap in
|
|
memory.
|
|
====
|
|
|
|
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.
|
|
The precise set of valid scenarios is described in more detail
|
|
<<renderpass-feedbackloop, below>>.
|
|
|
|
If a set of attachments alias each other, then all except the first to be
|
|
used in the render pass must: use an pname:initialLayout of
|
|
ename: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]
|
|
.Note
|
|
====
|
|
Once an attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT
|
|
bit, there should: be no additional cost of introducing additional aliases,
|
|
and using these additional aliases may: allow more efficient clearing of the
|
|
attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR.
|
|
====
|
|
|
|
// refBegin VkSubpassDescription Structure specifying a subpass description
|
|
|
|
The sname:VkSubpassDescription structure is defined as:
|
|
|
|
include::../api/structs/VkSubpassDescription.txt[]
|
|
|
|
* pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits
|
|
specifying usage of the subpass.
|
|
* pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
|
|
whether this is a compute or graphics subpass.
|
|
Currently, only graphics subpasses are supported.
|
|
* pname:inputAttachmentCount is the number of input attachments.
|
|
* pname:pInputAttachments is an array of slink:VkAttachmentReference
|
|
structures (defined below) that lists which of the render pass's
|
|
attachments can: be read in the shader during the subpass, and what
|
|
layout each attachment will be in during the subpass.
|
|
Each element of the array corresponds to an input attachment unit number
|
|
in the shader, i.e. if the shader declares an input variable
|
|
`layout(input_attachment_index=X, set=Y, binding=Z)` then it uses the
|
|
attachment provided in pname:pInputAttachments[X].
|
|
Input attachments must: also be bound to the pipeline with a descriptor
|
|
set, with the input attachment descriptor written in the location
|
|
(set=Y, binding=Z).
|
|
* pname:colorAttachmentCount is the number of color attachments.
|
|
* pname:pColorAttachments is an array of pname:colorAttachmentCount
|
|
slink:VkAttachmentReference structures that lists which of the render
|
|
pass's attachments will be used as color attachments in the subpass, and
|
|
what layout each attachment will be in during the subpass.
|
|
Each element of the array corresponds to a fragment shader output
|
|
location, i.e. if the shader declared an output variable
|
|
`layout(location=X)` then it uses the attachment provided in
|
|
pname:pColorAttachments[X].
|
|
* pname:pResolveAttachments is `NULL` or an array of
|
|
pname:colorAttachmentCount slink:VkAttachmentReference structures that
|
|
lists which of the render pass's attachments are resolved to at the end
|
|
of the subpass, and what layout each attachment will be in during the
|
|
multisample resolve operation.
|
|
If pname:pResolveAttachments is not `NULL`, each of its elements
|
|
corresponds to a color attachment (the element in
|
|
pname:pColorAttachments at the same index), and a multisample resolve
|
|
operation is defined for each attachment.
|
|
At the end of each subpass, multisample resolve operations read the
|
|
subpass's color attachments, and resolve the samples for each pixel to
|
|
the same pixel location in the corresponding resolve attachments, unless
|
|
the resolve attachment index is ename:VK_ATTACHMENT_UNUSED.
|
|
If the first use of an attachment in a render pass is as a resolve
|
|
attachment, then the pname:loadOp is effectively ignored as the resolve
|
|
is guaranteed to overwrite all pixels in the render area.
|
|
* pname:pDepthStencilAttachment is a pointer to a
|
|
slink:VkAttachmentReference specifying which attachment will be used for
|
|
depth/stencil data and the layout it will be in during the subpass.
|
|
Setting the attachment index to ename:VK_ATTACHMENT_UNUSED or leaving
|
|
this pointer as `NULL` indicates that no depth/stencil attachment will
|
|
be used in the subpass.
|
|
* pname:preserveAttachmentCount is the number of preserved attachments.
|
|
* pname:pPreserveAttachments is an array of pname:preserveAttachmentCount
|
|
render pass attachment indices describing the attachments that are not
|
|
used by a subpass, but whose contents must: be preserved throughout 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 *S~1~* that uses or preserves the attachment, and a
|
|
subpass dependency from *S~1~* to *S*.
|
|
* The attachment is not used or preserved in subpass *S*.
|
|
|
|
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 *S~1~* if those subpasses use or preserve the
|
|
attachment.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkSubpassDescription-pipelineBindPoint-00844]]
|
|
pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS
|
|
* [[VUID-VkSubpassDescription-colorAttachmentCount-00845]]
|
|
pname:colorAttachmentCount must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxColorAttachments
|
|
* [[VUID-VkSubpassDescription-loadOp-00846]]
|
|
If the first use of an attachment in this render pass is as an input
|
|
attachment, and the attachment is not also used as a color or
|
|
depth/stencil attachment in the same subpass, then pname:loadOp must:
|
|
not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR
|
|
* [[VUID-VkSubpassDescription-pResolveAttachments-00847]]
|
|
If pname:pResolveAttachments is not `NULL`, for each resolve attachment
|
|
that does not have the value ename:VK_ATTACHMENT_UNUSED, the
|
|
corresponding color attachment must: not have the value
|
|
ename:VK_ATTACHMENT_UNUSED
|
|
* [[VUID-VkSubpassDescription-pResolveAttachments-00848]]
|
|
If pname:pResolveAttachments is not `NULL`, the sample count of each
|
|
element of pname:pColorAttachments must: be anything other than
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-VkSubpassDescription-pResolveAttachments-00849]]
|
|
Any given element of pname:pResolveAttachments must: have a sample count
|
|
of ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-VkSubpassDescription-pResolveAttachments-00850]]
|
|
Any given element of pname:pResolveAttachments must: have the same
|
|
elink:VkFormat as its corresponding color attachment
|
|
* [[VUID-VkSubpassDescription-pColorAttachments-00851]]
|
|
All attachments in pname:pColorAttachments and
|
|
pname:pDepthStencilAttachment that are not ename:VK_ATTACHMENT_UNUSED
|
|
must: have the same sample count
|
|
* [[VUID-VkSubpassDescription-None-00852]]
|
|
If any input attachments are ename:VK_ATTACHMENT_UNUSED, then any
|
|
pipelines bound during the subpass must: not access those input
|
|
attachments from the fragment shader
|
|
* [[VUID-VkSubpassDescription-attachment-00853]]
|
|
The pname:attachment member of any element of pname:pPreserveAttachments
|
|
must: not be ename:VK_ATTACHMENT_UNUSED
|
|
* [[VUID-VkSubpassDescription-pPreserveAttachments-00854]]
|
|
Any given element of pname:pPreserveAttachments must: not also be an
|
|
element of any other member of the subpass description
|
|
* [[VUID-VkSubpassDescription-layout-00855]]
|
|
If any attachment is used as both an input attachment and a color or
|
|
depth/stencil attachment, then each use must: use the same pname:layout
|
|
ifdef::VK_NVX_multiview_per_view_attributes[]
|
|
* [[VUID-VkSubpassDescription-flags-00856]]
|
|
If pname:flags includes
|
|
ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must:
|
|
also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX.
|
|
endif::VK_NVX_multiview_per_view_attributes[]
|
|
****
|
|
|
|
include::../validity/structs/VkSubpassDescription.txt[]
|
|
|
|
// refBegin VkSubpassDescriptionFlagBits Bitmask specifying usage of a subpass
|
|
|
|
Bits which can: be set in slink:VkSubpassDescription::pname:flags,
|
|
specifying usage of the subpass, are:
|
|
|
|
include::../api/enums/VkSubpassDescriptionFlagBits.txt[]
|
|
|
|
ifdef::VK_NVX_multiview_per_view_attributes[]
|
|
* ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that
|
|
shaders compiled for this subpass write the attributes for all views in
|
|
a single invocation of each vertex processing stage.
|
|
All pipelines compiled against a subpass that includes this bit must:
|
|
write per-view attributes to the code:*PerViewNV[] shader outputs, in
|
|
addition to the non-per-view (e.g. code:Position) outputs.
|
|
* ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies
|
|
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.
|
|
endif::VK_NVX_multiview_per_view_attributes[]
|
|
|
|
// refEnd VkSubpassDescriptionFlagBits
|
|
|
|
// refBegin VkAttachmentReference Structure specifying an attachment reference
|
|
|
|
The sname:VkAttachmentReference structure is defined as:
|
|
|
|
include::../api/structs/VkAttachmentReference.txt[]
|
|
|
|
* pname:attachment is the index of the attachment of the render pass, and
|
|
corresponds to the index of the corresponding element in the
|
|
pname:pAttachments array of the sname:VkRenderPassCreateInfo structure.
|
|
If any color or depth/stencil attachments are
|
|
ename:VK_ATTACHMENT_UNUSED, then no writes occur for those attachments.
|
|
* pname:layout is a elink:VkImageLayout value specifying the layout the
|
|
attachment uses during the subpass.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkAttachmentReference-layout-00857]]
|
|
pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED
|
|
****
|
|
|
|
include::../validity/structs/VkAttachmentReference.txt[]
|
|
|
|
// refBegin VkSubpassDependency Structure specifying a subpass dependency
|
|
|
|
The sname:VkSubpassDependency structure is defined as:
|
|
|
|
include::../api/structs/VkSubpassDependency.txt[]
|
|
|
|
* pname:srcSubpass is the subpass index of the first subpass in the
|
|
dependency, or ename:VK_SUBPASS_EXTERNAL.
|
|
* pname:dstSubpass is the subpass index of the second subpass in the
|
|
dependency, or ename:VK_SUBPASS_EXTERNAL.
|
|
* pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits
|
|
specifying the <<synchronization-pipeline-stages-masks, source stage
|
|
mask>>.
|
|
* pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits
|
|
specifying the <<synchronization-pipeline-stages-masks, destination
|
|
stage mask>>
|
|
* pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
|
|
<<synchronization-access-masks, source access mask>>.
|
|
* pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
|
|
<<synchronization-access-masks, destination access mask>>.
|
|
* pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits.
|
|
|
|
If pname:srcSubpass is equal to pname:dstSubpass then the
|
|
slink:VkSubpassDependency describes a
|
|
<<synchronization-pipeline-barriers-subpass-self-dependencies, subpass
|
|
self-dependency>>, and only constrains the pipeline barriers allowed within
|
|
a subpass instance.
|
|
Otherwise, when a render pass instance which includes a subpass dependency
|
|
is submitted to a queue, it defines a memory dependency between the
|
|
subpasses identified by pname:srcSubpass and pname:dstSubpass.
|
|
|
|
If pname:srcSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the first
|
|
<<synchronization-dependencies-scopes, synchronization scope>> includes
|
|
commands submitted to the queue before the render pass instance began.
|
|
Otherwise, the first set of commands includes all commands submitted as part
|
|
of the subpass instance identified by pname:srcSubpass and any load, store
|
|
or multisample resolve operations on attachments used in pname:srcSubpass.
|
|
In either case, the first synchronization scope is limited to operations on
|
|
the pipeline stages determined by the
|
|
<<synchronization-pipeline-stages-masks, source stage mask>> specified by
|
|
pname:srcStageMask.
|
|
|
|
If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second
|
|
<<synchronization-dependencies-scopes, synchronization scope>> includes
|
|
commands submitted after the render pass instance is ended.
|
|
Otherwise, the second set of commands includes all commands submitted as
|
|
part of the subpass instance identified by pname:dstSubpass and any load,
|
|
store or multisample resolve operations on attachments used in
|
|
pname:dstSubpass.
|
|
In either case, the second synchronization scope is limited to operations on
|
|
the pipeline stages determined by the
|
|
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
|
|
by pname:dstStageMask.
|
|
|
|
The first <<synchronization-dependencies-access-scopes, access scope>> is
|
|
limited to access in the pipeline stages determined by the
|
|
<<synchronization-pipeline-stages-masks, source stage mask>> specified by
|
|
pname:srcStageMask.
|
|
It is also limited to access types in the <<synchronization-access-masks,
|
|
source access mask>> specified by pname:srcAccessMask.
|
|
|
|
The second <<synchronization-dependencies-access-scopes, access scope>> is
|
|
limited to access in the pipeline stages determined by the
|
|
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
|
|
by pname:dstStageMask.
|
|
It is also limited to access types in the <<synchronization-access-masks,
|
|
destination access mask>> specified by pname:dstAccessMask.
|
|
|
|
The <<synchronization-dependencies-available-and-visible, availability and
|
|
visibility operations>> defined by a subpass dependency affect the execution
|
|
of <<renderpass-layout-transitions, image layout transitions>> within the
|
|
render pass.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00858]]
|
|
If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask
|
|
must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
|
|
* [[VUID-VkSubpassDependency-dstSubpass-00859]]
|
|
If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask
|
|
must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
|
|
* [[VUID-VkSubpassDependency-srcStageMask-00860]]
|
|
If the <<features-features-geometryShader,geometry shaders>> feature is
|
|
not enabled, pname:srcStageMask must: not contain
|
|
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
|
|
* [[VUID-VkSubpassDependency-dstStageMask-00861]]
|
|
If the <<features-features-geometryShader,geometry shaders>> feature is
|
|
not enabled, pname:dstStageMask must: not contain
|
|
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
|
|
* [[VUID-VkSubpassDependency-srcStageMask-00862]]
|
|
If the <<features-features-tessellationShader,tessellation shaders>>
|
|
feature is not enabled, pname:srcStageMask must: not contain
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
|
|
* [[VUID-VkSubpassDependency-dstStageMask-00863]]
|
|
If the <<features-features-tessellationShader,tessellation shaders>>
|
|
feature is not enabled, pname:dstStageMask must: not contain
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00864]]
|
|
pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless
|
|
one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies
|
|
and ensure a valid execution order
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00865]]
|
|
pname:srcSubpass and pname:dstSubpass must: not both be equal to
|
|
ename:VK_SUBPASS_EXTERNAL
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00866]]
|
|
If pname:srcSubpass is equal to pname:dstSubpass, pname:srcStageMask and
|
|
pname:dstStageMask must: only contain one of
|
|
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
|
|
ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT,
|
|
ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT,
|
|
ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT,
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT,
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT,
|
|
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT,
|
|
ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT,
|
|
ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT,
|
|
ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT,
|
|
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,
|
|
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, or
|
|
ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00867]]
|
|
If pname:srcSubpass is equal to pname:dstSubpass and not all of the
|
|
stages in pname:srcStageMask and pname:dstStageMask are
|
|
<<synchronization-framebuffer-regions,framebuffer-space stages>>, the
|
|
<<synchronization-pipeline-stages-order, logically latest>> pipeline
|
|
stage in pname:srcStageMask must: be
|
|
<<synchronization-pipeline-stages-order, logically earlier>> than or
|
|
equal to the <<synchronization-pipeline-stages-order, logically
|
|
earliest>> pipeline stage in pname:dstStageMask
|
|
* [[VUID-VkSubpassDependency-srcAccessMask-00868]]
|
|
Any access flag included in pname:srcAccessMask must: be supported by
|
|
one of the pipeline stages in pname:srcStageMask, as specified in the
|
|
<<synchronization-access-types-supported, table of supported access
|
|
types>>.
|
|
* [[VUID-VkSubpassDependency-dstAccessMask-00869]]
|
|
Any access flag included in pname:dstAccessMask must: be supported by
|
|
one of the pipeline stages in pname:dstStageMask, as specified in the
|
|
<<synchronization-access-types-supported, table of supported access
|
|
types>>.
|
|
ifdef::VK_KHX_multiview[]
|
|
* [[VUID-VkSubpassDependency-dependencyFlags-00870]]
|
|
If pname:dependencyFlags includes
|
|
ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX, then both pname:srcSubpass and
|
|
pname:dstSubpass must: not equal ename:VK_SUBPASS_EXTERNAL
|
|
* [[VUID-VkSubpassDependency-dependencyFlags-00871]]
|
|
If pname:dependencyFlags includes
|
|
ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX, then the render pass must: have
|
|
multiview enabled
|
|
* [[VUID-VkSubpassDependency-srcSubpass-00872]]
|
|
If pname:srcSubpass equals pname:dstSubpass and that subpass has more
|
|
than one bit set in the view mask, then pname:dependencyFlags must:
|
|
include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT_KHX
|
|
endif::VK_KHX_multiview[]
|
|
****
|
|
|
|
include::../validity/structs/VkSubpassDependency.txt[]
|
|
|
|
ifdef::VK_KHX_multiview[]
|
|
|
|
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 ename: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]
|
|
.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
|
|
[eq]#N {times} 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 were a separate attachment.
|
|
====
|
|
|
|
endif::VK_KHX_multiview[]
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
The following two alleged implicit dependencies are practically no-ops, as
|
|
the operations they describe are already guaranteed by semaphores and
|
|
submission order (so they're almost entirely no-ops on their own).
|
|
The *only* reason they exist is because it simplifies reasoning about where
|
|
<<renderpass-layout-transitions, automatic layout transitions>> happen.
|
|
Further rewrites of this chapter could potentially remove the need for
|
|
these.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
If there is no subpass dependency from ename:VK_SUBPASS_EXTERNAL to the
|
|
first subpass that uses an attachment, then an implicit subpass dependency
|
|
exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in.
|
|
The subpass dependency operates as if defined with the following parameters:
|
|
|
|
[source,c]
|
|
----
|
|
VkSubpassDependency implicitDependency = {
|
|
.srcSubpass = VK_SUBPASS_EXTERNAL;
|
|
.dstSubpass = firstSubpass; // First subpass attachment is used in
|
|
.srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
|
|
.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 ename:VK_SUBPASS_EXTERNAL, then an implicit subpass
|
|
dependency exists from the last subpass it is used in to
|
|
ename:VK_SUBPASS_EXTERNAL.
|
|
The subpass dependency operates as if defined with the following parameters:
|
|
|
|
[source,c]
|
|
----
|
|
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_BOTTOM_OF_PIPE_BIT;
|
|
.srcAccessMask = 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;
|
|
.dstAccessMask = 0;
|
|
.dependencyFlags = 0;
|
|
};
|
|
----
|
|
|
|
[[renderpass-layout-transitions]]
|
|
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 renderpass, 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 away from the layout used in a subpass
|
|
happen-after the availability operations for all dependencies with that
|
|
subpass as the pname:srcSubpass.
|
|
|
|
Automatic layout transitions into the layout used in a subpass happen-before
|
|
the visibility operations for all dependencies with that subpass as the
|
|
pname:dstSubpass.
|
|
|
|
Automatic layout transitions away from pname:initialLayout happens-after the
|
|
availability operations for all dependencies with a pname:srcSubpass equal
|
|
to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses the attachment
|
|
that will be transitioned.
|
|
For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
|
|
automatic layout transitions away from pname:initialLayout happen-after the
|
|
availability operations for all dependencies with a pname:srcSubpass equal
|
|
to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses any aliased
|
|
attachment.
|
|
|
|
Automatic layout transitions into pname:finalLayout happens-before the
|
|
visibility operations for all dependencies with a pname:dstSubpass equal to
|
|
ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses the attachment that
|
|
will be transitioned.
|
|
For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
|
|
automatic layout transitions into pname:finalLayout happen-before the
|
|
visibility operations for all dependencies with a pname:dstSubpass equal to
|
|
ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses any aliased
|
|
attachment.
|
|
|
|
If two subpasses use the same attachment in different layouts, and both
|
|
layouts are read-only, 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:
|
|
|
|
[source,c]
|
|
----
|
|
// Used for input attachments
|
|
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
|
|
VkAccessFlags inputAttachmentAccess = 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 depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;
|
|
|
|
VkSubpassDependency implicitDependency = {
|
|
.srcSubpass = firstSubpass;
|
|
.dstSubpass = secondSubpass;
|
|
.srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
|
|
.dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
|
|
.srcAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
|
|
.dstAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
|
|
.dependencyFlags = 0;
|
|
};
|
|
----
|
|
|
|
[[renderpass-feedbackloop]]
|
|
If a subpass uses the same attachment as both an input attachment and either
|
|
a color attachment or a depth/stencil attachment, writes via the color or
|
|
depth/stencil attachment are not automatically made visible to reads via the
|
|
input attachment, causing a _feedback loop_, except in any of the following
|
|
conditions:
|
|
|
|
* If the color components or depth/stencil components read by the input
|
|
attachment are mutually exclusive with the components written by the
|
|
color or depth/stencil attachments, then there is no feedback loop.
|
|
This requires the graphics pipelines used by the subpass to disable
|
|
writes to color components that are read as inputs via the
|
|
pname:colorWriteMask, and to disable writes to depth/stencil components
|
|
that are read as inputs via pname:depthWriteEnable or
|
|
pname:stencilTestEnable.
|
|
* If the attachment is used as an input attachment and depth/stencil
|
|
attachment only, and the depth/stencil attachment is not written to.
|
|
* If a memory dependency is inserted between when the attachment is
|
|
written and when it is subsequently read by later fragments.
|
|
<<synchronization-pipeline-barriers, Pipeline barriers>> expressing a
|
|
<<synchronization-pipeline-barriers-subpass-self-dependencies, subpass
|
|
self-dependency>> are the only way to achieve this, and one must: be
|
|
inserted every time a fragment will read values at a particular sample
|
|
(x, y, layer, sample) coordinate, if those values have been written
|
|
since the most recent pipeline barrier; or the since start of the
|
|
subpass if there have been no pipeline barriers since the start of the
|
|
subpass.
|
|
|
|
An attachment used as both an input attachment and a color attachment must:
|
|
be in the
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_GENERAL layout.
|
|
An attachment used as an input attachment and depth/stencil attachment must:
|
|
be in the
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL layout.
|
|
An attachment must: not be used as both a depth/stencil attachment and a
|
|
color attachment.
|
|
|
|
// refBegin vkDestroyRenderPass Destroy a render pass object
|
|
|
|
To destroy a render pass, call:
|
|
|
|
include::../api/protos/vkDestroyRenderPass.txt[]
|
|
|
|
* pname:device is the logical device that destroys the render pass.
|
|
* pname:renderPass is the handle of the render pass to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyRenderPass-renderPass-00873]]
|
|
All submitted commands that refer to pname:renderPass must: have
|
|
completed execution
|
|
* [[VUID-vkDestroyRenderPass-renderPass-00874]]
|
|
If sname:VkAllocationCallbacks were provided when pname:renderPass was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyRenderPass-renderPass-00875]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:renderPass
|
|
was created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyRenderPass.txt[]
|
|
|
|
|
|
[[renderpass-compatibility]]
|
|
== 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 ename: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 ename: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
|
|
|
|
A framebuffer is compatible with a render pass if it was created using the
|
|
same render pass or a compatible render pass.
|
|
|
|
|
|
== Framebuffers
|
|
|
|
// refBegin VkFramebuffer Opaque handle to a framebuffer object
|
|
|
|
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 sname:VkFramebuffer handles:
|
|
|
|
include::../api/handles/VkFramebuffer.txt[]
|
|
|
|
// refEnd VkFramebuffer
|
|
|
|
// refBegin vkCreateFramebuffer Create a new framebuffer object
|
|
|
|
To create a framebuffer, call:
|
|
|
|
include::../api/protos/vkCreateFramebuffer.txt[]
|
|
|
|
* pname:device is the logical device that creates the framebuffer.
|
|
* pname:pCreateInfo points to a slink:VkFramebufferCreateInfo structure
|
|
which describes additional information about framebuffer creation.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pFramebuffer points to a sname:VkFramebuffer handle in which the
|
|
resulting framebuffer object is returned.
|
|
|
|
include::../validity/protos/vkCreateFramebuffer.txt[]
|
|
|
|
// refBegin VkFramebufferCreateInfo Structure specifying parameters of a newly created framebuffer
|
|
|
|
The sname:VkFramebufferCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkFramebufferCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:renderPass is a render pass that defines what render passes the
|
|
framebuffer will be compatible with.
|
|
See <<renderpass-compatibility,Render Pass Compatibility>> for details.
|
|
* pname:attachmentCount is the number of attachments.
|
|
* pname:pAttachments is an array of sname:VkImageView handles, each of
|
|
which will be used as the corresponding attachment in a render pass
|
|
instance.
|
|
* pname:width, pname:height and pname:layers define the dimensions of the
|
|
framebuffer.
|
|
ifdef::VK_KHX_multiview[]
|
|
If the render pass uses multiview, then pname:layers must: 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.
|
|
endif::VK_KHX_multiview[]
|
|
|
|
Image subresources used as attachments must: not be used via any
|
|
non-attachment usage for the duration of a render pass instance.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
This restriction means that the render pass has full knowledge of all uses
|
|
of all of the attachments, so that the implementation is able to make
|
|
correct decisions about when and how to perform layout transitions, when to
|
|
overlap execution of subpasses, etc.
|
|
====
|
|
|
|
[[renderpass-noattachments]]
|
|
It is legal for a subpass to use no color or depth/stencil attachments, and
|
|
rather use shader side effects such as image stores and atomics to produce
|
|
an output.
|
|
In this case, the subpass continues to use the pname:width, pname:height,
|
|
and pname:layers of the framebuffer to define the dimensions of the
|
|
rendering area, and the pname:rasterizationSamples from each pipeline's
|
|
slink:VkPipelineMultisampleStateCreateInfo to define the number of samples
|
|
used in rasterization; however, if
|
|
slink:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is
|
|
code:VK_FALSE, then all pipelines to be bound with a given zero-attachment
|
|
subpass must: have the same value for
|
|
slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkFramebufferCreateInfo-attachmentCount-00876]]
|
|
pname:attachmentCount must: be equal to the attachment count specified
|
|
in pname:renderPass
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00877]]
|
|
Any given element of pname:pAttachments that is used as a color
|
|
attachment or resolve attachment by pname:renderPass must: have been
|
|
created with a pname:usage value including
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00878]]
|
|
Any given element of pname:pAttachments that is used as a depth/stencil
|
|
attachment by pname:renderPass must: have been created with a
|
|
pname:usage value including
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00879]]
|
|
Any given element of pname:pAttachments that is used as an input
|
|
attachment by pname:renderPass must: have been created with a
|
|
pname:usage value including ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00880]]
|
|
Any given element of pname:pAttachments must: have been created with an
|
|
elink:VkFormat value that matches the elink:VkFormat specified by the
|
|
corresponding sname:VkAttachmentDescription in pname:renderPass
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00881]]
|
|
Any given element of pname:pAttachments must: have been created with a
|
|
pname:samples value that matches the pname:samples value specified by
|
|
the corresponding sname:VkAttachmentDescription in pname:renderPass
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00882]]
|
|
Any given element of pname:pAttachments must: have dimensions at least
|
|
as large as the corresponding framebuffer dimension
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00883]]
|
|
Any given element of pname:pAttachments must: only specify a single mip
|
|
level
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00884]]
|
|
Any given element of pname:pAttachments must: have been created with the
|
|
identity swizzle
|
|
* [[VUID-VkFramebufferCreateInfo-width-00885]]
|
|
pname:width must: be greater than `0`.
|
|
* [[VUID-VkFramebufferCreateInfo-width-00886]]
|
|
pname:width must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth
|
|
* [[VUID-VkFramebufferCreateInfo-height-00887]]
|
|
pname:height must: be greater than `0`.
|
|
* [[VUID-VkFramebufferCreateInfo-height-00888]]
|
|
pname:height must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight
|
|
* [[VUID-VkFramebufferCreateInfo-layers-00889]]
|
|
pname:layers must: be greater than `0`.
|
|
* [[VUID-VkFramebufferCreateInfo-layers-00890]]
|
|
pname:layers must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkFramebufferCreateInfo-pAttachments-00891]]
|
|
Any given element of pname:pAttachments that is a 2D or 2D array image
|
|
view taken from a 3D image must: not be a depth/stencil format
|
|
endif::VK_KHR_maintenance1[]
|
|
****
|
|
|
|
include::../validity/structs/VkFramebufferCreateInfo.txt[]
|
|
|
|
// refBegin vkDestroyFramebuffer Destroy a framebuffer object
|
|
|
|
To destroy a framebuffer, call:
|
|
|
|
include::../api/protos/vkDestroyFramebuffer.txt[]
|
|
|
|
* pname:device is the logical device that destroys the framebuffer.
|
|
* pname:framebuffer is the handle of the framebuffer to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyFramebuffer-framebuffer-00892]]
|
|
All submitted commands that refer to pname:framebuffer must: have
|
|
completed execution
|
|
* [[VUID-vkDestroyFramebuffer-framebuffer-00893]]
|
|
If sname:VkAllocationCallbacks were provided when pname:framebuffer was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyFramebuffer-framebuffer-00894]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:framebuffer
|
|
was created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyFramebuffer.txt[]
|
|
|
|
|
|
[[renderpass-commands]]
|
|
== 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.
|
|
|
|
// refBegin vkCmdBeginRenderPass Begin a new render pass
|
|
|
|
To begin a render pass instance, call:
|
|
|
|
include::../api/protos/vkCmdBeginRenderPass.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer in which to record the
|
|
command.
|
|
* pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo
|
|
structure (defined below) which indicates the render pass to begin an
|
|
instance of, and the framebuffer the instance uses.
|
|
* pname:contents is a elink: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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00895]]
|
|
If any of the pname:initialLayout or pname:finalLayout member of the
|
|
sname:VkAttachmentDescription structures or the pname:layout member of
|
|
the sname:VkAttachmentReference structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
|
|
then the corresponding attachment image subresource of the framebuffer
|
|
specified in the pname:framebuffer member of pname:pRenderPassBegin
|
|
must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
set
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00896]]
|
|
If any of the pname:initialLayout or pname:finalLayout member of the
|
|
sname:VkAttachmentDescription structures or the pname:layout member of
|
|
the sname:VkAttachmentReference structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the
|
|
corresponding attachment image subresource of the framebuffer specified
|
|
in the pname:framebuffer member of pname:pRenderPassBegin must: have
|
|
been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00897]]
|
|
If any of the pname:initialLayout or pname:finalLayout member of the
|
|
sname:VkAttachmentDescription structures or the pname:layout member of
|
|
the sname:VkAttachmentReference structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
|
|
then the corresponding attachment image subresource of the framebuffer
|
|
specified in the pname:framebuffer member of pname:pRenderPassBegin
|
|
must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00898]]
|
|
If any of the pname:initialLayout or pname:finalLayout member of the
|
|
sname:VkAttachmentDescription structures or the pname:layout member of
|
|
the sname:VkAttachmentReference structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
|
|
then the corresponding attachment image subresource of the framebuffer
|
|
specified in the pname:framebuffer member of pname:pRenderPassBegin
|
|
must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00899]]
|
|
If any of the pname:initialLayout or pname:finalLayout member of the
|
|
sname:VkAttachmentDescription structures or the pname:layout member of
|
|
the sname:VkAttachmentReference structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
|
|
then the corresponding attachment image subresource of the framebuffer
|
|
specified in the pname:framebuffer member of pname:pRenderPassBegin
|
|
must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set
|
|
* [[VUID-vkCmdBeginRenderPass-initialLayout-00900]]
|
|
If any of the pname:initialLayout members of the
|
|
sname:VkAttachmentDescription structures specified when creating the
|
|
render pass specified in the pname:renderPass member of
|
|
pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each
|
|
such pname:initialLayout must: be equal to the current layout of the
|
|
corresponding attachment image subresource of the framebuffer specified
|
|
in the pname:framebuffer member of pname:pRenderPassBegin
|
|
* [[VUID-vkCmdBeginRenderPass-srcStageMask-00901]]
|
|
The pname:srcStageMask and pname:dstStageMask members of any element of
|
|
the pname:pDependencies member of slink:VkRenderPassCreateInfo used to
|
|
create pname:renderpass must: be supported by the capabilities of the
|
|
queue family identified by the pname:queueFamilyIndex member of the
|
|
slink:VkCommandPoolCreateInfo used to create the command pool which
|
|
pname:commandBuffer was allocated from.
|
|
****
|
|
|
|
include::../validity/protos/vkCmdBeginRenderPass.txt[]
|
|
|
|
// refBegin VkRenderPassBeginInfo Structure specifying render pass begin info
|
|
|
|
The sname:VkRenderPassBeginInfo structure is defined as:
|
|
|
|
include::../api/structs/VkRenderPassBeginInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:renderPass is the render pass to begin an instance of.
|
|
* pname:framebuffer is the framebuffer containing the attachments that are
|
|
used with the render pass.
|
|
* pname:renderArea is the render area that is affected by the render pass
|
|
instance, and is described in more detail below.
|
|
* pname:clearValueCount is the number of elements in pname:pClearValues.
|
|
* pname:pClearValues is an array of slink:VkClearValue structures that
|
|
contains clear values for each attachment, if the attachment uses a
|
|
pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR or if the
|
|
attachment has a depth/stencil format and uses a pname:stencilLoadOp
|
|
value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR.
|
|
The array is indexed by attachment number.
|
|
Only elements corresponding to cleared attachments are used.
|
|
Other elements of pname:pClearValues are ignored.
|
|
|
|
pname: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 pname:framebuffer.
|
|
The application must: ensure (using scissor if necessary) that all rendering
|
|
is contained within the render area, otherwise the pixels outside of the
|
|
render area become undefined and shader side effects may: occur for
|
|
fragments outside the render area.
|
|
The render area must: be contained within the framebuffer dimensions.
|
|
|
|
ifdef::VK_KHX_multiview[]
|
|
|
|
When multiview is enabled, the resolve operation at the end of a subpass
|
|
applies to all views in the view mask.
|
|
|
|
endif::VK_KHX_multiview[]
|
|
|
|
[NOTE]
|
|
.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.
|
|
====
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkRenderPassBeginInfo-clearValueCount-00902]]
|
|
pname:clearValueCount must: be greater than the largest attachment index
|
|
in pname:renderPass that specifies a pname:loadOp (or
|
|
pname:stencilLoadOp, if the attachment has a depth/stencil format) of
|
|
ename:VK_ATTACHMENT_LOAD_OP_CLEAR
|
|
* [[VUID-VkRenderPassBeginInfo-clearValueCount-00903]]
|
|
If pname:clearValueCount is not `0`, pname:pClearValues must: be a
|
|
pointer to an array of pname:clearValueCount valid sname:VkClearValue
|
|
unions
|
|
* [[VUID-VkRenderPassBeginInfo-renderPass-00904]]
|
|
pname:renderPass must: be <<renderpass-compatibility,compatible>> with
|
|
the pname:renderPass member of the sname:VkFramebufferCreateInfo
|
|
structure specified when creating pname:framebuffer.
|
|
****
|
|
|
|
include::../validity/structs/VkRenderPassBeginInfo.txt[]
|
|
|
|
// refBegin VkSubpassContents Specify how commands in the first subpass of a render pass are provided
|
|
|
|
Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying
|
|
how the commands in the first subpass will be provided, are:
|
|
|
|
include::../api/enums/VkSubpassContents.txt[]
|
|
|
|
* ename:VK_SUBPASS_CONTENTS_INLINE specifies 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.
|
|
* ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the
|
|
contents are recorded in secondary command buffers that will be called
|
|
from the primary command buffer, and flink:vkCmdExecuteCommands is the
|
|
only valid command on the command buffer until flink:vkCmdNextSubpass or
|
|
flink:vkCmdEndRenderPass.
|
|
|
|
// refEnd VkSubpassContents
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin VkDeviceGroupRenderPassBeginInfoKHX Set the initial device mask and render areas for a render pass instance
|
|
|
|
If the pname:pNext list of slink:VkRenderPassBeginInfo includes a
|
|
sname:VkDeviceGroupRenderPassBeginInfoKHX structure, then that structure
|
|
includes a device mask and set of render areas for the render pass instance.
|
|
|
|
The sname:VkDeviceGroupRenderPassBeginInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkDeviceGroupRenderPassBeginInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:deviceMask is the device mask for the render pass instance.
|
|
* pname:deviceRenderAreaCount is the number of elements in the
|
|
pname:pDeviceRenderAreas array.
|
|
* pname:pDeviceRenderAreas is an array of structures of type
|
|
slink:VkRect2D defining the render area for each physical device.
|
|
|
|
The pname: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.
|
|
Render pass attachment load, store, and resolve operations only apply to
|
|
physical devices included in the device mask.
|
|
Subpass dependencies only apply to the physical devices in the device mask.
|
|
|
|
If pname:deviceRenderAreaCount is not zero, then the elements of
|
|
pname:pDeviceRenderAreas override the value of
|
|
slink:VkRenderPassBeginInfo::pname:renderArea, and provide a render area
|
|
specific to each physical device.
|
|
These render areas serve the same purpose as
|
|
slink:VkRenderPassBeginInfo::pname:renderArea, including controlling the
|
|
region of attachments that are cleared by ename: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 slink:VkDeviceGroupCommandBufferBeginInfoKHX::pname:deviceMask.
|
|
If this structure is not present or if pname:deviceRenderAreaCount is zero,
|
|
slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical
|
|
devices.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00905]]
|
|
pname:deviceMask must: be a valid device mask value
|
|
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00906]]
|
|
pname:deviceMask must: not be zero
|
|
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceMask-00907]]
|
|
pname:deviceMask must: be a subset of the command buffer's initial
|
|
device mask
|
|
* [[VUID-VkDeviceGroupRenderPassBeginInfoKHX-deviceRenderAreaCount-00908]]
|
|
pname:deviceRenderAreaCount must: either be zero or equal to the number
|
|
of physical devices in the logical device.
|
|
****
|
|
|
|
include::../validity/structs/VkDeviceGroupRenderPassBeginInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// refBegin vkGetRenderAreaGranularity Returns the granularity for optimal render area
|
|
|
|
To query the render area granularity, call:
|
|
|
|
include::../api/protos/vkGetRenderAreaGranularity.txt[]
|
|
|
|
* pname:device is the logical device that owns the render pass.
|
|
* pname:renderPass is a handle to a render pass.
|
|
* pname:pGranularity points to a slink:VkExtent2D structure in which the
|
|
granularity is returned.
|
|
|
|
The conditions leading to an optimal pname:renderArea are:
|
|
|
|
* the pname:offset.x member in pname:renderArea is a multiple of the
|
|
pname:width member of the returned slink:VkExtent2D (the horizontal
|
|
granularity).
|
|
* the pname:offset.y member in pname:renderArea is a multiple of the
|
|
pname:height of the returned slink:VkExtent2D (the vertical
|
|
granularity).
|
|
* either the pname:offset.width member in pname:renderArea is a multiple
|
|
of the horizontal granularity or pname:offset.x+pname:offset.width is
|
|
equal to the pname:width of the pname:framebuffer in the
|
|
slink:VkRenderPassBeginInfo.
|
|
* either the pname:offset.height member in pname:renderArea is a multiple
|
|
of the vertical granularity or pname:offset.y+pname:offset.height is
|
|
equal to the pname:height of the pname:framebuffer in the
|
|
slink:VkRenderPassBeginInfo.
|
|
|
|
Subpass dependencies are not affected by the render area, and apply to the
|
|
entire image subresources attached to the framebuffer.
|
|
Similarly, pipeline barriers are valid even if their effect extends outside
|
|
the render area.
|
|
|
|
include::../validity/protos/vkGetRenderAreaGranularity.txt[]
|
|
|
|
// refBegin vkCmdNextSubpass Transition to the next subpass of a render pass
|
|
|
|
To transition to the next subpass in the render pass instance after
|
|
recording the commands for a subpass, call:
|
|
|
|
include::../api/protos/vkCmdNextSubpass.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer in which to record the
|
|
command.
|
|
* pname:contents specifies how the commands in the next subpass will be
|
|
provided, in the same fashion as the corresponding parameter of
|
|
flink:vkCmdBeginRenderPass.
|
|
|
|
The subpass index for a render pass begins at zero when
|
|
fname:vkCmdBeginRenderPass is recorded, and increments each time
|
|
fname:vkCmdNextSubpass is recorded.
|
|
|
|
Moving to the next subpass automatically performs any multisample resolve
|
|
operations in the subpass being ended.
|
|
End-of-subpass multisample resolves are treated as color attachment writes
|
|
for the purposes of synchronization.
|
|
That is, they are considered to execute in the
|
|
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their
|
|
writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
|
|
Synchronization between rendering within a subpass and any resolve
|
|
operations at the end of the subpass occurs automatically, without need for
|
|
explicit dependencies or pipeline barriers.
|
|
However, if the resolve attachment is also used in a different subpass, an
|
|
explicit dependency is needed.
|
|
|
|
After transitioning to the next subpass, the application can: record the
|
|
commands for that subpass.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdNextSubpass-None-00909]]
|
|
The current subpass index must: be less than the number of subpasses in
|
|
the render pass minus one
|
|
****
|
|
|
|
include::../validity/protos/vkCmdNextSubpass.txt[]
|
|
|
|
// refBegin vkCmdEndRenderPass End the current render pass
|
|
|
|
To record a command to end a render pass instance after recording the
|
|
commands for the last subpass, call:
|
|
|
|
include::../api/protos/vkCmdEndRenderPass.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer in which to end the current
|
|
render pass instance.
|
|
|
|
Ending a render pass instance performs any multisample resolve operations on
|
|
the final subpass.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdEndRenderPass-None-00910]]
|
|
The current subpass index must: be equal to the number of subpasses in
|
|
the render pass minus one
|
|
****
|
|
|
|
include::../validity/protos/vkCmdEndRenderPass.txt[]
|
|
|