mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-05 19:14:22 +00:00
eaea7d2709
* Bump API patch number and header version number to 26 for this update.
Github Issues:
* Bring sample code in the +VK_KHR_surface+ and +VK_KHR_swapchain+
extension summary appendices up to date, and note they will be replaced
with pointers to the LunarG SDK examples in the future (public issue
279).
* Add a new <<fundamentals-commandsyntax-results-lifetime,Lifetime of
Retrieved Results>> section specifying that ftext:vkGet* and
ftext:VkEnumerate* results are invariant unless otherwise specified, and
specify behavior for individual commands which are not invariant (public
issue 280).
* Remove conflicting definition of
slink:VkDisplayPlaneCapabilitiesKHR::pname:maxSrcPosition and clean up
language of the remaining definition (public issue 351).
* Fix many minor spelling errors and add rules to the style guide to
prevent recurrences (public issue 352).
Internal Issues:
* Remove redundant descriptions of the etext:VK_USE_PLATFORM_* macros from
the <<wsi,Window System Integration>> chapter in favor of the
description in the <<boilerplate-wsi-header,Window System-Specific
Header Control>> appendix (internal issue 6).
* Replace misleading 'can: be destroyed when not X' with more correct
'must: not be destroyed while X' in the
<<fundamentals-objectmodel-lifetime,Object Lifetime>> section. Disallow
destroying a pipeline layout while a command buffer using it is
recording (internal issue 241).
* Clarify that ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT is valid for
all images used as attachments in elink:VkImageUsageFlagBits and the
slink:VkImageLayout validity language (internal issue 320).
* Note that <<extended-functionality-layers,Layers>> may wrap object
handles, but that this is a generally discouraged. A link to additional
information in the documentation for layer authors is provided (issue
398)
* Replace the mustnot: and shouldnot: macros with equivalent must: not and
should: not to get rid of non-English words while still highlighting
normative language (internal issue 407).
* Disallow creating multisampled images with
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT in the slink:VkImageLayout
validity language and the <<features-supported-sample-counts,Supported
Sample Counts>> section (internal issue 445).
* Fix typo so that flink:vkCmdDrawIndexedIndirect is defined in terms of
flink:vkCmdDrawIndexed rather than flink:vkCmdDrawIndirect (internal
issue 446).
* Reorganize the per-extension information sections to all be in the
<<extensions,Layers & Extensions>> appendix. Also fix a typo in
+VK_IMG_filter_cubic+ which incorrectly identified it as a +KHR+
extension (internal issue 461).
Other Issues:
* Use asciidoc markup instead of latexmath to simplify diagrams in the
<<features-formats-non-packed,byte mapping tables>> for color formats.
* Fix a markup problem with the wildcarded enumerant names in a NOTE in
the <<textures-texel-replacement,Texel Replacement>> section.
* Fix missing attributes in the XML interface for
elink:VkExternalMemoryHandleTypeFlagBitsNV and
elink:VkExternalMemoryFeatureFlagBitsNV (KhronosGroup/Vulkan-Hpp issue
#25)
* Cleanup reference page builds so only core pages are built for releases.
214 lines
10 KiB
Plaintext
214 lines
10 KiB
Plaintext
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[appendix]
|
|
= Invariance
|
|
|
|
The Vulkan specification is not pixel exact. It therefore does not
|
|
guarantee an exact match between images produced by different Vulkan
|
|
implementations. However, the specification does specify exact matches, in
|
|
some cases, for images produced by the same implementation. The purpose of
|
|
this appendix is to identify and provide justification for those cases that
|
|
require exact matches.
|
|
|
|
== Repeatability
|
|
|
|
The obvious and most fundamental case is repeated issuance of a series of
|
|
Vulkan commands. For any given Vulkan and framebuffer state vector,
|
|
and for any Vulkan command, the resulting Vulkan and framebuffer state
|
|
must: be identical whenever the command is executed on that initial
|
|
Vulkan and framebuffer state. This repeatability requirement does not
|
|
apply when using shaders containing side effects (image and buffer variable
|
|
stores and atomic operations), because these memory operations are not
|
|
guaranteed to be processed in a defined order.
|
|
|
|
ifdef::VK_AMD_rasterization_order[]
|
|
The repeatability requirement does not apply for rendering done using a
|
|
graphics pipeline that uses ename:VK_RASTERIZATION_ORDER_RELAXED_AMD.
|
|
endif::VK_AMD_rasterization_order[]
|
|
|
|
One purpose of repeatability is avoidance of visual artifacts when a
|
|
double-buffered scene is redrawn. If rendering is not repeatable, swapping
|
|
between two buffers rendered with the same command sequence may: result in
|
|
visible changes in the image. Such false motion is distracting to the
|
|
viewer. Another reason for repeatability is testability.
|
|
|
|
Repeatability, while important, is a weak requirement. Given only
|
|
repeatability as a requirement, two scenes rendered with one (small) polygon
|
|
changed in position might differ at every pixel. Such a difference, while
|
|
within the law of repeatability, is certainly not within its spirit.
|
|
Additional invariance rules are desirable to ensure useful operation.
|
|
|
|
|
|
== Multi-pass Algorithms
|
|
|
|
Invariance is necessary for a whole set of useful multi-pass algorithms.
|
|
Such algorithms render multiple times, each time with a different Vulkan
|
|
mode vector, to eventually produce a result in the framebuffer. Examples of
|
|
these algorithms include:
|
|
|
|
* ``Erasing'' a primitive from the framebuffer by redrawing it, either in
|
|
a different color or using the XOR logical operation.
|
|
* Using stencil operations to compute capping planes.
|
|
|
|
|
|
== Invariance Rules
|
|
|
|
For a given instantiation of an Vulkan rendering context:
|
|
|
|
*Rule 1* _For any given Vulkan and framebuffer state vector, and for any
|
|
given Vulkan command, the resulting Vulkan and framebuffer state must:
|
|
be identical each time the command is executed on that initial Vulkan and
|
|
framebuffer state._
|
|
|
|
*Rule 2* _Changes to the following state values have no side effects (the
|
|
use of any other state value is not affected by the change):_
|
|
|
|
*Required:*
|
|
|
|
* _Framebuffer contents (all bit planes)_
|
|
* _The color buffers enabled for writing_
|
|
* _Scissor parameters (other than enable)_
|
|
* _Writemasks (color, depth, stencil)_
|
|
* _Clear values (color, depth, stencil)_
|
|
|
|
*Strongly suggested:*
|
|
|
|
* _Stencil Parameters (other than enable)_
|
|
* _Depth test parameters (other than enable)_
|
|
* _Blend parameters (other than enable)_
|
|
* _Logical operation parameters (other than enable)_
|
|
* _Pixel storage state_
|
|
|
|
*Corollary 1* _Fragment generation is invariant with respect to the state
|
|
values listed in Rule 2._
|
|
|
|
*Rule 3* _The arithmetic of each per-fragment operation is invariant except
|
|
with respect to parameters that directly control it._
|
|
|
|
*Corollary 2* _Images rendered into different color buffers sharing the same
|
|
framebuffer, either simultaneously or separately using the same command
|
|
sequence, are pixel identical._
|
|
|
|
*Rule 4* _The same vertex or fragment shader will produce the same result
|
|
when run multiple times with the same input. The wording ``the same shader''
|
|
means a program object that is populated with the same SPIR-V binary, which
|
|
is used to create pipelines, possibly multiple times, and which program
|
|
object is then executed using the same Vulkan state vector. Invariance is
|
|
relaxed for shaders with side effects, such as performing stores or
|
|
atomics._
|
|
|
|
*Rule 5* _All fragment shaders that either conditionally or unconditionally
|
|
assign_ code:FragCoord.z _to_ code:FragDepth _are depth-invariant with
|
|
respect to each other, for those fragments where the assignment to_
|
|
code:FragDepth _actually is done._
|
|
|
|
If a sequence of Vulkan commands specifies primitives to be rendered with
|
|
shaders containing side effects (image and buffer variable stores and atomic
|
|
operations), invariance rules are relaxed. In particular, rule 1, corollary
|
|
2, and rule 4 do not apply in the presence of shader side effects.
|
|
|
|
The following weaker versions of rules 1 and 4 apply to Vulkan commands
|
|
involving shader side effects:
|
|
|
|
*Rule 6* _For any given Vulkan and framebuffer state vector, and for any
|
|
given Vulkan command, the contents of any framebuffer state not directly
|
|
or indirectly affected by results of shader image or buffer variable stores
|
|
or atomic operations must: be identical each time the command is executed on
|
|
that initial Vulkan and framebuffer state._
|
|
|
|
*Rule 7* _The same vertex or fragment shader will produce the same result
|
|
when run multiple times with the same input as long as:_
|
|
|
|
* _shader invocations do not use image atomic operations;_
|
|
* _no framebuffer memory is written to more than once by image stores,
|
|
unless all such stores write the same value; and_
|
|
* _no shader invocation, or other operation performed to process the
|
|
sequence of commands, reads memory written to by an image store._
|
|
|
|
When any sequence of Vulkan commands triggers shader invocations that
|
|
perform image stores or atomic operations, and subsequent Vulkan commands
|
|
read the memory written by those shader invocations, these operations must:
|
|
be explicitly synchronized.
|
|
|
|
|
|
== Tessellation Invariance
|
|
|
|
When using a program containing tessellation evaluation shaders, the
|
|
fixed-function tessellation primitive generator consumes the input patch
|
|
specified by an application and emits a new set of primitives. The following
|
|
invariance rules are intended to provide repeatability guarantees.
|
|
Additionally, they are intended to allow an application with a carefully
|
|
crafted tessellation evaluation shader to ensure that the sets of triangles
|
|
generated for two adjacent patches have identical vertices along shared
|
|
patch edges, avoiding ``cracks'' caused by minor differences in the
|
|
positions of vertices along shared edges.
|
|
|
|
*Rule 1* _When processing two patches with identical outer and inner
|
|
tessellation levels, the tessellation primitive generator will emit an
|
|
identical set of point, line, or triangle primitives as long as the active
|
|
program used to process the patch primitives has tessellation evaluation
|
|
shaders specifying the same tessellation mode, spacing, vertex order, and
|
|
point mode decorations. Two sets of primitives are considered identical if
|
|
and only if they contain the same number and type of primitives and the
|
|
generated tessellation coordinates for the vertex numbered m of the
|
|
primitive numbered n are identical for all values of m and n._
|
|
|
|
*Rule 2* _The set of vertices generated along the outer edge of the
|
|
subdivided primitive in triangle and quad tessellation, and the tessellation
|
|
coordinates of each, depends only on the corresponding outer tessellation
|
|
level and the spacing decorations in the tessellation shaders of the
|
|
pipeline._
|
|
|
|
*Rule 3* _The set of vertices generated when subdividing any outer primitive
|
|
edge is always symmetric. For triangle tessellation, if the subdivision
|
|
generates a vertex with tessellation coordinates of the form (0, x, 1-x),
|
|
(x, 0, 1-x), or (x, 1-x, 0), it will also generate a vertex with coordinates
|
|
of exactly (0, 1-x, x), (1-x, 0, x), or (1-x, x, 0), respectively. For quad
|
|
tessellation, if the subdivision generates a vertex with coordinates of (x,
|
|
0) or (0, x), it will also generate a vertex with coordinates of exactly
|
|
(1-x, 0) or (0, 1-x), respectively. For isoline tessellation, if it
|
|
generates vertices at (0, x) and (1, x) where x is not zero, it will also
|
|
generate vertices at exactly (0, 1-x) and (1, 1-x), respectively._
|
|
|
|
*Rule 4* _The set of vertices generated when subdividing outer edges in
|
|
triangular and quad tessellation must: be independent of the specific edge
|
|
subdivided, given identical outer tessellation levels and spacing. For
|
|
example, if vertices at (x, 1 - x, 0) and (1-x, x, 0) are generated when
|
|
subdividing the w = 0 edge in triangular tessellation, vertices must: be
|
|
generated at (x, 0, 1-x) and (1-x, 0, x) when subdividing an otherwise
|
|
identical v = 0 edge. For quad tessellation, if vertices at (x, 0) and
|
|
(1-x, 0) are generated when subdividing the v = 0 edge, vertices must: be
|
|
generated at (0, x) and (0, 1-x) when subdividing an otherwise identical
|
|
u = 0 edge._
|
|
|
|
*Rule 5* _When processing two patches that are identical in all respects
|
|
enumerated in rule 1 except for vertex order, the set of triangles generated
|
|
for triangle and quad tessellation must: be identical except for vertex and
|
|
triangle order. For each triangle n1 produced by processing the first patch,
|
|
there must: be a triangle n2 produced when processing the second patch each
|
|
of whose vertices has the same tessellation coordinates as one of the
|
|
vertices in n1._
|
|
|
|
*Rule 6* _When processing two patches that are identical in all respects
|
|
enumerated in rule 1 other than matching outer tessellation levels and/or
|
|
vertex order, the set of interior triangles generated for triangle and quad
|
|
tessellation must: be identical in all respects except for vertex and
|
|
triangle order. For each interior triangle n1 produced by processing the
|
|
first patch, there must: be a triangle n2 produced when processing the
|
|
second patch each of whose vertices has the same tessellation coordinates as
|
|
one of the vertices in n1. A triangle produced by the tessellator is
|
|
considered an interior triangle if none of its vertices lie on an outer edge
|
|
of the subdivided primitive._
|
|
|
|
*Rule 7* _For quad and triangle tessellation, the set of triangles
|
|
connecting an inner and outer edge depends only on the inner and outer
|
|
tessellation levels corresponding to that edge and the spacing decorations._
|
|
|
|
*Rule 8* _The value of all defined components of_ code:TessCoord
|
|
_will be in the range [0, 1]. Additionally, for any defined component x of_
|
|
code:TessCoord, _the results of computing 1.0-x in a tessellation
|
|
evaluation shader will be exact. If any floating-point values in the range
|
|
[0, 1] fail to satisfy this property, such values must: not be used as
|
|
tessellation coordinate components._
|