1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[interfaces]] 6= Shader Interfaces 7 8When a pipeline is created, the set of shaders specified in the 9corresponding stext:Vk*PipelineCreateInfo structure are implicitly linked at 10a number of different interfaces. 11 12 * <<interfaces-iointerfaces,Shader Input and Output Interface>> 13 * <<interfaces-vertexinput,Vertex Input Interface>> 14 * <<interfaces-fragmentoutput,Fragment Output Interface>> 15 * <<interfaces-inputattachment,Fragment Input Attachment Interface>> 16 * <<interfaces-resources,Shader Resource Interface>> 17 18Interface definitions make use of the following SPIR-V decorations: 19 20 * code:DescriptorSet and code:Binding 21 * code:Location, code:Component, and code:Index 22 * code:Flat, code:NoPerspective, code:Centroid, and code:Sample 23 * code:Block and code:BufferBlock 24 * code:InputAttachmentIndex 25 * code:Offset, code:ArrayStride, and code:MatrixStride 26 * code:BuiltIn 27ifdef::VK_NV_geometry_shader_passthrough[] 28 * <<geometry-passthrough-passthrough,code:PassthroughNV>> 29endif::VK_NV_geometry_shader_passthrough[] 30 31 32This specification describes valid uses for Vulkan of these decorations. 33Any other use of one of these decorations is invalid. 34 35[[interfaces-iointerfaces]] 36== Shader Input and Output Interfaces 37 38When multiple stages are present in a pipeline, the outputs of one stage 39form an interface with the inputs of the next stage. 40When such an interface involves a shader, shader outputs are matched against 41the inputs of the next stage, and shader inputs are matched against the 42outputs of the previous stage. 43 44There are two classes of variables that can: be matched between shader 45stages, built-in variables and user-defined variables. 46Each class has a different set of matching criteria. 47Generally, when non-shader stages are between shader stages, the 48user-defined variables, and most built-in variables, form an interface 49between the shader stages. 50 51The variables forming the input or output _interfaces_ are listed as 52operands to the code:OpEntryPoint instruction and are declared with the 53code:Input or code:Output storage classes, respectively, in the SPIR-V 54module. 55 56code:Output variables of a shader stage have undefined values until the 57shader writes to them or uses the code:Initializer operand when declaring 58the variable. 59 60 61[[interfaces-iointerfaces-builtin]] 62=== Built-in Interface Block 63 64Shader <<interfaces-builtin-variables,built-in>> variables meeting the 65following requirements define the _built-in interface block_. 66They must: 67 68 * be explicitly declared (there are no implicit built-ins), 69 * be identified with a code:BuiltIn decoration, 70 * form object types as described in the 71 <<interfaces-builtin-variables,Built-in Variables>> section, and 72 * be declared in a block whose top-level members are the built-ins. 73 74Built-ins only participate in interface matching if they are declared in 75such a block. 76They must: not have any code:Location or code:Component decorations. 77 78There must: be no more than one built-in interface block per shader per 79interface. 80 81 82[[interfaces-iointerfaces-user]] 83=== User-defined Variable Interface 84 85The remaining variables listed by code:OpEntryPoint with the code:Input or 86code:Output storage class form the _user-defined variable interface_. 87ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 88By default such variables have a type with a width of 32 or 64. 89If an implementation supports 90<<features-features-storageInputOutput16,storageInputOutput16>>, 91user-defined variables in the code:Input and code:Output storage classes 92can: also have types with a width of 16. 93endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 94These variables must: be identified with a code:Location decoration and can: 95also be identified with a code:Component decoration. 96 97 98[[interfaces-iointerfaces-matching]] 99=== Interface Matching 100 101A user-defined output variable is considered to match an input variable in 102the subsequent stage if the two variables are declared with the same 103code:Location and code:Component decoration and match in type and 104decoration, except that <<shaders-interpolation-decorations,interpolation 105decorations>> are not required: to match. 106For the purposes of interface matching, variables declared without a 107code:Component decoration are considered to have a code:Component decoration 108of zero. 109 110ifdef::VK_NV_geometry_shader_passthrough[] 111[NOTE] 112.Note 113==== 114Matching rules for _passthrough geometry shaders_ are slightly different and 115are described in the <<geometry-passthrough-interface,Passthrough Interface 116Matching>> section. 117==== 118 119endif::VK_NV_geometry_shader_passthrough[] 120Variables or block members declared as structures are considered to match in 121type if and only if the structure members match in type, decoration, number, 122and declaration order. 123Variables or block members declared as arrays are considered to match in 124type only if both declarations specify the same element type and size. 125 126Tessellation control shader per-vertex output variables and blocks, and 127tessellation control, tessellation evaluation, and geometry shader 128per-vertex input variables and blocks are required to be declared as arrays, 129with each element representing input or output values for a single vertex of 130a multi-vertex primitive. 131For the purposes of interface matching, the outermost array dimension of 132such variables and blocks is ignored. 133 134At an interface between two non-fragment shader stages, the built-in 135interface block must: match exactly, as described above. 136At an interface involving the fragment shader inputs, the presence or 137absence of any built-in output does not affect the interface matching. 138 139At an interface between two shader stages, the user-defined variable 140interface must: match exactly, as described above. 141 142Any input value to a shader stage is well-defined as long as the preceding 143stages writes to a matching output, as described above. 144 145Additionally, scalar and vector inputs are well-defined if there is a 146corresponding output satisfying all of the following conditions: 147 148 * the input and output match exactly in decoration, 149 * the output is a vector with the same basic type and has at least as many 150 components as the input, and 151 * the common component type of the input and output is 152ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 153 16-bit integer or floating-point, or 154endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 155 32-bit integer or floating-point (64-bit component types are excluded). 156 157In this case, the components of the input will be taken from the first 158components of the output, and any extra components of the output will be 159ignored. 160 161 162[[interfaces-iointerfaces-locations]] 163=== Location Assignment 164 165This section describes how many locations are consumed by a given type. 166As mentioned above, geometry shader inputs, tessellation control shader 167inputs and outputs, and tessellation evaluation inputs all have an 168additional level of arrayness relative to other shader inputs and outputs. 169This outer array level is removed from the type before considering how many 170locations the type consumes. 171 172The code:Location value specifies an interface slot comprised of a 32-bit 173four-component vector conveyed between stages. 174The code:Component specifies 175<<interfaces-iointerfaces-components,components>> within these vector 176locations. 177Only types with widths of 178ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 17916, 180endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 18132 or 64 are supported in shader interfaces. 182 183Inputs and outputs of the following types consume a single interface 184location: 185 186ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 187 * 16-bit scalar and vector types, and 188endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 189 * 32-bit scalar and vector types, and 190 * 64-bit scalar and 2-component vector types. 191 19264-bit three- and four-component vectors consume two consecutive locations. 193 194If a declared input or output is an array of size _n_ and each element takes 195_m_ locations, it will be assigned _m_ {times} _n_ consecutive locations 196starting with the location specified. 197 198If the declared input or output is an _n_ {times} _m_ 199ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 20016-, 201endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 20232- or 64-bit matrix, it will be assigned multiple locations starting with 203the location specified. 204The number of locations assigned for each matrix will be the same as for an 205_n_-element array of _m_-component vectors. 206 207The layout of a structure type used as an code:Input or code:Output depends 208on whether it is also a code:Block (i.e. has a code:Block decoration). 209 210If it is a not a code:Block, then the structure type must: have a 211code:Location decoration. 212Its members are assigned consecutive locations in their declaration order, 213with the first member assigned to the location specified for the structure 214type. 215The members, and their nested types, must: not themselves have code:Location 216decorations. 217 218If the structure type is a code:Block but without a code:Location, then each 219of its members must: have a code:Location decoration. 220If it is a code:Block with a code:Location decoration, then its members are 221assigned consecutive locations in declaration order, starting from the first 222member which is initially assigned the location specified for the 223code:Block. 224Any member with its own code:Location decoration is assigned that location. 225Each remaining member is assigned the location after the immediately 226preceding member in declaration order. 227 228The locations consumed by block and structure members are determined by 229applying the rules above in a depth-first traversal of the instantiated 230members as though the structure or block member were declared as an input or 231output variable of the same type. 232 233Any two inputs listed as operands on the same code:OpEntryPoint must: not be 234assigned the same location, either explicitly or implicitly. 235Any two outputs listed as operands on the same code:OpEntryPoint must: not 236be assigned the same location, either explicitly or implicitly. 237 238The number of input and output locations available for a shader input or 239output interface are limited, and dependent on the shader stage as described 240in <<interfaces-iointerfaces-limits>>. 241All variables in both the <<interfaces-builtin-variables,built-in interface 242block>> and the <<interfaces-iointerfaces-user,user-defined variable 243interface>> count against these limits. 244 245 246[[interfaces-iointerfaces-limits]] 247.Shader Input and Output Locations 248[width="90%",cols="<6,<13",options="header"] 249|==== 250| Shader Interface | Locations Available 251| vertex input | pname:maxVertexInputAttributes 252| vertex output | pname:maxVertexOutputComponents / 4 253| tessellation control input | pname:maxTessellationControlPerVertexInputComponents / 4 254| tessellation control output | pname:maxTessellationControlPerVertexOutputComponents / 4 255| tessellation evaluation input | pname:maxTessellationEvaluationInputComponents / 4 256| tessellation evaluation output| pname:maxTessellationEvaluationOutputComponents / 4 257| geometry input | pname:maxGeometryInputComponents / 4 258| geometry output | pname:maxGeometryOutputComponents / 4 259| fragment input | pname:maxFragmentInputComponents / 4 260| fragment output | pname:maxFragmentOutputAttachments 261|==== 262 263 264[[interfaces-iointerfaces-components]] 265=== Component Assignment 266 267The code:Component decoration allows the code:Location to be more finely 268specified for scalars and vectors, down to the individual components within 269a location that are consumed. 270The components within a location are 0, 1, 2, and 3. 271A variable or block member starting at component N will consume components 272N, N+1, N+2, ... 273up through its size. 274ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 275For 16-, and 32-bit types, 276endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 277ifndef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 278For single precision types, 279endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 280it is invalid if this sequence of components gets larger than 3. 281A scalar 64-bit type will consume two of these components in sequence, and a 282two-component 64-bit vector type will consume all four components available 283within a location. 284A three- or four-component 64-bit vector type must: not specify a 285code:Component decoration. 286A three-component 64-bit vector type will consume all four components of the 287first location and components 0 and 1 of the second location. 288This leaves components 2 and 3 available for other component-qualified 289declarations. 290 291A scalar or two-component 64-bit data type must: not specify a 292code:Component decoration of 1 or 3. 293A code:Component decoration must: not be specified for any type that is not 294a scalar or vector. 295 296 297[[interfaces-vertexinput]] 298== Vertex Input Interface 299 300When the vertex stage is present in a pipeline, the vertex shader input 301variables form an interface with the vertex input attributes. 302The vertex shader input variables are matched by the code:Location and 303code:Component decorations to the vertex input attributes specified in the 304pname:pVertexInputState member of the slink:VkGraphicsPipelineCreateInfo 305structure. 306 307The vertex shader input variables listed by code:OpEntryPoint with the 308code:Input storage class form the _vertex input interface_. 309These variables must: be identified with a code:Location decoration and can: 310also be identified with a code:Component decoration. 311 312For the purposes of interface matching: variables declared without a 313code:Component decoration are considered to have a code:Component decoration 314of zero. 315The number of available vertex input locations is given by the 316pname:maxVertexInputAttributes member of the sname:VkPhysicalDeviceLimits 317structure. 318 319See <<fxvertex-attrib-location>> for details. 320 321All vertex shader inputs declared as above must: have a corresponding 322attribute and binding in the pipeline. 323 324 325[[interfaces-fragmentoutput]] 326== Fragment Output Interface 327 328When the fragment stage is present in a pipeline, the fragment shader 329outputs form an interface with the output attachments of the current 330subpass. 331The fragment shader output variables are matched by the code:Location and 332code:Component decorations to the color attachments specified in the 333pname:pColorAttachments array of the slink:VkSubpassDescription structure 334that describes the subpass that the fragment shader is executed in. 335 336The fragment shader output variables listed by code:OpEntryPoint with the 337code:Output storage class form the _fragment output interface_. 338These variables must: be identified with a code:Location decoration. 339They can: also be identified with a code:Component decoration and/or an 340code:Index decoration. 341For the purposes of interface matching: variables declared without a 342code:Component decoration are considered to have a code:Component decoration 343of zero, and variables declared without an code:Index decoration are 344considered to have an code:Index decoration of zero. 345 346A fragment shader output variable identified with a code:Location decoration 347of _i_ is directed to the color attachment indicated by 348pname:pColorAttachments[_i_], after passing through the blending unit as 349described in <<framebuffer-blending>>, if enabled. 350Locations are consumed as described in 351<<interfaces-iointerfaces-locations,Location Assignment>>. 352The number of available fragment output locations is given by the 353pname:maxFragmentOutputAttachments member of the 354sname:VkPhysicalDeviceLimits structure. 355 356Components of the output variables are assigned as described in 357<<interfaces-iointerfaces-components,Component Assignment>>. 358Output components identified as 0, 1, 2, and 3 will be directed to the R, G, 359B, and A inputs to the blending unit, respectively, or to the output 360attachment if blending is disabled. 361If two variables are placed within the same location, they must: have the 362same underlying type (floating-point or integer). 363The input to blending or color attachment writes is undefined for components 364which do not correspond to a fragment shader output. 365 366Fragment outputs identified with an code:Index of zero are directed to the 367first input of the blending unit associated with the corresponding 368code:Location. 369Outputs identified with an code:Index of one are directed to the second 370input of the corresponding blending unit. 371 372No _component aliasing_ of output variables is allowed, that is there must: 373not be two output variables which have the same location, component, and 374index, either explicitly declared or implied. 375 376Output values written by a fragment shader must: be declared with either 377code:OpTypeFloat or code:OpTypeInt, and a Width of 32. 378ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 379If pname:storageInputOutput16 is supported, output values written by a 380fragment shader can: be also declared with either code:OpTypeFloat or 381code:OpTypeInt and a Width of 16. 382endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 383Composites of these types are also permitted. 384If the color attachment has a signed or unsigned normalized fixed-point 385format, color values are assumed to be floating-point and are converted to 386fixed-point as described in <<fundamentals-fpfixedconv>>; If the color 387attachment has an integer format, color values are assumed to be integers 388and converted to the bit-depth of the target. 389Any value that cannot be represented in the attachment's format is 390undefined. 391For any other attachment format no conversion is performed. 392If the type of the values written by the fragment shader do not match the 393format of the corresponding color attachment, the result is undefined for 394those components. 395 396 397[[interfaces-inputattachment]] 398== Fragment Input Attachment Interface 399 400When a fragment stage is present in a pipeline, the fragment shader subpass 401inputs form an interface with the input attachments of the current subpass. 402The fragment shader subpass input variables are matched by 403code:InputAttachmentIndex decorations to the input attachments specified in 404the pname:pInputAttachments array of the slink:VkSubpassDescription 405structure that describes the subpass that the fragment shader is executed 406in. 407 408The fragment shader subpass input variables with the code:UniformConstant 409storage class and a decoration of code:InputAttachmentIndex that are 410statically used by code:OpEntryPoint form the _fragment input attachment 411interface_. 412These variables must: be declared with a type of code:OpTypeImage, a 413code:Dim operand of code:SubpassData, and a code:Sampled operand of 2. 414 415A subpass input variable identified with an code:InputAttachmentIndex 416decoration of _i_ reads from the input attachment indicated by 417pname:pInputAttachments[_i_] member of sname:VkSubpassDescription. 418If the subpass input variable is declared as an array of size N, it consumes 419N consecutive input attachments, starting with the index specified. 420There must: not be more than one input variable with the same 421code:InputAttachmentIndex whether explicitly declared or implied by an array 422declaration. 423The number of available input attachment indices is given by the 424pname:maxPerStageDescriptorInputAttachments member of the 425sname:VkPhysicalDeviceLimits structure. 426 427Variables identified with the code:InputAttachmentIndex must: only be used 428by a fragment stage. 429The basic data type (floating-point, integer, unsigned integer) of the 430subpass input must: match the basic format of the corresponding input 431attachment, or the values of subpass loads from these variables are 432undefined. 433 434See <<descriptorsets-inputattachment>> for more details. 435 436 437[[interfaces-resources]] 438== Shader Resource Interface 439 440When a shader stage accesses buffer or image resources, as described in the 441<<descriptorsets,Resource Descriptors>> section, the shader resource 442variables must: be matched with the <<descriptorsets-pipelinelayout,pipeline 443layout>> that is provided at pipeline creation time. 444 445The set of shader resources that form the _shader resource interface_ for a 446stage are the variables statically used by code:OpEntryPoint with the 447storage class of code:Uniform, code:UniformConstant, or code:PushConstant. 448For the fragment shader, this includes the <<interfaces-inputattachment, 449fragment input attachment interface>>. 450 451The shader resource interface consists of two sub-interfaces: the push 452constant interface and the descriptor set interface. 453 454 455[[interfaces-resources-pushconst]] 456=== Push Constant Interface 457 458The shader variables defined with a storage class of code:PushConstant that 459are statically used by the shader entry points for the pipeline define the 460_push constant interface_. 461They must: be: 462 463 * typed as code:OpTypeStruct, 464 * identified with a code:Block decoration, and 465 * laid out explicitly using the code:Offset, code:ArrayStride, and 466 code:MatrixStride decorations as specified in 467 <<interfaces-resources-layout,Offset and Stride Assignment>>. 468 469There must: be no more than one push constant block statically used per 470shader entry point. 471 472Each variable in a push constant block must: be placed at an code:Offset 473such that the entire constant value is entirely contained within the 474slink:VkPushConstantRange for each code:OpEntryPoint that uses it, and the 475pname:stageFlags for that range must: specify the appropriate 476elink:VkShaderStageFlagBits for that stage. 477The code:Offset decoration for any variable in a push constant block must: 478not cause the space required for that variable to extend outside the range 479[eq]#[0, pname:maxPushConstantsSize)#. 480 481Any variable in a push constant block that is declared as an array must: 482only be accessed with _dynamically uniform_ indices. 483 484 485[[interfaces-resources-descset]] 486=== Descriptor Set Interface 487 488The _descriptor set interface_ is comprised of the shader variables with the 489storage class of code:Uniform or code:UniformConstant (including the 490variables in the <<interfaces-inputattachment,fragment input attachment 491interface>>) that are statically used by the shader entry points for the 492pipeline. 493 494These variables must: have code:DescriptorSet and code:Binding decorations 495specified, which are assigned and matched with the 496sname:VkDescriptorSetLayout objects in the pipeline layout as described in 497<<interfaces-resources-setandbinding,DescriptorSet and Binding Assignment>>. 498 499Variables identified with the code:UniformConstant storage class are used 500only as handles to refer to opaque resources. 501Such variables must: be typed as code:OpTypeImage, code:OpTypeSampler, 502code:OpTypeSampledImage, or an array of one of these types. 503 504The code:Sampled code:Type of an code:OpTypeImage declaration must: match 505the same basic data type as the corresponding resource, or the values 506obtained by reading or sampling from this image are undefined. 507 508The code:Image code:Format of an code:OpTypeImage declaration must: not be 509*Unknown*, for variables which are used for code:OpImageRead, 510code:OpImageSparseRead, or code:OpImageWrite operations, except under the 511following conditions: 512 513 * For code:OpImageWrite, if the pname:shaderStorageImageWriteWithoutFormat 514 feature is enabled and the shader module declares the 515 code:StorageImageWriteWithoutFormat capability. 516 * For code:OpImageRead or code:OpImageSparseRead, if the 517 pname:shaderStorageImageReadWithoutFormat feature is enabled and the 518 shader module declares the code:StorageImageReadWithoutFormat 519 capability. 520 521The code:Image code:Format of an code:OpTypeImage declaration must: not be 522*Unknown*, for variables which are used for code:OpAtomic* operations. 523 524Variables identified with the code:Uniform storage class are used to access 525transparent buffer backed resources. 526Such variables must: be: 527 528 * typed as code:OpTypeStruct, or an array of this type, 529 * identified with a code:Block or code:BufferBlock decoration, and 530 * laid out explicitly using the code:Offset, code:ArrayStride, and 531 code:MatrixStride decorations as specified in 532 <<interfaces-resources-layout,Offset and Stride Assignment>>. 533 534ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 535Variables identified with the code:StorageBuffer storage class are used to 536access transparent buffer backed resources. 537Such variables must: be: 538 539 * typed as code:OpTypeStruct, or an array of this type, 540 * identified with a code:Block decoration, and 541 * laid out explicitly using the code:Offset, code:ArrayStride, and 542 code:MatrixStride decorations as specified in 543 <<interfaces-resources-layout,Offset and Stride Assignment>>. 544endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 545 546ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 547The code:Offset decoration for any variable in a code:Block must: not cause 548the space required for that variable to extend outside the range [eq]#[0, 549pname:maxUniformBufferRange)#. 550The code:Offset decoration for any variable in a code:BufferBlock must: not 551cause the space required for that variable to extend outside the range 552[eq]#[0, pname:maxStorageBufferRange)#. 553endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 554 555ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 556The code:Offset decoration for any member of a code:Block-decorated variable 557in the code:Uniform storage class must: not cause the space required for 558that variable to extend outside the range [eq]#[0, 559pname:maxUniformBufferRange)#. 560The code:Offset decoration for any member of a code:Block-decorated variable 561in the code:StorageBuffer storage class must: not cause the space required 562for that variable to extend outside the range [eq]#[0, 563pname:maxStorageBufferRange)#. 564endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 565 566Variables identified with a storage class of code:UniformConstant and a 567decoration of code:InputAttachmentIndex must: be declared as described in 568<<interfaces-inputattachment,Fragment Input Attachment Interface>>. 569 570SPIR-V variables decorated with a descriptor set and binding that identify a 571<<descriptorsets-combinedimagesampler, combined image sampler descriptor>> 572can: have a type of code:OpTypeImage, code:OpTypeSampler (code:Sampled=1), 573or code:OpTypeSampledImage. 574 575Arrays of any of these types can: be indexed with constant integral 576expressions. 577The following features must: be enabled and capabilities must: be declared 578in order to index such arrays with dynamically uniform or non-uniform 579indices: 580 581 * Storage images (except storage texel buffers and input attachments): 582 ** Dynamically uniform: pname:shaderStorageImageArrayDynamicIndexing and 583 code:StorageImageArrayDynamicIndexing 584ifdef::VK_EXT_descriptor_indexing[] 585 ** Non-uniform: pname:shaderStorageImageArrayNonUniformIndexing and 586 code:StorageImageArrayNonUniformIndexingEXT 587 * Storage texel buffers: 588 ** Dynamically uniform: pname:shaderStorageTexelBufferArrayDynamicIndexing 589 and code:StorageTexelBufferArrayDynamicIndexingEXT 590 ** Non-uniform: pname:shaderStorageTexelBufferArrayNonUniformIndexing and 591 code:StorageTexelBufferArrayNonUniformIndexingEXT 592 * Input attachments: 593 ** Dynamically uniform: pname:shaderInputAttachmentArrayDynamicIndexing 594 and code:InputAttachmentArrayDynamicIndexingEXT 595 ** Non-uniform: pname:shaderInputAttachmentArrayNonUniformIndexing and 596 code:InputAttachmentArrayNonUniformIndexingEXT 597endif::VK_EXT_descriptor_indexing[] 598 * Sampled images (except uniform texel buffers): 599 ** Dynamically uniform: pname:shaderSampledImageArrayDynamicIndexing and 600 code:SampledImageArrayDynamicIndexing 601ifdef::VK_EXT_descriptor_indexing[] 602 ** Non-uniform: pname:shaderSampledImageArrayNonUniformIndexing and 603 code:SampledImageArrayNonUniformIndexingEXT 604 * Uniform texel buffers: 605 ** Dynamically uniform: pname:shaderUniformTexelBufferArrayDynamicIndexing 606 and code:UniformTexelBufferArrayDynamicIndexingEXT 607 ** Non-uniform: pname:shaderUniformTexelBufferArrayNonUniformIndexing and 608 code:UniformTexelBufferArrayNonUniformIndexingEXT 609endif::VK_EXT_descriptor_indexing[] 610 * Uniform buffers: 611 ** Dynamically uniform: pname:shaderUniformBufferArrayDynamicIndexing and 612 code:UniformBufferArrayDynamicIndexing 613ifdef::VK_EXT_descriptor_indexing[] 614 ** Non-uniform: pname:shaderUniformBufferArrayNonUniformIndexing and 615 code:UniformBufferArrayNonUniformIndexingEXT 616endif::VK_EXT_descriptor_indexing[] 617 * Storage buffers: 618 ** Dynamically uniform: pname:shaderStorageBufferArrayDynamicIndexing and 619 code:StorageBufferArrayDynamicIndexing 620ifdef::VK_EXT_descriptor_indexing[] 621 ** Non-uniform: pname:shaderStorageBufferArrayNonUniformIndexing and 622 code:StorageBufferArrayNonUniformIndexingEXT 623endif::VK_EXT_descriptor_indexing[] 624 625ifdef::VK_EXT_descriptor_indexing[] 626If an instruction loads from or stores to a resource (including atomics and 627image instructions) and the resource descriptor being accessed is not 628dynamically uniform, then the corresponding non-uniform indexing feature 629must: be enabled and the capability must: be declared. 630endif::VK_EXT_descriptor_indexing[] 631If an instruction loads from or stores to a resource (including atomics and 632image instructions) and the resource descriptor being accessed is not 633uniform, then the corresponding dynamic indexing 634ifdef::VK_EXT_descriptor_indexing[] 635or non-uniform 636endif::VK_EXT_descriptor_indexing[] 637feature must: be enabled and the capability must: be declared. 638 639ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 640If sampler Y'C~B~C~R~ conversion is enabled, the combined image sampler 641must: be indexed only by constant integral expressions when aggregated into 642arrays in shader code, irrespective of the 643pname:shaderSampledImageArrayDynamicIndexing feature. 644endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 645 646[[interfaces-resources-correspondence]] 647.Shader Resource and Descriptor Type Correspondence 648[width="90%",cols="<1,<2",options="header"] 649|==== 650| Resource type | Descriptor Type 651| sampler | ename:VK_DESCRIPTOR_TYPE_SAMPLER or 652 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 653| sampled image | ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 654 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 655| storage image | ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE 656| combined image sampler | ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 657| uniform texel buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 658| storage texel buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER 659| uniform buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 660 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC 661| storage buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 662 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 663| input attachment | ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 664|==== 665 666[[interfaces-resources-storage-class-correspondence]] 667.Shader Resource and Storage Class Correspondence 668[width="100%",cols="<21%,<22%,<27%,<30%",options="header"] 669|==== 670| Resource type | Storage Class | Type | Decoration(s)^1^ 671| sampler 672 | code:UniformConstant | code:OpTypeSampler | 673| sampled image 674 | code:UniformConstant | code:OpTypeImage (code:Sampled=1)| 675| storage image 676 | code:UniformConstant | code:OpTypeImage (code:Sampled=2) | 677| combined image sampler 678 | code:UniformConstant | code:OpTypeSampledImage + 679 code:OpTypeImage (code:Sampled=1) + 680 code:OpTypeSampler | 681| uniform texel buffer 682 | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=1) | 683| storage texel buffer 684 | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=2) | 685| uniform buffer 686 | code:Uniform | code:OpTypeStruct 687 | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) 688ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 689| storage buffer 690 | code:Uniform | code:OpTypeStruct 691 | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride) 692endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 693ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 694.2+<.^| storage buffer 695 | code:Uniform .2+<.^| code:OpTypeStruct 696 | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride) 697 | code:StorageBuffer | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) 698endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 699| input attachment 700 | code:UniformConstant | code:OpTypeImage (code:Dim=code:SubpassData, code:Sampled=2) 701 | code:InputAttachmentIndex 702|==== 7031:: in addition to code:DescriptorSet and code:Binding 704 705 706[[interfaces-resources-setandbinding]] 707=== DescriptorSet and Binding Assignment 708 709A variable decorated with a code:DescriptorSet decoration of [eq]#s# and a 710code:Binding decoration of [eq]#b# indicates that this variable is 711associated with the slink:VkDescriptorSetLayoutBinding that has a 712pname:binding equal to [eq]#b# in pname:pSetLayouts[_s_] that was specified 713in slink:VkPipelineLayoutCreateInfo. 714 715code:DescriptorSet decoration values must: be between zero and 716pname:maxBoundDescriptorSets minus one, inclusive. 717code:Binding decoration values can: be any 32-bit unsigned integer value, as 718described in <<descriptorsets-setlayout>>. 719Each descriptor set has its own binding name space. 720 721If the code:Binding decoration is used with an array, the entire array is 722assigned that binding value. 723The array must: be a single-dimensional array and size of the array must: be 724no larger than the number of descriptors in the binding. 725ifdef::VK_EXT_descriptor_indexing[] 726If the array is runtime-sized, then array elements greater than or equal to 727the size of that binding in the bound descriptor set must: not be used. 728If the array is runtime-sized, the pname:runtimeDescriptorArray feature 729must: be enabled and the code:RuntimeDescriptorArrayEXT capability must: be 730declared. 731endif::VK_EXT_descriptor_indexing[] 732ifndef::VK_EXT_descriptor_indexing[] 733The array must: not be runtime-sized. 734endif::VK_EXT_descriptor_indexing[] 735The index of each element of the array is referred to as the _arrayElement_. 736For the purposes of interface matching and descriptor set 737<<descriptorsets-updates,operations>>, if a resource variable is not an 738array, it is treated as if it has an arrayElement of zero. 739 740There is a limit on the number of resources of each type that can: be 741accessed by a pipeline stage as shown in 742<<interfaces-resources-limits,Shader Resource Limits>>. 743The "`Resources Per Stage`" column gives the limit on the number each type 744of resource that can: be statically used for an entry point in any given 745stage in a pipeline. 746The "`Resource Types`" column lists which resource types are counted against 747the limit. 748Some resource types count against multiple limits. 749 750The pipeline layout may: include descriptor sets and bindings which are not 751referenced by any variables statically used by the entry points for the 752shader stages in the binding's pname:stageFlags. 753 754However, if a variable assigned to a given code:DescriptorSet and 755code:Binding is statically used by the entry point for a shader stage, the 756pipeline layout must: contain a descriptor set layout binding in that 757descriptor set layout and for that binding number, and that binding's 758pname:stageFlags must: include the appropriate elink:VkShaderStageFlagBits 759for that stage. 760The variable must: be of a valid resource type determined by its SPIR-V type 761and storage class, as defined in 762<<interfaces-resources-storage-class-correspondence,Shader Resource and 763Storage Class Correspondence>>. 764The descriptor set layout binding must: be of a corresponding descriptor 765type, as defined in <<interfaces-resources-correspondence,Shader Resource 766and Descriptor Type Correspondence>>. 767 768[NOTE] 769.Note 770==== 771There are no limits on the number of shader variables that can have 772overlapping set and binding values in a shader; but which resources are 773<<shaders-staticuse,statically used>> has an impact. 774If any shader variable identifying a resource is 775<<shaders-staticuse,statically used>> in a shader, then the underlying 776descriptor bound at the declared set and binding must 777<<interfaces-resources-correspondence,support the declared type in the 778shader>> when the shader executes. 779 780If multiple shader variables are declared with the same set and binding 781values, and with the same underlying descriptor type, they can all be 782statically used within the same shader. 783However, accesses are not automatically synchronized, and code:Aliased 784decorations should be used to avoid data hazards (see 785https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_aliasingsection_a_aliasing[section 7862.18.2 Aliasing in the SPIR-V specification]). 787 788If multiple shader variables with the same set and binding values are 789declared in a single shader, but with different declared types, where any of 790those are not supported by the relevant bound descriptor, that shader can 791only be executed if the variables with the unsupported type are not 792statically used. 793 794A noteworthy example of using multiple statically-used shader variables 795sharing the same descriptor set and binding values is a descriptor of type 796code:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER that has multiple 797corresponding shader variables in the code:UniformConstant storage class, 798where some could be code:OpTypeImage, some could be code:OpTypeSampler 799(code:Sampled=1), and some could be code:OpTypeSampledImage. 800==== 801 802[[interfaces-resources-limits]] 803.Shader Resource Limits 804[width="80%",cols="<35,<23",options="header"] 805|==== 806| Resources per Stage | Resource Types 807.2+<.^| pname:maxPerStageDescriptorSamplers 808ifdef::VK_EXT_descriptor_indexing[] 809or pname:maxPerStageDescriptorUpdateAfterBindSamplers 810endif::VK_EXT_descriptor_indexing[] 811 | sampler | combined image sampler 812.3+<.^| pname:maxPerStageDescriptorSampledImages 813ifdef::VK_EXT_descriptor_indexing[] 814or pname:maxPerStageDescriptorUpdateAfterBindSampledImages 815endif::VK_EXT_descriptor_indexing[] 816 | sampled image | combined image sampler | uniform texel buffer 817.2+<.^| pname:maxPerStageDescriptorStorageImages 818ifdef::VK_EXT_descriptor_indexing[] 819or pname:maxPerStageDescriptorUpdateAfterBindStorageImages 820endif::VK_EXT_descriptor_indexing[] 821 | storage image | storage texel buffer 822.2+<.^| pname:maxPerStageDescriptorUniformBuffers 823ifdef::VK_EXT_descriptor_indexing[] 824or pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers 825endif::VK_EXT_descriptor_indexing[] 826 | uniform buffer | uniform buffer dynamic 827.2+<.^| pname:maxPerStageDescriptorStorageBuffers 828ifdef::VK_EXT_descriptor_indexing[] 829or pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers 830endif::VK_EXT_descriptor_indexing[] 831 | storage buffer | storage buffer dynamic 832| pname:maxPerStageDescriptorInputAttachments 833ifdef::VK_EXT_descriptor_indexing[] 834or pname:maxPerStageDescriptorUpdateAfterBindInputAttachments 835endif::VK_EXT_descriptor_indexing[] 836 | input attachment^1^ 837|==== 838 8391:: 840 Input attachments can: only be used in the fragment shader stage 841 842 843[[interfaces-resources-layout]] 844=== Offset and Stride Assignment 845 846All variables with a storage class of code:PushConstant or code:Uniform 847must: be explicitly laid out using the code:Offset, code:ArrayStride, and 848code:MatrixStride decorations. 849There are two different layouts requirements depending on the specific 850resources. 851 852[[interfaces-resources-layout-std140]] 853*Standard Uniform Buffer Layout* 854 855The _base alignment_ of the type of an code:OpTypeStruct member of is 856defined recursively as follows: 857 858 * A scalar of size [eq]#N# has a base alignment of [eq]#N#. 859 * A two-component vector, with components of size [eq]#N#, has a base 860 alignment of [eq]#2 N#. 861 * A three- or four-component vector, with components of size [eq]#N#, has 862 a base alignment of [eq]#4 N#. 863 * An array has a base alignment equal to the base alignment of its element 864 type, rounded up to a multiple of [eq]#16#. 865 * A structure has a base alignment equal to the largest base alignment of 866 any of its members, rounded up to a multiple of [eq]#16#. 867 * A row-major matrix of [eq]#C# columns has a base alignment equal to the 868 base alignment of a vector of [eq]#C# matrix components. 869 * A column-major matrix has a base alignment equal to the base alignment 870 of the matrix column type. 871 872ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 873 874A member is defined to _improperly straddle_ if either of the following are 875true: 876 877 * It is a vector with total size less than or equal to 16 bytes, and has 878 code:Offset decorations placing its first byte at [eq]#F# and its last 879 byte at [eq]#L#, where [eq]#floor(F / 16) != floor(L / 16)#. 880 * It is a vector with total size greater than 16 bytes and has its 881 code:Offset decorations placing its first byte at a non-integer multiple 882 of 16. 883 884endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 885 886Every member of an code:OpTypeStruct with storage class of code:Uniform and 887a decoration of code:Block (uniform buffers) must: be laid out according to 888the following rules: 889 890ifndef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 891 892 * The code:Offset decoration must: be a multiple of its base alignment. 893 894endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 895 896ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 897 898 * The code:Offset decoration of a scalar, an array, a structure, or a 899 matrix must: be a multiple of its base alignment. 900 * The code:Offset decoration of a vector must: be an integer multiple of 901 the base alignment of its scalar component type, and must: not 902 improperly straddle, as defined above. 903 904endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 905 906 * Any code:ArrayStride or code:MatrixStride decoration must: be an integer 907 multiple of the base alignment of the array or matrix from above. 908 * The code:Offset decoration of a member must: not place it between the 909 end of a structure or an array and the next multiple of the base 910 alignment of that structure or array. 911 * The numeric order of code:Offset decorations need not follow member 912 declaration order. 913 914[NOTE] 915.Note 916==== 917The *std140 layout* in GLSL satisfies these rules. 918==== 919 920[[interfaces-resources-layout-std430]] 921*Standard Storage Buffer Layout* 922 923Member variables of an code:OpTypeStruct with a storage class of 924code:PushConstant (push constants), or a storage class of code:Uniform with 925a decoration of code:BufferBlock (storage buffers) 926ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 927, or a storage class of code:StorageBuffer with a decoration of code:Block 928endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 929must: be laid out as <<interfaces-resources-layout-std140,above>>, except 930for array and structure base alignment which do not need to be rounded up to 931a multiple of [eq]#16#. 932 933[NOTE] 934.Note 935==== 936The *std430 layout* in GLSL satisfies these rules. 937==== 938 939 940[[interfaces-builtin-variables]] 941== Built-In Variables 942 943Built-in variables are accessed in shaders by declaring a variable decorated 944with a code:BuiltIn decoration. 945The meaning of each code:BuiltIn decoration is as follows. 946In the remainder of this section, the name of a built-in is used 947interchangeably with a term equivalent to a variable decorated with that 948particular built-in. 949Built-ins that represent integer values can: be declared as either signed or 950unsigned 32-bit integers. 951 952ifdef::VK_AMD_shader_explicit_vertex_parameter[] 953code:BaryCoordNoPerspAMD:: 954 955The code:BaryCoordNoPerspAMD decoration can: be used to decorate a fragment 956shader input variable. 957This variable will contain the (I,J) pair of the barycentric coordinates 958corresponding to the fragment evaluated using linear interpolation at the 959pixel's center. 960The K coordinate of the barycentric coordinates can: be derived given the 961identity I + J + K = 1.0. 962 963code:BaryCoordNoPerspCentroidAMD:: 964 965The code:BaryCoordNoPerspCentroidAMD decoration can: be used to decorate a 966fragment shader input variable. 967This variable will contain the (I,J) pair of the barycentric coordinates 968corresponding to the fragment evaluated using linear interpolation at the 969centroid. 970The K coordinate of the barycentric coordinates can: be derived given the 971identity I + J + K = 1.0. 972 973code:BaryCoordNoPerspSampleAMD:: 974 975The code:BaryCoordNoPerspCentroidAMD decoration can: be used to decorate a 976fragment shader input variable. 977This variable will contain the (I,J) pair of the barycentric coordinates 978corresponding to the fragment evaluated using linear interpolation at each 979covered sample. 980The K coordinate of the barycentric coordinates can: be derived given the 981identity I + J + K = 1.0. 982 983code:BaryCoordPullModelAMD:: 984 985The code:BaryCoordPullModelAMD decoration can: be used to decorate a 986fragment shader input variable. 987This variable will contain (1/W, 1/I, 1/J) evaluated at the pixel center and 988can: be used to calculate gradients and then interpolate I, J, and W at any 989desired sample location. 990 991code:BaryCoordSmoothAMD:: 992 993The code:BaryCoordSmoothAMD decoration can: be used to decorate a fragment 994shader input variable. 995This variable will contain the (I,J) pair of the barycentric coordinates 996corresponding to the fragment evaluated using perspective interpolation at 997the pixel's center. 998The K coordinate of the barycentric coordinates can: be derived given the 999identity I + J + K = 1.0. 1000 1001code:BaryCoordSmoothCentroidAMD:: 1002 1003The code:BaryCoordSmoothCentroidAMD decoration can: be used to decorate a 1004fragment shader input variable. 1005This variable will contain the (I,J) pair of the barycentric coordinates 1006corresponding to the fragment evaluated using perspective interpolation at 1007the centroid. 1008The K coordinate of the barycentric coordinates can: be derived given the 1009identity I + J + K = 1.0. 1010 1011code:BaryCoordSmoothSampleAMD:: 1012 1013The code:BaryCoordSmoothCentroidAMD decoration can: be used to decorate a 1014fragment shader input variable. 1015This variable will contain the (I,J) pair of the barycentric coordinates 1016corresponding to the fragment evaluated using perspective interpolation at 1017each covered sample. 1018The K coordinate of the barycentric coordinates can: be derived given the 1019identity I + J + K = 1.0. 1020 1021endif::VK_AMD_shader_explicit_vertex_parameter[] 1022 1023ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1024 1025[[interfaces-builtin-variables-baseinstance]] 1026code:BaseInstance:: 1027 1028Decorating a variable with the code:BaseInstance built-in will make that 1029variable contain the integer value corresponding to the first instance that 1030was passed to the command that invoked the current vertex shader invocation. 1031code:BaseInstance is the pname:firstInstance parameter to a _direct drawing 1032command_ or the pname:firstInstance member of a structure consumed by an 1033_indirect drawing command_. 1034+ 1035The code:BaseInstance decoration must: be used only within vertex shaders. 1036+ 1037The variable decorated with BaseInstance must: be declared using the input 1038storage class. 1039+ 1040The variable decorated with BaseInstance must: be declared as a scalar 104132-bit integer. 1042 1043[[interfaces-builtin-variables-basevertex]] 1044code:BaseVertex:: 1045 1046Decorating a variable with the code:BaseVertex built-in will make that 1047variable contain the integer value corresponding to the first vertex or 1048vertex offset that was passed to the command that invoked the current vertex 1049shader invocation. 1050For _non-indexed drawing commands_, this variable is the pname:firstVertex 1051parameter to a _direct drawing command_ or the pname:firstVertex member of 1052the structure consumed by an _indirect drawing command_. 1053For _indexed drawing commands_, this variable is the pname:vertexOffset 1054parameter to a _direct drawing command_ or the pname:vertexOffset member of 1055the structure consumed by an _indirect drawing command_. 1056+ 1057The code:BaseVertex decoration must: be used only within vertex shaders. 1058+ 1059The variable decorated with code:BaseVertex must: be declared using the 1060input storage class. 1061+ 1062The variable decorated with codeBaseVertex must: be declared as a scalar 106332-bit integer. 1064 1065endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1066 1067code:ClipDistance:: 1068 1069Decorating a variable with the code:ClipDistance built-in decoration will 1070make that variable contain the mechanism for controlling user clipping. 1071code:ClipDistance is an array such that the i^th^ element of the array 1072specifies the clip distance for plane i. 1073A clip distance of 0 means the vertex is on the plane, a positive distance 1074means the vertex is inside the clip half-space, and a negative distance 1075means the point is outside the clip half-space. 1076+ 1077The code:ClipDistance decoration must: be used only within vertex, fragment, 1078tessellation control, tessellation evaluation, and geometry shaders. 1079+ 1080In vertex shaders, any variable decorated with code:ClipDistance must: be 1081declared using the code:Output storage class. 1082+ 1083In fragment shaders, any variable decorated with code:ClipDistance must: be 1084declared using the code:Input storage class. 1085+ 1086In tessellation control, tessellation evaluation, or geometry shaders, any 1087variable decorated with code:ClipDistance must: not be in a storage class 1088other than code:Input or code:Output. 1089+ 1090Any variable decorated with code:ClipDistance must: be declared as an array 1091of 32-bit floating-point values. 1092 1093[NOTE] 1094.Note 1095==== 1096The array variable decorated with code:ClipDistance is explicitly sized by 1097the shader. 1098==== 1099 1100[NOTE] 1101.Note 1102==== 1103In the last vertex processing stage, these values will be linearly 1104interpolated across the primitive and the portion of the primitive with 1105interpolated distances less than 0 will be considered outside the clip 1106volume. 1107If code:ClipDistance is then used by a fragment shader, code:ClipDistance 1108contains these linearly interpolated values. 1109==== 1110 1111code:CullDistance:: 1112 1113Decorating a variable with the code:CullDistance built-in decoration will 1114make that variable contain the mechanism for controlling user culling. 1115If any member of this array is assigned a negative value for all vertices 1116belonging to a primitive, then the primitive is discarded before 1117rasterization. 1118+ 1119The code:CullDistance decoration must: be used only within vertex, fragment, 1120tessellation control, tessellation evaluation, and geometry shaders. 1121+ 1122In vertex shaders, any variable decorated with code:CullDistance must: be 1123declared using the code:Output storage class. 1124+ 1125In fragment shaders, any variable decorated with code:CullDistance must: be 1126declared using the code:Input storage class. 1127+ 1128In tessellation control, tessellation evaluation, or geometry shaders, any 1129variable decorated with code:CullDistance must: not be declared in a storage 1130class other than input or output. 1131+ 1132Any variable decorated with code:CullDistance must: be declared as an array 1133of 32-bit floating-point values. 1134 1135[NOTE] 1136.Note 1137==== 1138In fragment shaders, the values of the code:CullDistance array are linearly 1139interpolated across each primitive. 1140==== 1141 1142[NOTE] 1143.Note 1144==== 1145If code:CullDistance decorates an input variable, that variable will contain 1146the corresponding value from the code:CullDistance decorated output variable 1147from the previous shader stage. 1148==== 1149 1150ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1151 1152[[interfaces-builtin-variables-deviceindex]] 1153code:DeviceIndex:: 1154 1155The code:DeviceIndex decoration can: be applied to a shader input which will 1156be filled with the device index of the physical device that is executing the 1157current shader invocation. 1158This value will be in the range latexmath:[[0,max(1,physicalDeviceCount))], 1159where physicalDeviceCount is the pname:physicalDeviceCount member of 1160slink:VkDeviceGroupDeviceCreateInfo. 1161+ 1162The code:DeviceIndex decoration can: be used in any shader. 1163+ 1164The variable decorated with code:DeviceIndex must: be declared using the 1165code:Input storage class. 1166+ 1167The variable decorated with code:DeviceIndex must: be declared as a scalar 116832-bit integer. 1169 1170endif::VK_VERSION_1_1,VK_KHR_device_group[] 1171 1172ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1173 1174[[interfaces-builtin-variables-drawindex]] 1175code:DrawIndex:: 1176 1177Decorating a variable with the code:DrawIndex built-in will make that 1178variable contain the integer value corresponding to the zero-based index of 1179the drawing command that invoked the current vertex shader invocation. 1180For _indirect drawing commands_, code:DrawIndex begins at zero and 1181increments by one for each draw command executed. 1182The number of draw commands is given by the pname:drawCount parameter. 1183For _direct drawing commands_, code:DrawIndex is always zero. 1184code:DrawIndex is dynamically uniform. 1185+ 1186The code:DrawIndex decoration must: be used only within vertex shaders. 1187+ 1188The variable decorated with code:DrawIndex must: be declared using the input 1189storage class. 1190+ 1191The variable decorated with code:DrawIndex must: be declared as a scalar 119232-bit integer. 1193 1194endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1195 1196code:FragCoord:: 1197 1198Decorating a variable with the code:FragCoord built-in decoration will make 1199that variable contain the framebuffer coordinate 1200latexmath:[(x,y,z,\frac{1}{w})] of the fragment being processed. 1201The [eq]#(x,y)# coordinate [eq]#(0,0)# is the upper left corner of the upper 1202left pixel in the framebuffer. 1203+ 1204When <<primsrast-sampleshading,Sample Shading>> is enabled, the [eq]#x# and 1205[eq]#y# components of code:FragCoord reflect the location of one of the 1206samples corresponding to the shader invocation. 1207+ 1208When sample shading is not enabled, the [eq]#x# and [eq]#y# components of 1209code:FragCoord reflect the location of the center of the pixel, 1210[eq]#(0.5,0.5)#. 1211+ 1212The [eq]#z# component of code:FragCoord is the interpolated depth value of 1213the primitive. 1214+ 1215The [eq]#w# component is the interpolated latexmath:[\frac{1}{w}]. 1216+ 1217The code:FragCoord decoration must: be used only within fragment shaders. 1218+ 1219The variable decorated with code:FragCoord must: be declared using the 1220code:Input storage class. 1221+ 1222The code:Centroid interpolation decoration is ignored, but allowed, on 1223code:FragCoord. 1224+ 1225The variable decorated with code:FragCoord must: be declared as a 1226four-component vector of 32-bit floating-point values. 1227 1228code:FragDepth:: 1229 1230To have a shader supply a fragment-depth value, the shader must: declare the 1231code:DepthReplacing execution mode. 1232Such a shader's fragment-depth value will come from the variable decorated 1233with the code:FragDepth built-in decoration. 1234+ 1235This value will be used for any subsequent depth testing performed by the 1236implementation or writes to the depth attachment. 1237+ 1238The code:FragDepth decoration must: be used only within fragment shaders. 1239+ 1240The variable decorated with code:FragDepth must: be declared using the 1241code:Output storage class. 1242+ 1243The variable decorated with code:FragDepth must: be declared as a scalar 124432-bit floating-point value. 1245 1246ifdef::VK_EXT_shader_stencil_export[] 1247 1248code:FragStencilRefEXT:: 1249 1250Decorating a variable with the code:FragStencilRefEXT built-in decoration 1251will make that variable contain the stencil reference value for all samples 1252covered by the fragment. 1253This value will be used as the stencil reference value used in stencil 1254testing. 1255+ 1256To write to code:FragStencilRefEXT, a shader must: declare the 1257code:StencilRefReplacingEXT execution mode. 1258If a shader declares the code:StencilRefReplacingEXT execution mode and 1259there is an execution path through the shader that does not set 1260code:FragStencilRefEXT, then the fragment's stencil reference value is 1261undefined for executions of the shader that take that path. 1262+ 1263The code:FragStencilRefEXT decoration must: be used only within fragment 1264shaders. 1265+ 1266The variable decorated with code:FragStencilRefEXT must: be declared using 1267the code:Output storage class. 1268+ 1269The variable decorated with code:FragStencilRefEXT must: be declared as a 1270scalar integer value. 1271Only the least significant *s* bits of the integer value of the variable 1272decorated with code:FragStencilRefEXT are considered for stencil testing, 1273where *s* is the number of bits in the stencil framebuffer attachment, and 1274higher order bits are discarded. 1275 1276endif::VK_EXT_shader_stencil_export[] 1277 1278code:FrontFacing:: 1279 1280Decorating a variable with the code:FrontFacing built-in decoration will 1281make that variable contain whether the fragment is front or back facing. 1282This variable is non-zero if the current fragment is considered to be part 1283of a <<primsrast-polygons-basic,front-facing>> polygon primitive or of a 1284non-polygon primitive and is zero if the fragment is considered to be part 1285of a back-facing polygon primitive. 1286+ 1287The code:FrontFacing decoration must: be used only within fragment shaders. 1288+ 1289The variable decorated with code:FrontFacing must: be declared using the 1290code:Input storage class. 1291+ 1292The variable decorated with code:FrontFacing must: be declared as a boolean. 1293 1294ifdef::VK_EXT_conservative_rasterization[] 1295 1296code:FullyCoveredEXT:: 1297 1298Decorating a variable with the code:FullyCoveredEXT built-in decoration will 1299make that variable indicate whether the fragment pixel square is fully 1300covered by the generating primitive. 1301This variable is non-zero if conservative rasterization is enabled and the 1302current fragment pixel square is fully covered by the generating primitive, 1303and is zero if the fragment is not covered or partially covered, or 1304conservative rasterization is disabled. 1305+ 1306The code:FullyCoveredEXT decoration must: be used only within fragment 1307shaders and the code:FragmentFullyCoveredEXT capability must: be declared. 1308+ 1309The variable decorated with code:FullyCoveredEXT must: be declared using the 1310code:Input storage class. 1311+ 1312The variable decorated with code:FullyCoveredEXT must: be declared as a 1313boolean. 1314+ 1315ifdef::VK_EXT_post_depth_coverage[] 1316If the implementation supports 1317sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage 1318and the 1319<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>> 1320execution mode is specified the code:SampleMask built-in input variable will 1321reflect the coverage after the early per-fragment depth and stencil tests 1322are applied. 1323If 1324sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage 1325is not supported the 1326<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>> 1327execution mode must: not be specified. 1328endif::VK_EXT_post_depth_coverage[] 1329 1330endif::VK_EXT_conservative_rasterization[] 1331 1332code:GlobalInvocationId:: 1333 1334Decorating a variable with the code:GlobalInvocationId built-in decoration 1335will make that variable contain the location of the current invocation 1336within the global workgroup. 1337Each component is equal to the index of the local workgroup multiplied by 1338the size of the local workgroup plus code:LocalInvocationId. 1339+ 1340The code:GlobalInvocationId decoration must: be used only within compute 1341shaders. 1342+ 1343The variable decorated with code:GlobalInvocationId must: be declared using 1344the code:Input storage class. 1345+ 1346The variable decorated with code:GlobalInvocationId must: be declared as a 1347three-component vector of 32-bit integers. 1348 1349code:HelperInvocation:: 1350 1351Decorating a variable with the code:HelperInvocation built-in decoration 1352will make that variable contain whether the current invocation is a helper 1353invocation. 1354This variable is non-zero if the current fragment being shaded is a helper 1355invocation and zero otherwise. 1356A helper invocation is an invocation of the shader that is produced to 1357satisfy internal requirements such as the generation of derivatives. 1358+ 1359The code:HelperInvocation decoration must: be used only within fragment 1360shaders. 1361+ 1362The variable decorated with code:HelperInvocation must: be declared using 1363the code:Input storage class. 1364+ 1365The variable decorated with code:HelperInvocation must: be declared as a 1366boolean. 1367 1368[NOTE] 1369.Note 1370==== 1371It is very likely that a helper invocation will have a value of 1372code:SampleMask fragment shader input value that is zero. 1373==== 1374 1375code:InvocationId:: 1376 1377Decorating a variable with the code:InvocationId built-in decoration will 1378make that variable contain the index of the current shader invocation in a 1379geometry shader, or the index of the output patch vertex in a tessellation 1380control shader. 1381+ 1382In a geometry shader, the index of the current shader invocation ranges from 1383zero to the number of <<geometry-invocations,instances>> declared in the 1384shader minus one. 1385If the instance count of the geometry shader is one or is not specified, 1386then code:InvocationId will be zero. 1387+ 1388The code:InvocationId decoration must: be used only within tessellation 1389control and geometry shaders. 1390+ 1391The variable decorated with code:InvocationId must: be declared using the 1392code:Input storage class. 1393+ 1394The variable decorated with code:InvocationId must: be declared as a scalar 139532-bit integer. 1396 1397code:InstanceIndex:: 1398 1399Decorating a variable with the code:InstanceIndex built-in decoration will 1400make that variable contain the index of the instance that is being processed 1401by the current vertex shader invocation. 1402code:InstanceIndex begins at the pname:firstInstance parameter to 1403flink:vkCmdDraw or flink:vkCmdDrawIndexed or at the pname:firstInstance 1404member of a structure consumed by flink:vkCmdDrawIndirect or 1405flink:vkCmdDrawIndexedIndirect. 1406+ 1407The code:InstanceIndex decoration must: be used only within vertex shaders. 1408+ 1409The variable decorated with code:InstanceIndex must: be declared using the 1410code:Input storage class. 1411+ 1412The variable decorated with code:InstanceIndex must: be declared as a scalar 141332-bit integer. 1414 1415[[interfaces-builtin-variables-layer]] 1416code:Layer:: 1417 1418Decorating a variable with the code:Layer built-in decoration will make that 1419variable contain the select layer of a multi-layer framebuffer attachment. 1420+ 1421In a 1422ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1423vertex, tessellation evaluation, or 1424endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1425geometry shader, any variable decorated with code:Layer can be written with 1426the framebuffer layer index to which the primitive produced by that shader 1427will be directed. 1428ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1429+ 1430The last active _vertex processing stage_ (in pipeline order) controls the 1431code:Layer that is used. 1432Outputs in previous shader stages are not used, even if the last stage fails 1433to write the code:Layer. 1434endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1435+ 1436If the last active vertex processing stage shader entry point's interface 1437does not include a variable decorated with code:Layer, then the first layer 1438is used. 1439If a vertex processing stage shader entry point's interface includes a 1440variable decorated with code:Layer, it must: write the same value to 1441code:Layer for all output vertices of a given primitive. 1442If the code:Layer value is less than 0 or greater than or equal to the 1443number of layers in the framebuffer, then primitives may: still be 1444rasterized, fragment shaders may: be executed, and the framebuffer values 1445for all layers are undefined. 1446+ 1447The code:Layer decoration must: be used only within 1448ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1449vertex, tessellation evaluation, 1450endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1451geometry, and fragment shaders. 1452+ 1453In a 1454ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1455vertex, tessellation evaluation, or 1456endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 1457geometry shader, any variable decorated with code:Layer must: be declared 1458using the code:Output storage class. 1459ifdef::VK_NV_viewport_array2[] 1460If such a variable is also decorated with code:ViewportRelativeNV, then the 1461code:ViewportIndex is added to the layer that is used for rendering and that 1462is made available in the fragment shader. 1463If the shader writes to a variable decorated code:ViewportMaskNV, then the 1464layer selected has a different value for each viewport a primitive is 1465rendered to. 1466endif::VK_NV_viewport_array2[] 1467+ 1468In a fragment shader, a variable decorated with code:Layer contains the 1469layer index of the primitive that the fragment invocation belongs to. 1470+ 1471In a fragment shader, any variable decorated with code:Layer must: be 1472declared using the code:Input storage class. 1473+ 1474Any variable decorated with code:Layer must: be declared as a scalar 32-bit 1475integer. 1476 1477code:LocalInvocationId:: 1478 1479Decorating a variable with the code:LocalInvocationId built-in decoration 1480will make that variable contain the location of the current compute shader 1481invocation within the local workgroup. 1482Each component ranges from zero through to the size of the workgroup in that 1483dimension minus one. 1484+ 1485The code:LocalInvocationId decoration must: be used only within compute 1486shaders. 1487+ 1488The variable decorated with code:LocalInvocationId must: be declared using 1489the code:Input storage class. 1490+ 1491The variable decorated with code:LocalInvocationId must: be declared as a 1492three-component vector of 32-bit integers. 1493 1494[NOTE] 1495.Note 1496==== 1497If the size of the workgroup in a particular dimension is one, then the 1498code:LocalInvocationId in that dimension will be zero. 1499If the workgroup is effectively two-dimensional, then 1500code:LocalInvocationId.z will be zero. 1501If the workgroup is effectively one-dimensional, then both 1502code:LocalInvocationId.y and code:LocalInvocationId.z will be zero. 1503==== 1504 1505code:LocalInvocationIndex:: 1506 1507Decorating a variable with the code:LocalInvocationIndex built-in decoration 1508will make that variable contain a one-dimensional representation of 1509code:LocalInvocationId. 1510This is computed as: 1511 1512[source,c++] 1513---- 1514LocalInvocationIndex = 1515 LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y + 1516 LocalInvocationId.y * WorkgroupSize.x + 1517 LocalInvocationId.x; 1518---- 1519 1520The code:LocalInvocationIndex decoration must: be used only within compute 1521shaders. 1522+ 1523The variable decorated with code:LocalInvocationIndex must: be declared 1524using the code:Input storage class. 1525+ 1526The variable decorated with code:LocalInvocationIndex must: be declared as a 1527scalar 32-bit integer. 1528 1529ifdef::VK_VERSION_1_1[] 1530 1531code:NumSubgroups:: 1532 1533Decorating a variable with the code:NumSubgroups built-in decoration will 1534make that variable contain the number of subgroups in the local workgroup. 1535+ 1536The code:NumSubgroups decoration must: be used only within compute shaders. 1537+ 1538The variable decorated with code:NumSubgroups must: be declared using the 1539code:Input storage class. 1540+ 1541The object decorated with code:NumSubgroups must: be declared as a scalar 154232-bit integer. 1543 1544endif::VK_VERSION_1_1[] 1545 1546code:NumWorkgroups:: 1547 1548Decorating a variable with the code:NumWorkgroups built-in decoration will 1549make that variable contain the number of local workgroups that are part of 1550the dispatch that the invocation belongs to. 1551Each component is equal to the values of the workgroup count parameters 1552passed into the dispatch commands. 1553+ 1554The code:NumWorkgroups decoration must: be used only within compute shaders. 1555+ 1556The variable decorated with code:NumWorkgroups must: be declared using the 1557code:Input storage class. 1558+ 1559The variable decorated with code:NumWorkgroups must: be declared as a 1560three-component vector of 32-bit integers. 1561 1562code:PatchVertices:: 1563 1564Decorating a variable with the code:PatchVertices built-in decoration will 1565make that variable contain the number of vertices in the input patch being 1566processed by the shader. 1567A single tessellation control or tessellation evaluation shader can: read 1568patches of differing sizes, so the value of the code:PatchVertices variable 1569may: differ between patches. 1570+ 1571The code:PatchVertices decoration must: be used only within tessellation 1572control and tessellation evaluation shaders. 1573+ 1574The variable decorated with code:PatchVertices must: be declared using the 1575code:Input storage class. 1576+ 1577The variable decorated with code:PatchVertices must: be declared as a scalar 157832-bit integer. 1579 1580code:PointCoord:: 1581 1582Decorating a variable with the code:PointCoord built-in decoration will make 1583that variable contain the coordinate of the current fragment within the 1584point being rasterized, normalized to the size of the point with origin in 1585the upper left corner of the point, as described in 1586<<primsrast-points-basic,Basic Point Rasterization>>. 1587If the primitive the fragment shader invocation belongs to is not a point, 1588then the variable decorated with code:PointCoord contains an undefined 1589value. 1590+ 1591The code:PointCoord decoration must: be used only within fragment shaders. 1592+ 1593The variable decorated with code:PointCoord must: be declared using the 1594code:Input storage class. 1595+ 1596The variable decorated with code:PointCoord must: be declared as 1597two-component vector of 32-bit floating-point values. 1598 1599[NOTE] 1600.Note 1601==== 1602Depending on how the point is rasterized, code:PointCoord may: never reach 1603[eq]#(0,0)# or [eq]#(1,1)#. 1604==== 1605 1606code:PointSize:: 1607 1608Decorating a variable with the code:PointSize built-in decoration will make 1609that variable contain the size of point primitives. 1610The value written to the variable decorated with code:PointSize by the last 1611vertex processing stage in the pipeline is used as the framebuffer-space 1612size of points produced by rasterization. 1613+ 1614The code:PointSize decoration must: be used only within vertex, tessellation 1615control, tessellation evaluation, and geometry shaders. 1616+ 1617In a vertex shader, any variable decorated with code:PointSize must: be 1618declared using the code:Output storage class. 1619+ 1620In a tessellation control, tessellation evaluation, or geometry shader, any 1621variable decorated with code:PointSize must: be declared using either the 1622code:Input or code:Output storage class. 1623+ 1624Any variable decorated with code:PointSize must: be declared as a scalar 162532-bit floating-point value. 1626 1627[NOTE] 1628.Note 1629==== 1630When code:PointSize decorates a variable in the code:Input storage class, it 1631contains the data written to the output variable decorated with 1632code:PointSize from the previous shader stage. 1633==== 1634 1635code:Position:: 1636 1637Decorating a variable with the code:Position built-in decoration will make 1638that variable contain the position of the current vertex. 1639In the last vertex processing stage, the value of the variable decorated 1640with code:Position is used in subsequent primitive assembly, clipping, and 1641rasterization operations. 1642+ 1643The code:Position decoration must: be used only within vertex, tessellation 1644control, tessellation evaluation, and geometry shaders. 1645+ 1646In a vertex shader, any variable decorated with code:Position must: be 1647declared using the code:Output storage class. 1648+ 1649In a tessellation control, tessellation evaluation, or geometry shader, any 1650variable decorated with code:Position must: not be declared in a storage 1651class other than code:Input or code:Output. 1652+ 1653Any variable decorated with code:Position must: be declared as a 1654four-component vector of 32-bit floating-point values. 1655 1656[NOTE] 1657.Note 1658==== 1659When code:Position decorates a variable in the code:Input storage class, it 1660contains the data written to the output variable decorated with 1661code:Position from the previous shader stage. 1662==== 1663 1664ifdef::VK_NVX_multiview_per_view_attributes[] 1665[[interfaces-builtin-variables-positionperview]] 1666code:PositionPerViewNV:: 1667 1668Decorating a variable with the code:PositionPerViewNV built-in decoration 1669will make that variable contain the position of the current vertex, for each 1670view. 1671+ 1672The code:PositionPerViewNV decoration must: be used only within vertex, 1673tessellation control, tessellation evaluation, and geometry shaders. 1674+ 1675In a vertex shader, any variable decorated with code:PositionPerViewNV must: 1676be declared using the code:Output storage class. 1677+ 1678In a tessellation control, tessellation evaluation, or geometry shader, any 1679variable decorated with code:PositionPerViewNV must: not be declared in a 1680storage class other than input or output. 1681+ 1682Any variable decorated with code:PositionPerViewNV must: be declared as an 1683array of four-component vector of 32-bit floating-point values with at least 1684as many elements as the maximum view in the subpass's view mask plus one. 1685The array must: be indexed by a constant or specialization constant. 1686+ 1687Elements of the array correspond to views in a multiview subpass, and those 1688elements corresponding to views in the view mask of the subpass the shader 1689is compiled against will be used as the position value for those views. 1690For the final vertex processing stage in the pipeline, values written to an 1691output variable decorated with code:PositionPerViewNV are used in subsequent 1692primitive assembly, clipping, and rasterization operations, as with 1693code:Position. 1694code:PositionPerViewNV output in an earlier vertex processing stage is 1695available as an input in the subsequent vertex processing stage. 1696+ 1697If a shader is compiled against a subpass that has the 1698ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX bit set, then 1699the position values for each view must: not differ in any component other 1700than the X component. 1701If the values do differ, one will be chosen in an implementation-dependent 1702manner. 1703endif::VK_NVX_multiview_per_view_attributes[] 1704 1705code:PrimitiveId:: 1706 1707Decorating a variable with the code:PrimitiveId built-in decoration will 1708make that variable contain the index of the current primitive. 1709+ 1710The index of the first primitive generated by a drawing command is zero, and 1711the index is incremented after every individual point, line, or triangle 1712primitive is processed. 1713+ 1714For triangles drawn as points or line segments (see <<primsrast-polygonmode 1715, Polygon Mode>>), the primitive index is incremented only once, even if 1716multiple points or lines are eventually drawn. 1717+ 1718Variables decorated with code:PrimitiveId are reset to zero between each 1719instance drawn. 1720+ 1721Restarting a primitive topology using primitive restart has no effect on the 1722value of variables decorated with code:PrimitiveId. 1723+ 1724In tessellation control and tessellation evaluation shaders, it will contain 1725the index of the patch within the current set of rendering primitives that 1726correspond to the shader invocation. 1727+ 1728In a geometry shader, it will contain the number of primitives presented as 1729input to the shader since the current set of rendering primitives was 1730started. 1731+ 1732In a fragment shader, it will contain the primitive index written by the 1733geometry shader if a geometry shader is present, or with the value that 1734would have been presented as input to the geometry shader had it been 1735present. 1736+ 1737If a geometry shader is present and the fragment shader reads from an input 1738variable decorated with code:PrimitiveId, then the geometry shader must: 1739write to an output variable decorated with code:PrimitiveId in all execution 1740paths. 1741+ 1742The code:PrimitiveId decoration must: be used only within fragment, 1743tessellation control, tessellation evaluation, and geometry shaders. 1744+ 1745In a tessellation control or tessellation evaluation shader, any variable 1746decorated with code:PrimitiveId must: be declared using the code:Input 1747storage class. 1748+ 1749In a geometry shader, any variable decorated with code:PrimitiveId must: be 1750declared using either the code:Input or code:Output storage class. 1751+ 1752In a fragment shader, any variable decorated with code:PrimitiveId must: be 1753declared using the code:Input storage class, and either the code:Geometry or 1754code:Tessellation capability must: also be declared. 1755+ 1756Any variable decorated with code:PrimitiveId must: be declared as a scalar 175732-bit integer. 1758 1759[NOTE] 1760.Note 1761==== 1762When the code:PrimitiveId decoration is applied to an output variable in the 1763geometry shader, the resulting value is seen through the code:PrimitiveId 1764decorated input variable in the fragment shader. 1765==== 1766 1767code:SampleId:: 1768 1769Decorating a variable with the code:SampleId built-in decoration will make 1770that variable contain the zero-based index of the sample the invocation 1771corresponds to. 1772code:SampleId ranges from zero to the number of samples in the framebuffer 1773minus one. 1774If a fragment shader entry point's interface includes an input variable 1775decorated with code:SampleId, <<primsrast-sampleshading,Sample Shading>> is 1776considered enabled with a pname:minSampleShading value of 1.0. 1777+ 1778The code:SampleId decoration must: be used only within fragment shaders. 1779+ 1780The variable decorated with code:SampleId must: be declared using the 1781code:Input storage class. 1782+ 1783The variable decorated with code:SampleId must: be declared as a scalar 178432-bit integer. 1785 1786[[interfaces-builtin-variables-samplemask]] 1787code:SampleMask:: 1788 1789Decorating a variable with the code:SampleMask built-in decoration will make 1790any variable contain the sample coverage mask for the current fragment 1791shader invocation. 1792+ 1793A variable in the code:Input storage class decorated with code:SampleMask 1794will contain a bitmask of the set of samples covered by the primitive 1795generating the fragment during rasterization. 1796It has a sample bit set if and only if the sample is considered covered for 1797this fragment shader invocation. 1798code:SampleMask[] is an array of integers. 1799Bits are mapped to samples in a manner where bit B of mask M 1800(`SampleMask[M]`) corresponds to sample [eq]#32 {times} M {plus} B#. 1801+ 1802When state specifies multiple fragment shader invocations for a given 1803fragment, the sample mask for any single fragment shader invocation 1804specifies the subset of the covered samples for the fragment that correspond 1805to the invocation. 1806In this case, the bit corresponding to each covered sample will be set in 1807exactly one fragment shader invocation. 1808 1809ifdef::VK_EXT_post_depth_coverage[] 1810+ 1811If the 1812<<shaders-fragment-earlytest-postdepthcoverage,code:PostDepthCoverage>> 1813execution mode is specified, the sample is considered covered if and only if 1814the sample is covered by the primitive and the sample passes the 1815<<fragops-early,early per-fragment tests>>. 1816Otherwise the sample is considered covered if the sample is covered by the 1817primitive, regardless of the result of the fragment tests. 1818endif::VK_EXT_post_depth_coverage[] 1819+ 1820A variable in the code:Output storage class decorated with code:SampleMask 1821is an array of integers forming a bit array in a manner similar an input 1822variable decorated with code:SampleMask, but where each bit represents 1823coverage as computed by the shader. 1824Modifying the sample mask by writing zero to a bit of code:SampleMask causes 1825the sample to be considered uncovered. 1826ifndef::VK_NV_sample_mask_override_coverage[] 1827However, setting sample mask bits to one will never enable samples not 1828covered by the original primitive. 1829endif::VK_NV_sample_mask_override_coverage[] 1830ifdef::VK_NV_sample_mask_override_coverage[] 1831If this variable is also decorated with code:OverrideCoverageNV, the 1832fragment coverage is replaced with the sample mask bits set in the shader 1833otherwise the fragment coverage is code:ANDed with the bits of the sample 1834mask. 1835endif::VK_NV_sample_mask_override_coverage[] 1836If the fragment shader is being evaluated at any frequency other than 1837per-fragment, bits of the sample mask not corresponding to the current 1838fragment shader invocation are ignored. 1839This array must: be sized in the fragment shader either implicitly or 1840explicitly, to be no larger than the implementation-dependent maximum 1841sample-mask (as an array of 32-bit elements), determined by the maximum 1842number of samples. 1843If a fragment shader entry point's interface includes an output variable 1844decorated with code:SampleMask, the sample mask will be undefined for any 1845array elements of any fragment shader invocations that fail to assign a 1846value. 1847If a fragment shader entry point's interface does not include an output 1848variable decorated with code:SampleMask, the sample mask has no effect on 1849the processing of a fragment. 1850+ 1851The code:SampleMask decoration must: be used only within fragment shaders. 1852+ 1853Any variable decorated with code:SampleMask must: be declared using either 1854the code:Input or code:Output storage class. 1855+ 1856Any variable decorated with code:SampleMask must: be declared as an array of 185732-bit integers. 1858 1859code:SamplePosition:: 1860 1861Decorating a variable with the code:SamplePosition built-in decoration will 1862make that variable contain the sub-pixel position of the sample being 1863shaded. 1864The top left of the pixel is considered to be at coordinate [eq]#(0,0)# and 1865the bottom right of the pixel is considered to be at coordinate [eq]#(1,1)#. 1866If a fragment shader entry point's interface includes an input variable 1867decorated with code:SamplePosition, <<primsrast-sampleshading,Sample 1868Shading>> is considered enabled with a pname:minSampleShading value of 1.0. 1869+ 1870The code:SamplePosition decoration must: be used only within fragment 1871shaders. 1872+ 1873The variable decorated with code:SamplePosition must: be declared using the 1874code:Input storage class. 1875ifdef::VK_EXT_sample_locations[] 1876If the current pipeline uses <<primrast-samplelocations, custom sample 1877locations>> the value of any variable decorated with the code:SamplePosition 1878built-in decoration is undefined. 1879endif::VK_EXT_sample_locations[] 1880+ 1881The variable decorated with code:SamplePosition must: be declared as a 1882two-component vector of 32-bit floating-point values. 1883 1884ifdef::VK_VERSION_1_1[] 1885 1886code:SubgroupId:: 1887+ 1888Decorating a variable with the code:SubgroupId built-in decoration will make 1889that variable contain the index of the subgroup within the local workgroup. 1890This variable is in range [0, code:NumSubgroups-1]. 1891+ 1892The code:SubgroupId decoration must: be used only within compute shaders. 1893+ 1894The variable decorated with code:SubgroupId must: be declared using the 1895code:Input storage class. 1896+ 1897The variable decorated with code:SubgroupId must: be declared as a scalar 189832-bit integer. 1899 1900endif::VK_VERSION_1_1[] 1901 1902ifdef::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[] 1903 1904[[interfaces-builtin-variables-sgeq]] 1905code:SubgroupEqMask:: 1906+ 1907Decorating a variable with the code:SubgroupEqMask builtin decoration will 1908make that variable contain the _subgroup mask_ of the current subgroup 1909invocation. 1910The bit corresponding to the code:SubgroupLocalInvocationId is set in the 1911variable decorated with code:SubgroupEqMask. 1912All other bits are set to zero. 1913+ 1914The variable decorated with code:SubgroupEqMask must: be declared using the 1915code:Input storage class. 1916+ 1917The variable decorated with code:SubgroupEqMask must: be declared as a 1918four-component vector of 32-bit integer values. 1919+ 1920code:SubgroupEqMaskKHR is an alias of code:SubgroupEqMask. 1921 1922[[interfaces-builtin-variables-sgge]] 1923code:SubgroupGeMask:: 1924+ 1925Decorating a variable with the code:SubgroupGeMask builtin decoration will 1926make that variable contain the _subgroup mask_ of the current subgroup 1927invocation. 1928The bits corresponding to the invocations greater than or equal to 1929code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the 1930variable decorated with code:SubgroupGeMask. 1931All other bits are set to zero. 1932+ 1933The variable decorated with code:SubgroupGeMask must: be declared using the 1934code:Input storage class. 1935+ 1936The variable decorated with code:SubgroupGeMask must: be declared as a 1937four-component vector of 32-bit integer values. 1938+ 1939code:SubgroupGeMaskKHR is an alias of code:SubgroupGeMask. 1940 1941[[interfaces-builtin-variables-sggt]] 1942code:SubgroupGtMask:: 1943+ 1944Decorating a variable with the code:SubgroupGtMask builtin decoration will 1945make that variable contain the _subgroup mask_ of the current subgroup 1946invocation. 1947The bits corresponding to the invocations greater than 1948code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the 1949variable decorated with code:SubgroupGtMask. 1950All other bits are set to zero. 1951+ 1952The variable decorated with code:SubgroupGtMask must: be declared using the 1953code:Input storage class. 1954+ 1955The variable decorated with code:SubgroupGtMask must: be declared as a 1956four-component vector of 32-bit integer values. 1957+ 1958code:SubgroupGtMaskKHR is an alias of code:SubgroupGtMask. 1959 1960[[interfaces-builtin-variables-sgle]] 1961code:SubgroupLeMask:: 1962+ 1963Decorating a variable with the code:SubgroupLeMask builtin decoration will 1964make that variable contain the _subgroup mask_ of the current subgroup 1965invocation. 1966The bits corresponding to the invocations less than or equal to 1967code:SubgroupLocalInvocationId are set in the variable decorated with 1968code:SubgroupLeMask. 1969All other bits are set to zero. 1970+ 1971The variable decorated with code:SubgroupLeMask must: be declared using the 1972code:Input storage class. 1973+ 1974The variable decorated with code:SubgroupLeMask must: be declared as a 1975four-component vector of 32-bit integer values. 1976+ 1977code:SubgroupLeMaskKHR is an alias of code:SubgroupLeMask. 1978 1979[[interfaces-builtin-variables-sglt]] 1980code:SubgroupLtMask:: 1981+ 1982Decorating a variable with the code:SubgroupLtMask builtin decoration will 1983make that variable contain the _subgroup mask_ of the current subgroup 1984invocation. 1985The bits corresponding to the invocations less than 1986code:SubgroupLocalInvocationId are set in the variable decorated with 1987code:SubgroupLtMask. 1988All other bits are set to zero. 1989+ 1990The variable decorated with code:SubgroupLtMask must: be declared using the 1991code:Input storage class. 1992+ 1993The variable decorated with code:SubgroupLtMask must: be declared as a 1994four-component vector of 32-bit integer values. 1995+ 1996code:SubgroupLtMaskKHR is an alias of code:SubgroupLtMask. 1997 1998[[interfaces-builtin-variables-sgli]] 1999code:SubgroupLocalInvocationId:: 2000+ 2001Decorating a variable with the code:SubgroupLocalInvocationId builtin 2002decoration will make that variable contain the index of the invocation 2003within the subgroup. 2004This variable is in range [0,code:SubgroupSize-1]. 2005+ 2006The variable decorated with code:SubgroupLocalInvocationId must: be declared 2007using the code:Input storage class. 2008+ 2009The variable decorated with code:SubgroupLocalInvocationId must: be declared 2010as a scalar 32-bit integer. 2011 2012[[interfaces-builtin-variables-sgs]] 2013code:SubgroupSize:: 2014+ 2015Decorating a variable with the code:SubgroupSize builtin decoration will 2016make that variable contain the implementation-dependent maximum number of 2017invocations in a subgroup. 2018The maximum number of invocations that an implementation can support per 2019subgroup is 128. 2020+ 2021The variable decorated with code:SubgroupSize must: be declared using the 2022code:Input storage class. 2023+ 2024The variable decorated with code:SubgroupSize must: be declared as a scalar 202532-bit integer. 2026 2027endif::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[] 2028 2029code:TessCoord:: 2030 2031Decorating a variable with the code:TessCoord built-in decoration will make 2032that variable contain the three-dimensional [eq]#(u,v,w)# barycentric 2033coordinate of the tessellated vertex within the patch. 2034[eq]#u#, [eq]#v#, and [eq]#w# are in the range [eq]#[0,1]# and vary linearly 2035across the primitive being subdivided. 2036For the tessellation modes of code:Quads or code:IsoLines, the third 2037component is always zero. 2038+ 2039The code:TessCoord decoration must: be used only within tessellation 2040evaluation shaders. 2041+ 2042The variable decorated with code:TessCoord must: be declared using the 2043code:Input storage class. 2044+ 2045The variable decorated with code:TessCoord must: be declared as 2046three-component vector of 32-bit floating-point values. 2047 2048code:TessLevelOuter:: 2049 2050Decorating a variable with the code:TessLevelOuter built-in decoration will 2051make that variable contain the outer tessellation levels for the current 2052patch. 2053+ 2054In tessellation control shaders, the variable decorated with 2055code:TessLevelOuter can: be written to which controls the tessellation 2056factors for the resulting patch. 2057These values are used by the tessellator to control primitive tessellation 2058and can: be read by tessellation evaluation shaders. 2059+ 2060In tessellation evaluation shaders, the variable decorated with 2061code:TessLevelOuter can: read the values written by the tessellation control 2062shader. 2063+ 2064The code:TessLevelOuter decoration must: be used only within tessellation 2065control and tessellation evaluation shaders. 2066+ 2067In a tessellation control shader, any variable decorated with 2068code:TessLevelOuter must: be declared using the code:Output storage class. 2069+ 2070In a tessellation evaluation shader, any variable decorated with 2071code:TessLevelOuter must: be declared using the code:Input storage class. 2072+ 2073Any variable decorated with code:TessLevelOuter must: be declared as an 2074array of size four, containing 32-bit floating-point values. 2075 2076code:TessLevelInner:: 2077 2078Decorating a variable with the code:TessLevelInner built-in decoration will 2079make that variable contain the inner tessellation levels for the current 2080patch. 2081+ 2082In tessellation control shaders, the variable decorated with 2083code:TessLevelInner can: be written to, which controls the tessellation 2084factors for the resulting patch. 2085These values are used by the tessellator to control primitive tessellation 2086and can: be read by tessellation evaluation shaders. 2087+ 2088In tessellation evaluation shaders, the variable decorated with 2089code:TessLevelInner can: read the values written by the tessellation control 2090shader. 2091+ 2092The code:TessLevelInner decoration must: be used only within tessellation 2093control and tessellation evaluation shaders. 2094+ 2095In a tessellation control shader, any variable decorated with 2096code:TessLevelInner must: be declared using the code:Output storage class. 2097+ 2098In a tessellation evaluation shader, any variable decorated with 2099code:TessLevelInner must: be declared using the code:Input storage class. 2100+ 2101Any variable decorated with code:TessLevelInner must: be declared as an 2102array of size two, containing 32-bit floating-point values. 2103 2104code:VertexIndex:: 2105 2106Decorating a variable with the code:VertexIndex built-in decoration will 2107make that variable contain the index of the vertex that is being processed 2108by the current vertex shader invocation. 2109For non-indexed draws, this variable begins at the pname:firstVertex 2110parameter to flink:vkCmdDraw or the pname:firstVertex member of a structure 2111consumed by flink:vkCmdDrawIndirect and increments by one for each vertex in 2112the draw. 2113For indexed draws, its value is the content of the index buffer for the 2114vertex plus the pname:vertexOffset parameter to flink:vkCmdDrawIndexed or 2115the pname:vertexOffset member of the structure consumed by 2116flink:vkCmdDrawIndexedIndirect. 2117+ 2118The code:VertexIndex decoration must: be used only within vertex shaders. 2119+ 2120The variable decorated with code:VertexIndex must: be declared using the 2121code:Input storage class. 2122+ 2123The variable decorated with code:VertexIndex must: be declared as a scalar 212432-bit integer. 2125 2126[NOTE] 2127.Note 2128==== 2129code:VertexIndex starts at the same starting value for each instance. 2130==== 2131 2132ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2133 2134[[interfaces-builtin-variables-viewindex]] 2135code:ViewIndex:: 2136 2137The code:ViewIndex decoration can: be applied to a shader input which will 2138be filled with the index of the view that is being processed by the current 2139shader invocation. 2140+ 2141If multiview is enabled in the render pass, this value will be one of the 2142bits set in the view mask of the subpass the pipeline is compiled against. 2143If multiview is not enabled in the render pass, this value will be zero. 2144+ 2145The code:ViewIndex decoration must: not be used within compute shaders. 2146+ 2147The variable decorated with code:ViewIndex must: be declared using the 2148code:Input storage class. 2149+ 2150The variable decorated with code:ViewIndex must: be declared as a scalar 215132-bit integer. 2152 2153endif::VK_VERSION_1_1,VK_KHR_multiview[] 2154 2155[[interfaces-builtin-variables-viewportindex]] 2156code:ViewportIndex:: 2157 2158Decorating a variable with the code:ViewportIndex built-in decoration will 2159make that variable contain the index of the viewport. 2160+ 2161In a 2162ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2163vertex, tessellation evaluation, or 2164endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2165geometry shader, the variable decorated with code:ViewportIndex can be 2166written to with the viewport index to which the primitive produced by that 2167shader will be directed. 2168+ 2169The selected viewport index is used to select the viewport transform and 2170scissor rectangle. 2171ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2172+ 2173The last active _vertex processing stage_ (in pipeline order) controls the 2174code:ViewportIndex that is used. 2175Outputs in previous shader stages are not used, even if the last stage fails 2176to write the code:ViewportIndex. 2177endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2178+ 2179If the last active vertex processing stage shader entry point's interface 2180does not include a variable decorated with code:ViewportIndex, then the 2181first viewport is used. 2182If a vertex processing stage shader entry point's interface includes a 2183variable decorated with code:ViewportIndex, it must: write the same value to 2184code:ViewportIndex for all output vertices of a given primitive. 2185+ 2186The code:ViewportIndex decoration must: be used only within 2187ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2188vertex, tessellation evaluation, 2189endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2190geometry, and fragment shaders. 2191+ 2192In a 2193ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2194vertex, tessellation evaluation, or 2195endif::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] 2196geometry shader, any variable decorated with code:ViewportIndex must: be 2197declared using the code:Output storage class. 2198+ 2199In a fragment shader, the variable decorated with code:ViewportIndex 2200contains the viewport index of the primitive that the fragment invocation 2201belongs to. 2202+ 2203In a fragment shader, any variable decorated with code:ViewportIndex must: 2204be declared using the code:Input storage class. 2205+ 2206Any variable decorated with code:ViewportIndex must: be declared as a scalar 220732-bit integer. 2208 2209ifdef::VK_NV_viewport_array2[] 2210[[interfaces-builtin-variables-viewportmask]] 2211code:ViewportMaskNV:: 2212 2213Decorating a variable with the code:ViewportMaskNV built-in decoration will 2214make that variable contain the viewport mask. 2215+ 2216In a vertex, tessellation evaluation, or geometry shader, the variable 2217decorated with code:ViewportMaskNV can be written to with the mask of which 2218viewports the primitive produced by that shader will directed. 2219+ 2220The code:ViewportMaskNV variable must: be an array that has 2221[eq]#{lceil}(sname:VkPhysicalDeviceLimits::pname:maxViewports / 32){rceil}# 2222elements. 2223When a shader writes to this variable, bit B of element M controls whether a 2224primitive is emitted to viewport [eq]#32 {times} M +B#. 2225The viewports indicated by the mask are used to select the viewport 2226transform and scissor rectangle that a primitive will be transformed by. 2227+ 2228The last active _vertex processing stage_ (in pipeline order) controls the 2229code:ViewportMaskNV that is used. 2230Outputs in previous shader stages are not used, even if the last stage fails 2231to write the code:ViewportMaskNV. 2232When code:ViewportMaskNV is written by the final vertex processing stage, 2233any variable decorated with code:ViewportIndex in the fragment shader will 2234have the index of the viewport that was used in generating that fragment. 2235+ 2236If a vertex processing stage shader entry point's interface includes a 2237variable decorated with code:ViewportMaskNV, it must: write the same value 2238to code:ViewportMaskNV for all output vertices of a given primitive. 2239+ 2240The code:ViewportMaskNV decoration must: be used only within vertex, 2241tessellation evaluation, and geometry shaders. 2242+ 2243Any variable decorated with code:ViewportMaskNV must: be declared using the 2244code:Output storage class. 2245+ 2246Any variable decorated with code:ViewportMaskNV must: be declared as an 2247array of 32-bit integers. 2248endif::VK_NV_viewport_array2[] 2249 2250ifdef::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[] 2251[[interfaces-builtin-variables-viewportmaskperview]] 2252code:ViewportMaskPerViewNV:: 2253 2254Decorating a variable with the code:ViewportMaskPerViewNV built-in 2255decoration will make that variable contain the mask of viewports primitives 2256are broadcast to, for each view. 2257+ 2258The code:ViewportMaskPerViewNV decoration must: be used only within vertex, 2259tessellation control, tessellation evaluation, and geometry shaders. 2260+ 2261Any variable decorated with code:ViewportMaskPerViewNV must: be declared 2262using the code:Output storage class. 2263+ 2264The value written to an element of code:ViewportMaskPerViewNV in the last 2265vertex processing stage is a bitmask indicating which viewports the 2266primitive will be directed to. 2267The primitive will be broadcast to the viewport corresponding to each 2268non-zero bit of the bitmask, and that viewport index is used to select the 2269viewport transform and scissor rectangle, for each view. 2270The same values must: be written to all vertices in a given primitive, or 2271else the set of viewports used for that primitive is undefined. 2272+ 2273Any variable decorated with code:ViewportMaskPerViewNV must: be declared as 2274an array of scalar 32-bit integers with at least as many elements as the 2275maximum view in the subpass's view mask plus one. 2276The array must: be indexed by a constant or specialization constant. 2277+ 2278Elements of the array correspond to views in a multiview subpass, and those 2279elements corresponding to views in the view mask of the subpass the shader 2280is compiled against will be used as the viewport mask value for those views. 2281code:ViewportMaskPerViewNV output in an earlier vertex processing stage is 2282not available as an input in the subsequent vertex processing stage. 2283+ 2284Although code:ViewportMaskNV is an array, code:ViewportMaskPerViewNV is not 2285a two-dimensional array. 2286Instead, code:ViewportMaskPerViewNV is limited to 32 viewports. 2287endif::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[] 2288 2289code:WorkgroupId:: 2290 2291Decorating a variable with the code:WorkgroupId built-in decoration will 2292make that variable contain the global workgroup that the current invocation 2293is a member of. 2294Each component ranges from a base value to a [eq]#base {plus} count# value, 2295based on the parameters passed into the dispatch commands. 2296+ 2297The code:WorkgroupId decoration must: be used only within compute shaders. 2298+ 2299The variable decorated with code:WorkgroupId must: be declared using the 2300code:Input storage class. 2301+ 2302The variable decorated with code:WorkgroupId must: be declared as a 2303three-component vector of 32-bit integers. 2304 2305code:WorkgroupSize:: 2306 2307Decorating an object with the code:WorkgroupSize built-in decoration will 2308make that object contain the dimensions of a local workgroup. 2309If an object is decorated with the code:WorkgroupSize decoration, this must: 2310take precedence over any execution mode set for code:LocalSize. 2311+ 2312The code:WorkgroupSize decoration must: be used only within compute shaders. 2313+ 2314The object decorated with code:WorkgroupSize must: be a specialization 2315constant or a constant. 2316+ 2317The object decorated with code:WorkgroupSize must: be declared as a 2318three-component vector of 32-bit integers. 2319