1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[appendix] 6[[invariance]] 7= Invariance 8 9The Vulkan specification is not pixel exact. 10It therefore does not guarantee an exact match between images produced by 11different Vulkan implementations. 12However, the specification does specify exact matches, in some cases, for 13images produced by the same implementation. 14The purpose of this appendix is to identify and provide justification for 15those cases that require exact matches. 16 17== Repeatability 18 19The obvious and most fundamental case is repeated issuance of a series of 20Vulkan commands. 21For any given Vulkan and framebuffer state vector, and for any Vulkan 22command, the resulting Vulkan and framebuffer state must: be identical 23whenever the command is executed on that initial Vulkan and framebuffer 24state. 25This repeatability requirement does not apply when using shaders containing 26side effects (image and buffer variable stores and atomic operations), 27because these memory operations are not guaranteed to be processed in a 28defined order. 29 30ifdef::VK_AMD_rasterization_order[] 31The repeatability requirement does not apply for rendering done using a 32graphics pipeline that uses ename:VK_RASTERIZATION_ORDER_RELAXED_AMD. 33endif::VK_AMD_rasterization_order[] 34 35One purpose of repeatability is avoidance of visual artifacts when a 36double-buffered scene is redrawn. 37If rendering is not repeatable, swapping between two buffers rendered with 38the same command sequence may: result in visible changes in the image. 39Such false motion is distracting to the viewer. 40Another reason for repeatability is testability. 41 42Repeatability, while important, is a weak requirement. 43Given only repeatability as a requirement, two scenes rendered with one 44(small) polygon changed in position might differ at every pixel. 45Such a difference, while within the law of repeatability, is certainly not 46within its spirit. 47Additional invariance rules are desirable to ensure useful operation. 48 49 50== Multi-pass Algorithms 51 52Invariance is necessary for a whole set of useful multi-pass algorithms. 53Such algorithms render multiple times, each time with a different Vulkan 54mode vector, to eventually produce a result in the framebuffer. 55Examples of these algorithms include: 56 57 * "`Erasing`" a primitive from the framebuffer by redrawing it, either in 58 a different color or using the XOR logical operation. 59 * Using stencil operations to compute capping planes. 60 61 62== Invariance Rules 63 64For a given Vulkan device: 65 66*Rule 1* _For any given Vulkan and framebuffer state vector, and for any 67given Vulkan command, the resulting Vulkan and framebuffer state must: be 68identical each time the command is executed on that initial Vulkan and 69framebuffer state._ 70 71*Rule 2* _Changes to the following state values have no side effects (the 72use of any other state value is not affected by the change):_ 73 74*Required:* 75 76 * _Color and depth/stencil attachment contents_ 77 * _Scissor parameters (other than enable)_ 78 * _Write masks (color, depth, stencil)_ 79 * _Clear values (color, depth, stencil)_ 80 81*Strongly suggested:* 82 83 * _Stencil parameters (other than enable)_ 84 * _Depth test parameters (other than enable)_ 85 * _Blend parameters (other than enable)_ 86 * _Logical operation parameters (other than enable)_ 87 88*Corollary 1* _Fragment generation is invariant with respect to the state 89values listed in Rule 2._ 90 91*Rule 3* _The arithmetic of each per-fragment operation is invariant except 92with respect to parameters that directly control it._ 93 94*Corollary 2* _Images rendered into different color attachments of the same 95framebuffer, either simultaneously or separately using the same command 96sequence, are pixel identical._ 97 98*Rule 4* _Identical pipelines will produce the same result when run multiple 99times with the same input. 100The wording "`Identical pipelines`" means slink:VkPipeline objects that have 101been created with identical SPIR-V binaries and identical state, which are 102then used by commands executed using the same Vulkan state vector. 103Invariance is relaxed for shaders with side effects, such as performing 104stores or atomics._ 105 106*Rule 5* _All fragment shaders that either conditionally or unconditionally 107assign_ code:FragCoord.z _to_ code:FragDepth _are depth-invariant with 108respect to each other, for those fragments where the assignment to_ 109code:FragDepth _actually is done._ 110 111If a sequence of Vulkan commands specifies primitives to be rendered with 112shaders containing side effects (image and buffer variable stores and atomic 113operations), invariance rules are relaxed. 114In particular, rule 1, corollary 2, and rule 4 do not apply in the presence 115of shader side effects. 116 117The following weaker versions of rules 1 and 4 apply to Vulkan commands 118involving shader side effects: 119 120*Rule 6* _For any given Vulkan and framebuffer state vector, and for any 121given Vulkan command, the contents of any framebuffer state not directly or 122indirectly affected by results of shader image or buffer variable stores or 123atomic operations must: be identical each time the command is executed on 124that initial Vulkan and framebuffer state._ 125 126*Rule 7* _Identical pipelines will produce the same result when run multiple 127times with the same input as long as:_ 128 129 * _shader invocations do not use image atomic operations;_ 130 * _no framebuffer memory is written to more than once by image stores, 131 unless all such stores write the same value; and_ 132 * _no shader invocation, or other operation performed to process the 133 sequence of commands, reads memory written to by an image store._ 134 135 136[NOTE] 137.Note 138==== 139The OpenGL specification has the following invariance rule: Consider a 140primitive p' obtained by translating a primitive p through an offset (x, y) 141in window coordinates, where x and y are integers. 142As long as neither p' nor p is clipped, it must: be the case that each 143fragment f' produced from p' is identical to a corresponding fragment f from 144p except that the center of f' is offset by (x, y) from the center of f. 145 146This rule does not apply to Vulkan and is an intentional difference from 147OpenGL. 148==== 149 150When any sequence of Vulkan commands triggers shader invocations that 151perform image stores or atomic operations, and subsequent Vulkan commands 152read the memory written by those shader invocations, these operations must: 153be explicitly synchronized. 154 155 156== Tessellation Invariance 157 158When using a pipeline containing tessellation evaluation shaders, the 159fixed-function tessellation primitive generator consumes the input patch 160specified by an application and emits a new set of primitives. 161The following invariance rules are intended to provide repeatability 162guarantees. 163Additionally, they are intended to allow an application with a carefully 164crafted tessellation evaluation shader to ensure that the sets of triangles 165generated for two adjacent patches have identical vertices along shared 166patch edges, avoiding "`cracks`" caused by minor differences in the 167positions of vertices along shared edges. 168 169*Rule 1* _When processing two patches with identical outer and inner 170tessellation levels, the tessellation primitive generator will emit an 171identical set of point, line, or triangle primitives as long as the pipeline 172used to process the patch primitives has tessellation evaluation shaders 173specifying the same tessellation mode, spacing, vertex order, and point mode 174decorations. 175Two sets of primitives are considered identical if and only if they contain 176the same number and type of primitives and the generated tessellation 177coordinates for the vertex numbered m of the primitive numbered n are 178identical for all values of m and n._ 179 180*Rule 2* _The set of vertices generated along the outer edge of the 181subdivided primitive in triangle and quad tessellation, and the tessellation 182coordinates of each, depend only on the corresponding outer tessellation 183level and the spacing decorations in the tessellation shaders of the 184pipeline._ 185 186*Rule 3* _The set of vertices generated when subdividing any outer primitive 187edge is always symmetric. 188For triangle tessellation, if the subdivision generates a vertex with 189tessellation coordinates of the form (0, x, 1-x), (x, 0, 1-x), or (x, 1-x, 1900), it will also generate a vertex with coordinates of exactly (0, 1-x, x), 191(1-x, 0, x), or (1-x, x, 0), respectively. 192For quad tessellation, if the subdivision generates a vertex with 193coordinates of (x, 0) or (0, x), it will also generate a vertex with 194coordinates of exactly (1-x, 0) or (0, 1-x), respectively. 195For isoline tessellation, if it generates vertices at (0, x) and (1, x) 196where x is not zero, it will also generate vertices at exactly (0, 1-x) and 197(1, 1-x), respectively._ 198 199*Rule 4* _The set of vertices generated when subdividing outer edges in 200triangular and quad tessellation must: be independent of the specific edge 201subdivided, given identical outer tessellation levels and spacing. 202For example, if vertices at (x, 1 - x, 0) and (1-x, x, 0) are generated when 203subdividing the w = 0 edge in triangular tessellation, vertices must: be 204generated at (x, 0, 1-x) and (1-x, 0, x) when subdividing an otherwise 205identical v = 0 edge. 206For quad tessellation, if vertices at (x, 0) and (1-x, 0) are generated when 207subdividing the v = 0 edge, vertices must: be generated at (0, x) and (0, 2081-x) when subdividing an otherwise identical u = 0 edge._ 209 210*Rule 5* _When processing two patches that are identical in all respects 211enumerated in rule 1 except for vertex order, the set of triangles generated 212for triangle and quad tessellation must: be identical except for vertex and 213triangle order. 214For each triangle n1 produced by processing the first patch, there must: be 215a triangle n2 produced when processing the second patch each of whose 216vertices has the same tessellation coordinates as one of the vertices in 217n1._ 218 219*Rule 6* _When processing two patches that are identical in all respects 220enumerated in rule 1 other than matching outer tessellation levels and/or 221vertex order, the set of interior triangles generated for triangle and quad 222tessellation must: be identical in all respects except for vertex and 223triangle order. 224For each interior triangle n1 produced by processing the first patch, there 225must: be a triangle n2 produced when processing the second patch each of 226whose vertices has the same tessellation coordinates as one of the vertices 227in n1. 228A triangle produced by the tessellator is considered an interior triangle if 229none of its vertices lie on an outer edge of the subdivided primitive._ 230 231*Rule 7* _For quad and triangle tessellation, the set of triangles 232connecting an inner and outer edge depends only on the inner and outer 233tessellation levels corresponding to that edge and the spacing decorations._ 234 235*Rule 8* _The value of all defined components of_ code:TessCoord _will be in 236the range [0, 1]. 237Additionally, for any defined component x of_ code:TessCoord, _the results 238of computing 1.0-x in a tessellation evaluation shader will be exact. 239If any floating-point values in the range [0, 1] fail to satisfy this 240property, such values must: not be used as tessellation coordinate 241components._ 242