1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-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>> 16ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 17 * <<interfaces-raypipeline, Ray Tracing Pipeline Interface>> 18endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 19 * <<interfaces-resources,Shader Resource Interface>> 20 21Interface definitions make use of the following SPIR-V decorations: 22 23 * code:DescriptorSet and code:Binding 24 * code:Location, code:Component, and code:Index 25 * code:Flat, code:NoPerspective, code:Centroid, and code:Sample 26 * code:Block and code:BufferBlock 27 * code:InputAttachmentIndex 28 * code:Offset, code:ArrayStride, and code:MatrixStride 29 * code:BuiltIn 30ifdef::VK_NV_geometry_shader_passthrough[] 31 * <<geometry-passthrough-passthrough,code:PassthroughNV>> 32endif::VK_NV_geometry_shader_passthrough[] 33 34 35This specification describes valid uses for Vulkan of these decorations. 36Any other use of one of these decorations is invalid, with the exception 37that, when using SPIR-V versions 1.4 and earlier: code:Block, 38code:BufferBlock, code:Offset, code:ArrayStride, and code:MatrixStride can 39also decorate types and type members used by variables in the Private and 40Function storage classes. 41 42[NOTE] 43.Note 44==== 45In this chapter, there are references to SPIR-V terms such as the 46code:MeshNV execution model. 47These terms will appear even in a build of the specification which does not 48support any extensions. 49This is as intended, since these terms appear in the unified SPIR-V 50specification without such qualifiers. 51==== 52 53 54[[interfaces-iointerfaces]] 55== Shader Input and Output Interfaces 56 57When multiple stages are present in a pipeline, the outputs of one stage 58form an interface with the inputs of the next stage. 59When such an interface involves a shader, shader outputs are matched against 60the inputs of the next stage, and shader inputs are matched against the 61outputs of the previous stage. 62 63All the variables forming the shader input and output _interfaces_ are 64listed as operands to the code:OpEntryPoint instruction and are declared 65with the code:Input or code:Output storage classes, respectively, in the 66SPIR-V module. 67These generally form the interfaces between consecutive shader stages, 68regardless of any non-shader stages between the consecutive shader stages. 69 70There are two classes of variables that can: be matched between shader 71stages, built-in variables and user-defined variables. 72Each class has a different set of matching criteria. 73 74code:Output variables of a shader stage have undefined: values until the 75shader writes to them or uses the code:Initializer operand when declaring 76the variable. 77 78 79[[interfaces-iointerfaces-builtin]] 80=== Built-in Interface Block 81 82Shader <<interfaces-builtin-variables,built-in>> variables meeting the 83following requirements define the _built-in interface block_. 84They must: 85 86 * be explicitly declared (there are no implicit built-ins), 87 * be identified with a code:BuiltIn decoration, 88 * form object types as described in the 89 <<interfaces-builtin-variables,Built-in Variables>> section, and 90 * be declared in a block whose top-level members are the built-ins. 91 92There must: be no more than one built-in interface block per shader per 93interface. 94 95Built-ins must: not have any code:Location or code:Component decorations. 96 97 98[[interfaces-iointerfaces-user]] 99=== User-defined Variable Interface 100 101The non-built-in variables listed by code:OpEntryPoint with the code:Input 102or code:Output storage class form the _user-defined variable interface_. 103These must: have SPIR-V numerical types or, recursively, composite types of 104such types. 105ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 106By default, the components of such types have a width of 32 or 64 bits. 107If an implementation supports 108<<features-storageInputOutput16,storageInputOutput16>>, components can: also 109have a width of 16 bits. 110endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 111These variables must: be identified with a code:Location decoration and can: 112also be identified with a code:Component decoration. 113 114 115[[interfaces-iointerfaces-matching]] 116=== Interface Matching 117 118An output variable, block, or structure member in a given shader stage has 119an interface match with an input variable, block, or structure member in a 120subsequent shader stage if they both adhere to the following conditions: 121 122 * They have equivalent decorations, other than: 123 ** <<shaders-interpolation-decorations,Interpolation decorations>> 124ifdef::VK_EXT_transform_feedback[] 125 ** code:XfbBuffer, code:XfbStride, code:Offset, and code:Stream 126endif::VK_EXT_transform_feedback[] 127 ** one is not decorated with code:Component and the other is declared with 128 a code:Component of `0` 129 * Their types match as follows: 130 ** if the input is declared in a tessellation control or geometry shader 131 as an code:OpTypeArray with an code:Element code:Type equivalent to the 132 code:OpType* declaration of the output, and neither is a structure 133 member; or 134ifdef::VK_KHR_maintenance4[] 135 ** if the <<features-maintenance4, pname:maintenance4>> feature is 136 enabled, they are declared as code:OpTypeVector variables, and the 137 output has a code:Component code:Count value higher than that of the 138 input but the same code:Component code:Type; or 139endif::VK_KHR_maintenance4[] 140ifdef::VK_NV_mesh_shader[] 141 ** if the output is declared in a mesh shader as an code:OpTypeArray with 142 an code:Element code:Type equivalent to the code:OpType* declaration of 143 the input, and neither is a structure member; or 144endif::VK_NV_mesh_shader[] 145 ** if in any other case they are declared with an equivalent code:OpType* 146 declaration. 147 * If both are structures and every member has an interface match. 148 149[NOTE] 150.Note 151==== 152The word "structure" above refers to both variables that have an 153code:OpTypeStruct type and interface blocks (which are also declared as 154code:OpTypeStruct). 155==== 156 157All input variables and blocks must: have an interface match in the 158preceding shader stage, except for built-in variables in fragment shaders. 159Shaders can: declare and write to output variables that are not declared or 160read by the subsequent stage. 161 162ifdef::VK_NV_geometry_shader_passthrough[] 163Matching rules for _passthrough geometry shaders_ are slightly different and 164are described in the <<geometry-passthrough-interface,Passthrough Interface 165Matching>> section. 166endif::VK_NV_geometry_shader_passthrough[] 167 168The value of an input variable is undefined: if the preceding stage does not 169write to a matching output variable, as described above. 170 171 172[[interfaces-iointerfaces-locations]] 173=== Location Assignment 174 175This section describes location assignments for user-defined variables and 176how many locations are consumed by a given user-variable type. 177<<interfaces-iointerfaces-matching, As mentioned above>>, some inputs and 178outputs have an additional level of arrayness relative to other shader 179inputs and outputs. 180This outer array level is removed from the type before considering how many 181locations the type consumes. 182 183The code:Location value specifies an interface slot comprised of a 32-bit 184four-component vector conveyed between stages. 185The code:Component specifies 186<<interfaces-iointerfaces-components,components>> within these vector 187locations. 188Only types with widths of 189ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 19016, 191endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 19232 or 64 are supported in shader interfaces. 193 194Inputs and outputs of the following types consume a single interface 195location: 196 197ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 198 * 16-bit scalar and vector types, and 199endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 200 * 32-bit scalar and vector types, and 201 * 64-bit scalar and 2-component vector types. 202 20364-bit three- and four-component vectors consume two consecutive locations. 204 205If a declared input or output is an array of size _n_ and each element takes 206_m_ locations, it will be assigned _m_ {times} _n_ consecutive locations 207starting with the location specified. 208 209If the declared input or output is an _n_ {times} _m_ 210ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 21116-, 212endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 21332- or 64-bit matrix, it will be assigned multiple locations starting with 214the location specified. 215The number of locations assigned for each matrix will be the same as for an 216_n_-element array of _m_-component vectors. 217 218An code:OpVariable with a structure type that is not a block must: be 219decorated with a code:Location. 220 221When an code:OpVariable with a structure type (either block or non-block) is 222decorated with a code:Location, the members in the structure type must: not 223be decorated with a code:Location. 224The code:OpVariable's members are assigned consecutive locations in 225declaration order, starting from the first member, which is assigned the 226location decoration from the code:OpVariable. 227 228When a block-type code:OpVariable is declared without a code:Location 229decoration, each member in its structure type must: be decorated with a 230code:Location. 231Types nested deeper than the top-level members must: not have code:Location 232decorations. 233 234The locations consumed by block and structure members are determined by 235applying the rules above in a depth-first traversal of the instantiated 236members as though the structure or block member were declared as an input or 237output variable of the same type. 238 239Any two inputs listed as operands on the same code:OpEntryPoint must: not be 240assigned the same location, either explicitly or implicitly. 241Any two outputs listed as operands on the same code:OpEntryPoint must: not 242be assigned the same location, either explicitly or implicitly. 243 244The number of input and output locations available for a shader input or 245output interface are limited, and dependent on the shader stage as described 246in <<interfaces-iointerfaces-limits>>. 247All variables in both the <<interfaces-builtin-variables,built-in interface 248block>> and the <<interfaces-iointerfaces-user,user-defined variable 249interface>> count against these limits. 250Each effective code:Location must: have a value less than the number of 251locations available for the given interface, as specified in the "Locations 252Available" column in <<interfaces-iointerfaces-limits>>. 253 254 255[[interfaces-iointerfaces-limits]] 256.Shader Input and Output Locations 257[width="90%",cols="<6,<13",options="header"] 258|==== 259| Shader Interface | Locations Available 260| vertex input | pname:maxVertexInputAttributes 261| vertex output | pname:maxVertexOutputComponents / 4 262| tessellation control input | pname:maxTessellationControlPerVertexInputComponents / 4 263| tessellation control output | pname:maxTessellationControlPerVertexOutputComponents / 4 264| tessellation evaluation input | pname:maxTessellationEvaluationInputComponents / 4 265| tessellation evaluation output| pname:maxTessellationEvaluationOutputComponents / 4 266| geometry input | pname:maxGeometryInputComponents / 4 267| geometry output | pname:maxGeometryOutputComponents / 4 268| fragment input | pname:maxFragmentInputComponents / 4 269| fragment output | pname:maxFragmentOutputAttachments 270ifdef::VK_NV_mesh_shader[] 271// we forgot to add maxMeshOutputComponents 272| mesh output | pname:maxFragmentInputComponents / 4 273endif::VK_NV_mesh_shader[] 274|==== 275 276 277[[interfaces-iointerfaces-components]] 278=== Component Assignment 279 280The code:Component decoration allows the code:Location to be more finely 281specified for scalars and vectors, down to the individual components within 282a location that are consumed. 283The components within a location are 0, 1, 2, and 3. 284A variable or block member starting at component N will consume components 285N, N+1, N+2, ... 286up through its size. 287ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 288For 16-, and 32-bit types, 289endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 290ifndef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 291For single precision types, 292endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 293it is invalid if this sequence of components gets larger than 3. 294A scalar 64-bit type will consume two of these components in sequence, and a 295two-component 64-bit vector type will consume all four components available 296within a location. 297A three- or four-component 64-bit vector type must: not specify a 298code:Component decoration. 299A three-component 64-bit vector type will consume all four components of the 300first location and components 0 and 1 of the second location. 301This leaves components 2 and 3 available for other component-qualified 302declarations. 303 304A scalar or two-component 64-bit data type must: not specify a 305code:Component decoration of 1 or 3. 306A code:Component decoration must: not be specified for any type that is not 307a scalar or vector. 308 309 310[[interfaces-vertexinput]] 311== Vertex Input Interface 312 313When the vertex stage is present in a pipeline, the vertex shader input 314variables form an interface with the vertex input attributes. 315The vertex shader input variables are matched by the code:Location and 316code:Component decorations to the vertex input attributes specified in the 317pname:pVertexInputState member of the slink:VkGraphicsPipelineCreateInfo 318structure. 319 320The vertex shader input variables listed by code:OpEntryPoint with the 321code:Input storage class form the _vertex input interface_. 322These variables must: be identified with a code:Location decoration and can: 323also be identified with a code:Component decoration. 324 325For the purposes of interface matching: variables declared without a 326code:Component decoration are considered to have a code:Component decoration 327of zero. 328The number of available vertex input locations is given by the 329pname:maxVertexInputAttributes member of the sname:VkPhysicalDeviceLimits 330structure. 331 332See <<fxvertex-attrib-location>> for details. 333 334All vertex shader inputs declared as above must: have a corresponding 335attribute and binding in the pipeline. 336 337 338[[interfaces-fragmentoutput]] 339== Fragment Output Interface 340 341When the fragment stage is present in a pipeline, the fragment shader 342outputs form an interface with the output attachments defined by a 343<<renderpass, render pass instance>>. 344The fragment shader output variables are matched by the code:Location and 345code:Component decorations to specified color attachments. 346 347The fragment shader output variables listed by code:OpEntryPoint with the 348code:Output storage class form the _fragment output interface_. 349These variables must: be identified with a code:Location decoration. 350They can: also be identified with a code:Component decoration and/or an 351code:Index decoration. 352For the purposes of interface matching: variables declared without a 353code:Component decoration are considered to have a code:Component decoration 354of zero, and variables declared without an code:Index decoration are 355considered to have an code:Index decoration of zero. 356 357A fragment shader output variable identified with a code:Location decoration 358of _i_ is associated with 359ifdef::VK_KHR_dynamic_rendering[] 360the element of slink:VkRenderingInfoKHR::pname:pColorAttachments with a 361pname:location equal to _i_. 362When using render pass objects, it is associated with 363endif::VK_KHR_dynamic_rendering[] 364the color attachment indicated by pname:pColorAttachments[_i_]. 365Values are written to those attachments after passing through the blending 366unit as described in <<framebuffer-blending>>, if enabled. 367Locations are consumed as described in 368<<interfaces-iointerfaces-locations,Location Assignment>>. 369The number of available fragment output locations is given by the 370pname:maxFragmentOutputAttachments member of the 371sname:VkPhysicalDeviceLimits structure. 372 373Components of the output variables are assigned as described in 374<<interfaces-iointerfaces-components,Component Assignment>>. 375Output components identified as 0, 1, 2, and 3 will be directed to the R, G, 376B, and A inputs to the blending unit, respectively, or to the output 377attachment if blending is disabled. 378If two variables are placed within the same location, they must: have the 379same underlying type (floating-point or integer). 380The input values to blending or color attachment writes are undefined: for 381components which do not correspond to a fragment shader output. 382 383Fragment outputs identified with an code:Index of zero are directed to the 384first input of the blending unit associated with the corresponding 385code:Location. 386Outputs identified with an code:Index of one are directed to the second 387input of the corresponding blending unit. 388 389No _component aliasing_ of output variables is allowed, that is there must: 390not be two output variables which have the same location, component, and 391index, either explicitly declared or implied. 392 393Output values written by a fragment shader must: be declared with either 394code:OpTypeFloat or code:OpTypeInt, and a code:Width of 32. 395ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 396If pname:storageInputOutput16 is supported, output values written by a 397fragment shader can: be also declared with either code:OpTypeFloat or 398code:OpTypeInt and a code:Width of 16. 399endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 400Composites of these types are also permitted. 401If the color attachment has a signed or unsigned normalized fixed-point 402format, color values are assumed to be floating-point and are converted to 403fixed-point as described in <<fundamentals-fpfixedconv>>; If the color 404attachment has an integer format, color values are assumed to be integers 405and converted to the bit-depth of the target. 406Any value that cannot be represented in the attachment's format is 407undefined:. 408For any other attachment format no conversion is performed. 409If the type of the values written by the fragment shader do not match the 410format of the corresponding color attachment, the resulting values are 411undefined: for those components. 412 413 414[[interfaces-inputattachment]] 415== Fragment Input Attachment Interface 416 417When a fragment stage is present in a pipeline, the fragment shader subpass 418inputs form an interface with the input attachments of the current subpass. 419The fragment shader subpass input variables are matched by 420code:InputAttachmentIndex decorations to the input attachments specified in 421the pname:pInputAttachments array of the slink:VkSubpassDescription 422structure describing the subpass that the fragment shader is executed in. 423 424The fragment shader subpass input variables with the code:UniformConstant 425storage class and a decoration of code:InputAttachmentIndex that are 426statically used by code:OpEntryPoint form the _fragment input attachment 427interface_. 428These variables must: be declared with a type of code:OpTypeImage, a 429code:Dim operand of code:SubpassData, an code:Arrayed operand of 0, and a 430code:Sampled operand of 2. 431The code:MS operand of the code:OpTypeImage must: be 0 if the pname:samples 432field of the corresponding slink:VkAttachmentDescription is 433ename:VK_SAMPLE_COUNT_1_BIT and 1 otherwise. 434 435A subpass input variable identified with an code:InputAttachmentIndex 436decoration of _i_ reads from the input attachment indicated by 437pname:pInputAttachments[_i_] member of sname:VkSubpassDescription. 438If the subpass input variable is declared as an array of size N, it consumes 439N consecutive input attachments, starting with the index specified. 440There must: not be more than one input variable with the same 441code:InputAttachmentIndex whether explicitly declared or implied by an array 442declaration. 443The number of available input attachment indices is given by the 444pname:maxPerStageDescriptorInputAttachments member of the 445sname:VkPhysicalDeviceLimits structure. 446 447Variables identified with the code:InputAttachmentIndex must: only be used 448by a fragment stage. 449The basic data type (floating-point, integer, unsigned integer) of the 450subpass input must: match the basic format of the corresponding input 451attachment, or the values of subpass loads from these variables are 452undefined:. 453 454See <<descriptorsets-inputattachment>> for more details. 455 456 457ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 458[[interfaces-raypipeline]] 459== Ray Tracing Pipeline Interface 460 461Ray tracing pipelines may: have more stages than other pipelines with 462multiple instances of each stage and more dynamic interactions between the 463stages, but still have interface structures that obey the same general rules 464as interfaces between shader stages in other pipelines. 465The three types of inter-stage interface variables for ray tracing pipelines 466are: 467 468 * Ray payloads which contain data tracked for the entire lifetime of the 469 ray. 470 * Hit attributes which contain data about a specific hit for the duration 471 of its processing. 472 * Callable data for passing data into and out of a callable shader. 473 474Ray payloads and callable data are used in explicit shader call 475instructions, so they have an incoming variant to distinguish the parameter 476passed to the invocation from any other payloads or data being used by 477subsequent shader call instructions. 478 479An interface structure used between stages must: match between the stages 480using it. 481Specifically: 482 483 * The hit attribute structure read in an any-hit or closest hit shader 484 must: be the same structure as the hit attribute structure written in the 485 corresponding intersection shader in the same hit group. 486 * The incoming callable data for a callable shader must: be the same 487 structure as the callable data referenced by the execute callable 488 instruction in the calling shader. 489 * The ray payload for a shader invoked by a ray tracing command must: be 490 the same structure for all shader stages using the payload for that ray. 491 492Any shader with an incoming ray payload, incoming callable data, or hit 493attribute must: only declare one variable of that type. 494 495.Ray Pipeline Shader Interface 496[width="90%",options="header"] 497|==== 498| Shader Stage | Ray Payload | Incoming Ray Payload | Hit Attribute | Callable Data | Incoming Callable Data 499| Ray Generation | r/w | | | r/w | 500| Intersection | | | r/w | | 501| Any-Hit | | r/w | r | | 502| Closest Hit | r/w | r/w | r | r/w | 503| Miss | r/w | r/w | | r/w | 504| Callable | | | | r/w | r/w 505|==== 506endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 507 508 509[[interfaces-resources]] 510== Shader Resource Interface 511 512When a shader stage accesses buffer or image resources, as described in the 513<<descriptorsets,Resource Descriptors>> section, the shader resource 514variables must: be matched with the <<descriptorsets-pipelinelayout,pipeline 515layout>> that is provided at pipeline creation time. 516 517The set of shader variables that form the _shader resource interface_ for a 518stage are the variables statically used by that stage's code:OpEntryPoint 519with a storage class of code:Uniform, code:UniformConstant, 520ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 521code:StorageBuffer, 522endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 523or code:PushConstant. 524For the fragment shader, this includes the <<interfaces-inputattachment, 525fragment input attachment interface>>. 526 527The shader resource interface consists of two sub-interfaces: the push 528constant interface and the descriptor set interface. 529 530 531[[interfaces-resources-pushconst]] 532=== Push Constant Interface 533 534The shader variables defined with a storage class of code:PushConstant that 535are statically used by the shader entry points for the pipeline define the 536_push constant interface_. 537They must: be: 538 539 * typed as code:OpTypeStruct, 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>>. 544 545There must: be no more than one push constant block statically used per 546shader entry point. 547 548Each statically used member of a push constant block must: be placed at an 549code:Offset such that the entire member is entirely contained within the 550slink:VkPushConstantRange for each code:OpEntryPoint that uses it, and the 551pname:stageFlags for that range must: specify the appropriate 552elink:VkShaderStageFlagBits for that stage. 553The code:Offset decoration for any member of a push constant block must: not 554cause the space required for that member to extend outside the range 555[eq]#[0, pname:maxPushConstantsSize)#. 556 557Any member of a push constant block that is declared as an array must: only 558be accessed with _dynamically uniform_ indices. 559 560 561[[interfaces-resources-descset]] 562=== Descriptor Set Interface 563 564The _descriptor set interface_ is comprised of the shader variables with the 565storage class of 566ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 567code:StorageBuffer, 568endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 569code:Uniform or code:UniformConstant (including the variables in the 570<<interfaces-inputattachment,fragment input attachment interface>>) that are 571statically used by the shader entry points for the pipeline. 572 573These variables must: have code:DescriptorSet and code:Binding decorations 574specified, which are assigned and matched with the 575sname:VkDescriptorSetLayout objects in the pipeline layout as described in 576<<interfaces-resources-setandbinding,DescriptorSet and Binding Assignment>>. 577 578The code:Image code:Format of an code:OpTypeImage declaration must: not be 579*Unknown*, for variables which are used for code:OpImageRead, 580code:OpImageSparseRead, or code:OpImageWrite operations, except under the 581following conditions: 582 583 * For code:OpImageWrite, if the image format is listed in the 584 <<formats-without-shader-storage-format,storage without format>> list 585 and if the pname:shaderStorageImageWriteWithoutFormat feature is enabled 586 and the shader module declares the code:StorageImageWriteWithoutFormat 587 capability. 588ifdef::VK_KHR_format_feature_flags2[] 589 * For code:OpImageWrite, if the image format supports 590 ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR and the 591 shader module declares the code:StorageImageWriteWithoutFormat 592 capability. 593endif::VK_KHR_format_feature_flags2[] 594 * For code:OpImageRead or code:OpImageSparseRead, if the image format is 595 listed in the <<formats-without-shader-storage-format,storage without 596 format>> list and if the pname:shaderStorageImageReadWithoutFormat 597 feature is enabled and the shader module declares the 598 code:StorageImageReadWithoutFormat capability. 599ifdef::VK_KHR_format_feature_flags2[] 600 * For code:OpImageRead or code:OpImageSparseRead, if the image format 601 supports ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR 602 and the shader module declares the code:StorageImageReadWithoutFormat 603 capability. 604endif::VK_KHR_format_feature_flags2[] 605 * For code:OpImageRead, if code:Dim is code:SubpassData (indicating a read 606 from an input attachment). 607 608The code:Image code:Format of an code:OpTypeImage declaration must: not be 609*Unknown*, for variables which are used for code:OpAtomic* operations. 610 611Variables identified with the code:Uniform storage class are used to access 612transparent buffer backed resources. 613Such variables must: be: 614 615 * typed as code:OpTypeStruct, or an array of this type, 616 * identified with a code:Block or code:BufferBlock decoration, and 617 * laid out explicitly using the code:Offset, code:ArrayStride, and 618 code:MatrixStride decorations as specified in 619 <<interfaces-resources-layout,Offset and Stride Assignment>>. 620 621ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 622Variables identified with the code:StorageBuffer storage class are used to 623access transparent buffer backed resources. 624Such variables must: be: 625 626 * typed as code:OpTypeStruct, or an array of this type, 627 * identified with a code:Block decoration, and 628 * laid out explicitly using the code:Offset, code:ArrayStride, and 629 code:MatrixStride decorations as specified in 630 <<interfaces-resources-layout,Offset and Stride Assignment>>. 631endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 632 633ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 634The code:Offset decoration for any variable in a code:Block must: not cause 635the space required for that variable to extend outside the range [eq]#[0, 636pname:maxUniformBufferRange)#. 637The code:Offset decoration for any variable in a code:BufferBlock must: not 638cause the space required for that variable to extend outside the range 639[eq]#[0, pname:maxStorageBufferRange)#. 640endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 641 642ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 643The code:Offset decoration for any member of a code:Block-decorated variable 644in the code:Uniform storage class must: not cause the space required for 645that variable to extend outside the range [eq]#[0, 646pname:maxUniformBufferRange)#. 647The code:Offset decoration for any member of a code:Block-decorated variable 648in the code:StorageBuffer storage class must: not cause the space required 649for that variable to extend outside the range [eq]#[0, 650pname:maxStorageBufferRange)#. 651endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 652 653ifdef::VK_EXT_inline_uniform_block[] 654Variables identified with the code:Uniform storage class can: also be used 655to access transparent descriptor set backed resources when the variable is 656assigned to a descriptor set layout binding with a pname:descriptorType of 657ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT. 658In this case the variable must: be typed as code:OpTypeStruct and cannot: be 659aggregated into arrays of that type. 660Further, the code:Offset decoration for any member of such a variable must: 661not cause the space required for that variable to extend outside the range 662[eq]#[0,pname:maxInlineUniformBlockSize)#. 663endif::VK_EXT_inline_uniform_block[] 664 665Variables identified with a storage class of code:UniformConstant and a 666decoration of code:InputAttachmentIndex must: be declared as described in 667<<interfaces-inputattachment,Fragment Input Attachment Interface>>. 668 669SPIR-V variables decorated with a descriptor set and binding that identify a 670<<descriptorsets-combinedimagesampler, combined image sampler descriptor>> 671can: have a type of code:OpTypeImage, code:OpTypeSampler (code:Sampled=1), 672or code:OpTypeSampledImage. 673 674Arrays of any of these types can: be indexed with _constant integral 675expressions_. 676The following features must: be enabled and capabilities must: be declared 677in order to index such arrays with dynamically uniform or non-uniform 678indices: 679 680 * Storage images (except storage texel buffers and input attachments): 681 ** Dynamically uniform: pname:shaderStorageImageArrayDynamicIndexing and 682 code:StorageImageArrayDynamicIndexing 683ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 684 ** Non-uniform: pname:shaderStorageImageArrayNonUniformIndexing and 685 code:StorageImageArrayNonUniformIndexing 686 * Storage texel buffers: 687 ** Dynamically uniform: pname:shaderStorageTexelBufferArrayDynamicIndexing 688 and code:StorageTexelBufferArrayDynamicIndexing 689 ** Non-uniform: pname:shaderStorageTexelBufferArrayNonUniformIndexing and 690 code:StorageTexelBufferArrayNonUniformIndexing 691 * Input attachments: 692 ** Dynamically uniform: pname:shaderInputAttachmentArrayDynamicIndexing 693 and code:InputAttachmentArrayDynamicIndexing 694 ** Non-uniform: pname:shaderInputAttachmentArrayNonUniformIndexing and 695 code:InputAttachmentArrayNonUniformIndexing 696endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 697 * Sampled images (except uniform texel buffers), samplers and combined 698 image samplers: 699 ** Dynamically uniform: pname:shaderSampledImageArrayDynamicIndexing and 700 code:SampledImageArrayDynamicIndexing 701ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 702 ** Non-uniform: pname:shaderSampledImageArrayNonUniformIndexing and 703 code:SampledImageArrayNonUniformIndexing 704 * Uniform texel buffers: 705 ** Dynamically uniform: pname:shaderUniformTexelBufferArrayDynamicIndexing 706 and code:UniformTexelBufferArrayDynamicIndexing 707 ** Non-uniform: pname:shaderUniformTexelBufferArrayNonUniformIndexing and 708 code:UniformTexelBufferArrayNonUniformIndexing 709endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 710 * Uniform buffers: 711 ** Dynamically uniform: pname:shaderUniformBufferArrayDynamicIndexing and 712 code:UniformBufferArrayDynamicIndexing 713ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 714 ** Non-uniform: pname:shaderUniformBufferArrayNonUniformIndexing and 715 code:UniformBufferArrayNonUniformIndexing 716endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 717 * Storage buffers: 718 ** Dynamically uniform: pname:shaderStorageBufferArrayDynamicIndexing and 719 code:StorageBufferArrayDynamicIndexing 720ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 721 ** Non-uniform: pname:shaderStorageBufferArrayNonUniformIndexing and 722 code:StorageBufferArrayNonUniformIndexing 723endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 724ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 725 * Acceleration structures: 726 ** Dynamically uniform: Always supported. 727 ** Non-uniform: Always supported. 728endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 729 730ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 731If an instruction loads from or stores to a resource (including atomics and 732image instructions) and the resource descriptor being accessed is not 733dynamically uniform, then the corresponding non-uniform indexing feature 734must: be enabled and the capability must: be declared. 735endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 736If an instruction loads from or stores to a resource (including atomics and 737image instructions) and the resource descriptor being accessed is loaded 738from an array element with a non-constant index, then the corresponding 739dynamic 740ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 741or non-uniform 742endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 743indexing feature must: be enabled and the capability must: be declared. 744 745ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 746If the combined image sampler enables sampler {YCbCr} 747ifndef::VK_EXT_fragment_density_map[] 748conversion, 749endif::VK_EXT_fragment_density_map[] 750ifdef::VK_EXT_fragment_density_map[] 751conversion or samples a <<samplers-subsamplesampler,subsampled image>>, 752endif::VK_EXT_fragment_density_map[] 753it must: be indexed only by constant integral expressions when aggregated 754into arrays in shader code, irrespective of the 755pname:shaderSampledImageArrayDynamicIndexing feature. 756endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 757ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 758ifdef::VK_EXT_fragment_density_map[] 759If the combined image sampler samples a 760<<samplers-subsamplesampler,subsampled image>>, it must: be indexed only by 761constant integral expressions when aggregated into arrays in shader code, 762irrespective of the pname:shaderSampledImageArrayDynamicIndexing feature. 763endif::VK_EXT_fragment_density_map[] 764endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 765 766[[interfaces-resources-correspondence]] 767.Shader Resource and Descriptor Type Correspondence 768[width="90%",cols="<1,<2",options="header"] 769|==== 770| Resource type | Descriptor Type 771| sampler | ename:VK_DESCRIPTOR_TYPE_SAMPLER or 772 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 773| sampled image | ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 774 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 775| storage image | ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE 776| combined image sampler | ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 777| uniform texel buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 778| storage texel buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER 779| uniform buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 780 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC 781| storage buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 782 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 783| input attachment | ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 784ifdef::VK_EXT_inline_uniform_block[] 785| inline uniform block | ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 786endif::VK_EXT_inline_uniform_block[] 787ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 788| acceleration structure | 789ifdef::VK_KHR_acceleration_structure[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR] 790ifdef::VK_NV_ray_tracing+VK_KHR_acceleration_structure[or] 791ifdef::VK_NV_ray_tracing[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV] 792endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 793|==== 794 795[[interfaces-resources-storage-class-correspondence]] 796.Shader Resource and Storage Class Correspondence 797[width="100%",cols="<21%,<22%,<27%,<30%",options="header"] 798|==== 799| Resource type | Storage Class | Type^1^ | Decoration(s)^2^ 800| sampler 801 | code:UniformConstant | code:OpTypeSampler | 802| sampled image 803 | code:UniformConstant | code:OpTypeImage (code:Sampled=1)| 804| storage image 805 | code:UniformConstant | code:OpTypeImage (code:Sampled=2) | 806| combined image sampler 807 | code:UniformConstant | code:OpTypeSampledImage + 808 code:OpTypeImage (code:Sampled=1) + 809 code:OpTypeSampler | 810| uniform texel buffer 811 | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=1) | 812| storage texel buffer 813 | code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=2) | 814| uniform buffer 815 | code:Uniform | code:OpTypeStruct 816 | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) 817ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 818| storage buffer 819 | code:Uniform | code:OpTypeStruct 820 | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride) 821endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 822ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 823.2+<.^| storage buffer 824 | code:Uniform .2+<.^| code:OpTypeStruct 825 | code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride) 826 | code:StorageBuffer | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) 827endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] 828| input attachment 829 | code:UniformConstant | code:OpTypeImage (code:Dim=code:SubpassData, code:Sampled=2) 830 | code:InputAttachmentIndex 831ifdef::VK_EXT_inline_uniform_block[] 832| inline uniform block 833 | code:Uniform | code:OpTypeStruct 834 | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride) 835endif::VK_EXT_inline_uniform_block[] 836ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 837| acceleration structure 838 | code:UniformConstant | code:OpTypeAccelerationStructureKHR | 839endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 840|==== 841 8421:: 843 Where code:OpTypeImage is referenced, the code:Dim values code:Buffer 844 and code:Subpassdata are only accepted where they are specifically 845 referenced. 846 They do not correspond to resource types where a generic 847 code:OpTypeImage is specified. 8482:: 849 In addition to code:DescriptorSet and code:Binding. 850 851 852[[interfaces-resources-setandbinding]] 853=== DescriptorSet and Binding Assignment 854 855A variable decorated with a code:DescriptorSet decoration of [eq]#s# and a 856code:Binding decoration of [eq]#b# indicates that this variable is 857associated with the slink:VkDescriptorSetLayoutBinding that has a 858pname:binding equal to [eq]#b# in pname:pSetLayouts[_s_] that was specified 859in slink:VkPipelineLayoutCreateInfo. 860 861code:DescriptorSet decoration values must: be between zero and 862pname:maxBoundDescriptorSets minus one, inclusive. 863code:Binding decoration values can: be any 32-bit unsigned integer value, as 864described in <<descriptorsets-setlayout>>. 865Each descriptor set has its own binding name space. 866 867If the code:Binding decoration is used with an array, the entire array is 868assigned that binding value. 869The array must: be a single-dimensional array and size of the array must: be 870no larger than the number of descriptors in the binding. 871ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 872If the array is runtime-sized, then array elements greater than or equal to 873the size of that binding in the bound descriptor set must: not be used. 874If the array is runtime-sized, the pname:runtimeDescriptorArray feature 875must: be enabled and the code:RuntimeDescriptorArray capability must: be 876declared. 877endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 878ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 879The array must: not be runtime-sized. 880endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 881The index of each element of the array is referred to as the _arrayElement_. 882For the purposes of interface matching and descriptor set 883<<descriptorsets-updates,operations>>, if a resource variable is not an 884array, it is treated as if it has an arrayElement of zero. 885 886There is a limit on the number of resources of each type that can: be 887accessed by a pipeline stage as shown in 888<<interfaces-resources-limits,Shader Resource Limits>>. 889The "`Resources Per Stage`" column gives the limit on the number each type 890of resource that can: be statically used for an entry point in any given 891stage in a pipeline. 892The "`Resource Types`" column lists which resource types are counted against 893the limit. 894Some resource types count against multiple limits. 895ifdef::VK_VALVE_mutable_descriptor_type[] 896The ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptor type counts as one 897individual resource and one for every unique resource limit per descriptor 898set type that is present in the associated binding's 899slink:VkMutableDescriptorTypeListVALVE. 900If multiple descriptor types in slink:VkMutableDescriptorTypeListVALVE map 901to the same resource limit, only one descriptor is consumed for purposes of 902computing resource limits. 903endif::VK_VALVE_mutable_descriptor_type[] 904 905The pipeline layout may: include descriptor sets and bindings which are not 906referenced by any variables statically used by the entry points for the 907shader stages in the binding's pname:stageFlags. 908 909However, if a variable assigned to a given code:DescriptorSet and 910code:Binding is statically used by the entry point for a shader stage, the 911pipeline layout must: contain a descriptor set layout binding in that 912descriptor set layout and for that binding number, and that binding's 913pname:stageFlags must: include the appropriate elink:VkShaderStageFlagBits 914for that stage. 915The variable must: be of a valid resource type determined by its SPIR-V type 916and storage class, as defined in 917<<interfaces-resources-storage-class-correspondence,Shader Resource and 918Storage Class Correspondence>>. 919The descriptor set layout binding must: be of a corresponding descriptor 920type, as defined in <<interfaces-resources-correspondence,Shader Resource 921and Descriptor Type Correspondence>>. 922 923[NOTE] 924.Note 925==== 926There are no limits on the number of shader variables that can have 927overlapping set and binding values in a shader; but which resources are 928<<shaders-staticuse,statically used>> has an impact. 929If any shader variable identifying a resource is 930<<shaders-staticuse,statically used>> in a shader, then the underlying 931descriptor bound at the declared set and binding must 932<<interfaces-resources-correspondence,support the declared type in the 933shader>> when the shader executes. 934 935If multiple shader variables are declared with the same set and binding 936values, and with the same underlying descriptor type, they can all be 937statically used within the same shader. 938However, accesses are not automatically synchronized, and code:Aliased 939decorations should be used to avoid data hazards (see 940https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_aliasingsection_a_aliasing[section 9412.18.2 Aliasing in the SPIR-V specification]). 942 943If multiple shader variables with the same set and binding values are 944declared in a single shader, but with different declared types, where any of 945those are not supported by the relevant bound descriptor, that shader can 946only be executed if the variables with the unsupported type are not 947statically used. 948 949A noteworthy example of using multiple statically-used shader variables 950sharing the same descriptor set and binding values is a descriptor of type 951ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER that has multiple 952corresponding shader variables in the code:UniformConstant storage class, 953where some could be code:OpTypeImage (code:Sampled=1), some could be 954code:OpTypeSampler, and some could be code:OpTypeSampledImage. 955==== 956 957[[interfaces-resources-limits]] 958.Shader Resource Limits 959[width="80%",cols="<35,<23",options="header"] 960|==== 961| Resources per Stage | Resource Types 962.2+<.^| pname:maxPerStageDescriptorSamplers 963ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 964or pname:maxPerStageDescriptorUpdateAfterBindSamplers 965endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 966 | sampler | combined image sampler 967.3+<.^| pname:maxPerStageDescriptorSampledImages 968ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 969or pname:maxPerStageDescriptorUpdateAfterBindSampledImages 970endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 971 | sampled image | combined image sampler | uniform texel buffer 972.2+<.^| pname:maxPerStageDescriptorStorageImages 973ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 974or pname:maxPerStageDescriptorUpdateAfterBindStorageImages 975endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 976 | storage image | storage texel buffer 977.2+<.^| pname:maxPerStageDescriptorUniformBuffers 978ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 979or pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers 980endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 981 | uniform buffer | uniform buffer dynamic 982.2+<.^| pname:maxPerStageDescriptorStorageBuffers 983ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 984or pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers 985endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 986 | storage buffer | storage buffer dynamic 987| pname:maxPerStageDescriptorInputAttachments 988ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 989or pname:maxPerStageDescriptorUpdateAfterBindInputAttachments 990endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 991 | input attachment^1^ 992ifdef::VK_EXT_inline_uniform_block[] 993| pname:maxPerStageDescriptorInlineUniformBlocks 994ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 995or pname:maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks 996endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 997 | inline uniform block 998endif::VK_EXT_inline_uniform_block[] 999ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1000| 1001ifdef::VK_NV_ray_tracing[sname:VkPhysicalDeviceRayTracingPropertiesNV ::pname:maxDescriptorSetAccelerationStructures] 1002ifdef::VK_NV_ray_tracing+VK_KHR_acceleration_structure[or] 1003ifdef::VK_KHR_acceleration_structure[] 1004pname:maxPerStageDescriptorAccelerationStructures or 1005pname:maxPerStageDescriptorUpdateAfterBindAccelerationStructures 1006endif::VK_KHR_acceleration_structure[] 1007 | acceleration structure 1008endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 1009|==== 1010 10111:: 1012 Input attachments can: only be used in the fragment shader stage 1013 1014 1015[[interfaces-resources-layout]] 1016=== Offset and Stride Assignment 1017 1018Certain objects must: be explicitly laid out using the code:Offset, 1019code:ArrayStride, and code:MatrixStride, as described in 1020https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#ShaderValidation[SPIR-V 1021explicit layout validation rules]. 1022All such layouts also must: conform to the following requirements. 1023 1024[NOTE] 1025.Note 1026==== 1027The numeric order of code:Offset decorations does not need to follow member 1028declaration order. 1029==== 1030 1031 1032[[interfaces-alignment-requirements]] 1033*Alignment Requirements* 1034 1035There are different alignment requirements depending on the specific 1036resources and on the features enabled on the device. 1037 1038The _scalar alignment_ of the type of an code:OpTypeStruct member is defined 1039recursively as follows: 1040 1041 * A scalar of size [eq]#N# has a scalar alignment of [eq]#N#. 1042 * A vector or matrix type has a scalar alignment equal to that of its 1043 component type. 1044 * An array type has a scalar alignment equal to that of its element type. 1045 * A structure has a scalar alignment equal to the largest scalar alignment 1046 of any of its members. 1047 1048The _base alignment_ of the type of an code:OpTypeStruct member is defined 1049recursively as follows: 1050 1051 * A scalar has a base alignment equal to its scalar alignment. 1052 * A two-component vector has a base alignment equal to twice its scalar 1053 alignment. 1054 * A three- or four-component vector has a base alignment equal to four 1055 times its scalar alignment. 1056 * An array has a base alignment equal to the base alignment of its element 1057 type. 1058 * A structure has a base alignment equal to the largest base alignment of 1059 any of its members. 1060 An empty structure has a base alignment equal to the size of the 1061 smallest scalar type permitted by the capabilities declared in the 1062 SPIR-V module. 1063 (e.g., for a 1 byte aligned empty struct in the code:StorageBuffer 1064 storage class, code:StorageBuffer8BitAccess or 1065 code:UniformAndStorageBuffer8BitAccess must: be declared in the SPIR-V 1066 module.) 1067 * A row-major matrix of [eq]#C# columns has a base alignment equal to the 1068 base alignment of a vector of [eq]#C# matrix components. 1069 * A column-major matrix has a base alignment equal to the base alignment 1070 of the matrix column type. 1071 1072The _extended alignment_ of the type of an code:OpTypeStruct member is 1073similarly defined as follows: 1074 1075 * A scalar, vector or matrix type has an extended alignment equal to its 1076 base alignment. 1077 * An array or structure type has an extended alignment equal to the 1078 largest extended alignment of any of its members, rounded up to a 1079 multiple of 16. 1080 1081ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1082 1083A member is defined to _improperly straddle_ if either of the following are 1084true: 1085 1086 * It is a vector with total size less than or equal to 16 bytes, and has 1087 code:Offset decorations placing its first byte at [eq]#F# and its last 1088 byte at [eq]#L#, where [eq]#floor(F / 16) != floor(L / 16)#. 1089 * It is a vector with total size greater than 16 bytes and has its 1090 code:Offset decorations placing its first byte at a non-integer multiple 1091 of 16. 1092 1093endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1094 1095[[interfaces-resources-standard-layout]] 1096*Standard Buffer Layout* 1097 1098Every member of an code:OpTypeStruct that is required to be explicitly laid 1099out must: be aligned according to the first matching rule as follows. 1100If the struct is contained in pointer types of multiple storage classes, it 1101must: satisfy the requirements for every storage class used to reference it. 1102 1103ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1104. If the code:scalarBlockLayout feature is enabled on the device and the 1105 storage class is code:Uniform, code:StorageBuffer, 1106ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1107 code:PhysicalStorageBuffer, 1108endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1109ifdef::VK_KHR_ray_tracing_pipeline[] 1110 code:ShaderRecordBufferKHR, 1111endif::VK_KHR_ray_tracing_pipeline[] 1112 or code:PushConstant then every member must: be aligned according to its 1113 scalar alignment. 1114endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1115ifdef::VK_KHR_workgroup_memory_explicit_layout[] 1116. If the code:workgroupMemoryExplicitLayoutScalarBlockLayout feature is 1117 enabled on the device and the storage class is code:Workgroup then every 1118 member must: be aligned according to its scalar alignment. 1119endif::VK_KHR_workgroup_memory_explicit_layout[] 1120ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1121. All vectors must: be aligned according to their scalar alignment. 1122endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1123ifdef::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[] 1124. If the pname:uniformBufferStandardLayout feature is not enabled on the 1125 device, then any 1126endif::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[] 1127ifndef::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[] 1128. Any 1129endif::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[] 1130 member of an code:OpTypeStruct with a storage class of code:Uniform and a 1131 decoration of code:Block must: be aligned according to its extended 1132 alignment. 1133. Every other member must: be aligned according to its base alignment. 1134 1135ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1136[NOTE] 1137.Note 1138==== 1139Even if scalar alignment is supported, it is generally more performant to 1140use the _base alignment_. 1141==== 1142endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1143 1144The memory layout must: obey the following rules: 1145 1146 * The code:Offset decoration of any member must: be a multiple of its 1147 alignment. 1148 * Any code:ArrayStride or code:MatrixStride decoration must: be a multiple 1149 of the alignment of the array or matrix as defined above. 1150 1151ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout,VK_KHR_workgroup_memory_explicit_layout[] 1152If one of the conditions below applies 1153 1154ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1155 * The storage class is code:Uniform, code:StorageBuffer, 1156ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1157 code:PhysicalStorageBuffer, 1158endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1159ifdef::VK_KHR_ray_tracing_pipeline[] 1160 code:ShaderRecordBufferKHR, 1161endif::VK_KHR_ray_tracing_pipeline[] 1162 or code:PushConstant, and the code:scalarBlockLayout feature is not 1163 enabled on the device. 1164endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[] 1165ifdef::VK_KHR_workgroup_memory_explicit_layout[] 1166 * The storage class is code:Workgroup, and either the struct member is not 1167 part of a code:Block or the 1168 code:workgroupMemoryExplicitLayoutScalarBlockLayout feature is not 1169 enabled on the device. 1170endif::VK_KHR_workgroup_memory_explicit_layout[] 1171 * The storage class is any other storage class. 1172 1173the memory layout must: also obey the following rules: 1174endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout,VK_KHR_workgroup_memory_explicit_layout[] 1175 1176ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1177 * Vectors must: not improperly straddle, as defined above. 1178endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[] 1179 * The code:Offset decoration of a member must: not place it between the 1180 end of a structure or an array and the next multiple of the alignment of 1181 that structure or array. 1182 1183[NOTE] 1184.Note 1185==== 1186The *std430 layout* in GLSL satisfies these rules for types using the base 1187alignment. 1188The *std140 layout* satisfies the rules for types using the extended 1189alignment. 1190==== 1191 1192 1193[[interfaces-builtin-variables]] 1194== Built-In Variables 1195 1196Built-in variables are accessed in shaders by declaring a variable decorated 1197with a code:BuiltIn SPIR-V decoration. 1198The meaning of each code:BuiltIn decoration is as follows. 1199In the remainder of this section, the name of a built-in is used 1200interchangeably with a term equivalent to a variable decorated with that 1201particular built-in. 1202Built-ins that represent integer values can: be declared as either signed or 1203unsigned 32-bit integers. 1204 1205<<interfaces-iointerfaces-matching, As mentioned above>>, some inputs and 1206outputs have an additional level of arrayness relative to other shader 1207inputs and outputs. 1208This level of arrayness is not included in the type descriptions below, but 1209must be included when declaring the built-in. 1210 1211ifdef::VK_NV_fragment_shader_barycentric[] 1212[[interfaces-builtin-variables-barycoordnv]] 1213[open,refpage='BaryCoordNV',desc='Barycentric coordinates of a fragment',type='builtins'] 1214-- 1215:refpage: BaryCoordNV 1216 1217code:BaryCoordNV:: 1218 1219The code:BaryCoordNV decoration can: be used to decorate a fragment shader 1220input variable. 1221This variable will contain a three-component floating-point vector with 1222barycentric weights that indicate the location of the fragment relative to 1223the screen-space locations of vertices of its primitive, obtained using 1224perspective interpolation. 1225 1226.Valid Usage 1227**** 1228 * [[VUID-{refpage}-BaryCoordNV-04154]] 1229 The code:BaryCoordNV decoration must: be used only within the 1230 code:Fragment {ExecutionModel} 1231 * [[VUID-{refpage}-BaryCoordNV-04155]] 1232 The variable decorated with code:BaryCoordNV must: be declared using the 1233 code:Input {StorageClass} 1234 * [[VUID-{refpage}-BaryCoordNV-04156]] 1235 The variable decorated with code:BaryCoordNV must: be declared as a 1236 three-component vector of 32-bit floating-point values 1237**** 1238-- 1239endif::VK_NV_fragment_shader_barycentric[] 1240 1241ifdef::VK_AMD_shader_explicit_vertex_parameter[] 1242[open,refpage='BaryCoordNoPerspAMD',desc='Barycentric coordinates of a fragment center in screen-space',type='builtins'] 1243-- 1244:refpage: BaryCoordNoPerspAMD 1245 1246code:BaryCoordNoPerspAMD:: 1247 1248The code:BaryCoordNoPerspAMD decoration can: be used to decorate a fragment 1249shader input variable. 1250This variable will contain the (I,J) pair of the barycentric coordinates 1251corresponding to the fragment evaluated using linear interpolation at the 1252fragment's center. 1253The K coordinate of the barycentric coordinates can: be derived given the 1254identity I {plus} J {plus} K = 1.0. 1255 1256.Valid Usage 1257**** 1258 * [[VUID-{refpage}-BaryCoordNoPerspAMD-04157]] 1259 The code:BaryCoordNoPerspAMD decoration must: be used only within the 1260 code:Fragment {ExecutionModel} 1261 * [[VUID-{refpage}-BaryCoordNoPerspAMD-04158]] 1262 The variable decorated with code:BaryCoordNoPerspAMD must: be declared 1263 using the code:Input {StorageClass} 1264 * [[VUID-{refpage}-BaryCoordNoPerspAMD-04159]] 1265 The variable decorated with code:BaryCoordNoPerspAMD must: be declared 1266 as a two-component vector of 32-bit floating-point values 1267**** 1268-- 1269endif::VK_AMD_shader_explicit_vertex_parameter[] 1270 1271ifdef::VK_NV_fragment_shader_barycentric[] 1272[[interfaces-builtin-variables-barycoordnoperspnv]] 1273[open,refpage='BaryCoordNoPerspNV',desc='Barycentric coordinates of a fragment in screen-space',type='builtins'] 1274-- 1275:refpage: BaryCoordNoPerspNV 1276 1277code:BaryCoordNoPerspNV:: 1278 1279The code:BaryCoordNoPerspNV decoration can: be used to decorate a fragment 1280shader input variable. 1281This variable will contain a three-component floating-point vector with 1282barycentric weights that indicate the location of the fragment relative to 1283the screen-space locations of vertices of its primitive, obtained using 1284linear interpolation. 1285 1286.Valid Usage 1287**** 1288 * [[VUID-{refpage}-BaryCoordNoPerspNV-04160]] 1289 The code:BaryCoordNoPerspNV decoration must: be used only within the 1290 code:Fragment {ExecutionModel} 1291 * [[VUID-{refpage}-BaryCoordNoPerspNV-04161]] 1292 The variable decorated with code:BaryCoordNoPerspNV must: be declared 1293 using the code:Input {StorageClass} 1294 * [[VUID-{refpage}-BaryCoordNoPerspNV-04162]] 1295 The variable decorated with code:BaryCoordNoPerspNV must: be declared as 1296 a three-component vector of 32-bit floating-point values 1297**** 1298-- 1299endif::VK_NV_fragment_shader_barycentric[] 1300 1301ifdef::VK_AMD_shader_explicit_vertex_parameter[] 1302[open,refpage='BaryCoordNoPerspCentroidAMD',desc='Barycentric coordinates of a fragment centroid in screen-space',type='builtins'] 1303-- 1304:refpage: BaryCoordNoPerspCentroidAMD 1305 1306code:BaryCoordNoPerspCentroidAMD:: 1307 1308The code:BaryCoordNoPerspCentroidAMD decoration can: be used to decorate a 1309fragment shader input variable. 1310This variable will contain the (I,J) pair of the barycentric coordinates 1311corresponding to the fragment evaluated using linear interpolation at the 1312centroid. 1313The K coordinate of the barycentric coordinates can: be derived given the 1314identity I {plus} J {plus} K = 1.0. 1315 1316.Valid Usage 1317**** 1318 * [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04163]] 1319 The code:BaryCoordNoPerspCentroidAMD decoration must: be used only 1320 within the code:Fragment {ExecutionModel} 1321 * [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04164]] 1322 The variable decorated with code:BaryCoordNoPerspCentroidAMD must: be 1323 declared using the code:Input {StorageClass} 1324 * [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04165]] 1325 The variable decorated with code:BaryCoordNoPerspCentroidAMD must: be 1326 declared as a three-component vector of 32-bit floating-point values 1327**** 1328-- 1329 1330[open,refpage='BaryCoordNoPerspSampleAMD',desc='Barycentric coordinates of a sample center in screen-space',type='builtins'] 1331-- 1332:refpage: BaryCoordNoPerspSampleAMD 1333 1334code:BaryCoordNoPerspSampleAMD:: 1335 1336The code:BaryCoordNoPerspSampleAMD decoration can: be used to decorate a 1337fragment shader input variable. 1338This variable will contain the (I,J) pair of the barycentric coordinates 1339corresponding to the fragment evaluated using linear interpolation at each 1340covered sample. 1341The K coordinate of the barycentric coordinates can: be derived given the 1342identity I {plus} J {plus} K = 1.0. 1343 1344.Valid Usage 1345**** 1346 * [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04166]] 1347 The code:BaryCoordNoPerspSampleAMD decoration must: be used only within 1348 the code:Fragment {ExecutionModel} 1349 * [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04167]] 1350 The variable decorated with code:BaryCoordNoPerspSampleAMD must: be 1351 declared using the code:Input {StorageClass} 1352 * [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04168]] 1353 The variable decorated with code:BaryCoordNoPerspSampleAMD must: be 1354 declared as a two-component vector of 32-bit floating-point values 1355**** 1356-- 1357 1358[open,refpage='BaryCoordPullModelAMD',desc='Inverse barycentric coordinates of a fragment center',type='builtins'] 1359-- 1360:refpage: BaryCoordPullModelAMD 1361 1362code:BaryCoordPullModelAMD:: 1363 1364The code:BaryCoordPullModelAMD decoration can: be used to decorate a 1365fragment shader input variable. 1366This variable will contain (1/W, 1/I, 1/J) evaluated at the fragment center 1367and can: be used to calculate gradients and then interpolate I, J, and W at 1368any desired sample location. 1369 1370.Valid Usage 1371**** 1372 * [[VUID-{refpage}-BaryCoordPullModelAMD-04169]] 1373 The code:BaryCoordPullModelAMD decoration must: be used only within the 1374 code:Fragment {ExecutionModel} 1375 * [[VUID-{refpage}-BaryCoordPullModelAMD-04170]] 1376 The variable decorated with code:BaryCoordPullModelAMD must: be declared 1377 using the code:Input {StorageClass} 1378 * [[VUID-{refpage}-BaryCoordPullModelAMD-04171]] 1379 The variable decorated with code:BaryCoordPullModelAMD must: be declared 1380 as a three-component vector of 32-bit floating-point values 1381**** 1382-- 1383 1384[open,refpage='BaryCoordSmoothAMD',desc='Barycentric coordinates of a fragment center',type='builtins'] 1385-- 1386:refpage: BaryCoordSmoothAMD 1387 1388code:BaryCoordSmoothAMD:: 1389 1390The code:BaryCoordSmoothAMD decoration can: be used to decorate a fragment 1391shader input variable. 1392This variable will contain the (I,J) pair of the barycentric coordinates 1393corresponding to the fragment evaluated using perspective interpolation at 1394the fragment's center. 1395The K coordinate of the barycentric coordinates can: be derived given the 1396identity I {plus} J {plus} K = 1.0. 1397 1398.Valid Usage 1399**** 1400 * [[VUID-{refpage}-BaryCoordSmoothAMD-04172]] 1401 The code:BaryCoordSmoothAMD decoration must: be used only within the 1402 code:Fragment {ExecutionModel} 1403 * [[VUID-{refpage}-BaryCoordSmoothAMD-04173]] 1404 The variable decorated with code:BaryCoordSmoothAMD must: be declared 1405 using the code:Input {StorageClass} 1406 * [[VUID-{refpage}-BaryCoordSmoothAMD-04174]] 1407 The variable decorated with code:BaryCoordSmoothAMD must: be declared as 1408 a two-component vector of 32-bit floating-point values 1409**** 1410-- 1411 1412[open,refpage='BaryCoordSmoothCentroidAMD',desc='Barycentric coordinates of a fragment centroid',type='builtins'] 1413-- 1414:refpage: BaryCoordSmoothCentroidAMD 1415 1416code:BaryCoordSmoothCentroidAMD:: 1417 1418The code:BaryCoordSmoothCentroidAMD decoration can: be used to decorate a 1419fragment shader input variable. 1420This variable will contain the (I,J) pair of the barycentric coordinates 1421corresponding to the fragment evaluated using perspective interpolation at 1422the centroid. 1423The K coordinate of the barycentric coordinates can: be derived given the 1424identity I {plus} J {plus} K = 1.0. 1425 1426.Valid Usage 1427**** 1428 * [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04175]] 1429 The code:BaryCoordSmoothCentroidAMD decoration must: be used only within 1430 the code:Fragment {ExecutionModel} 1431 * [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04176]] 1432 The variable decorated with code:BaryCoordSmoothCentroidAMD must: be 1433 declared using the code:Input {StorageClass} 1434 * [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04177]] 1435 The variable decorated with code:BaryCoordSmoothCentroidAMD must: be 1436 declared as a two-component vector of 32-bit floating-point values 1437**** 1438-- 1439 1440[open,refpage='BaryCoordSmoothSampleAMD',desc='Barycentric coordinates of a sample center',type='builtins'] 1441-- 1442:refpage: BaryCoordSmoothSampleAMD 1443 1444code:BaryCoordSmoothSampleAMD:: 1445 1446The code:BaryCoordSmoothSampleAMD decoration can: be used to decorate a 1447fragment shader input variable. 1448This variable will contain the (I,J) pair of the barycentric coordinates 1449corresponding to the fragment evaluated using perspective interpolation at 1450each covered sample. 1451The K coordinate of the barycentric coordinates can: be derived given the 1452identity I {plus} J {plus} K = 1.0. 1453 1454.Valid Usage 1455**** 1456 * [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04178]] 1457 The code:BaryCoordSmoothSampleAMD decoration must: be used only within 1458 the code:Fragment {ExecutionModel} 1459 * [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04179]] 1460 The variable decorated with code:BaryCoordSmoothSampleAMD must: be 1461 declared using the code:Input {StorageClass} 1462 * [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04180]] 1463 The variable decorated with code:BaryCoordSmoothSampleAMD must: be 1464 declared as a two-component vector of 32-bit floating-point values 1465**** 1466-- 1467endif::VK_AMD_shader_explicit_vertex_parameter[] 1468 1469 1470ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1471[[interfaces-builtin-variables-baseinstance]] 1472[open,refpage='BaseInstance',desc='First instance being rendered',type='builtins'] 1473-- 1474:refpage: BaseInstance 1475 1476code:BaseInstance:: 1477 1478Decorating a variable with the code:BaseInstance built-in will make that 1479variable contain the integer value corresponding to the first instance that 1480was passed to the command that invoked the current vertex shader invocation. 1481code:BaseInstance is the pname:firstInstance parameter to a _direct drawing 1482command_ or the pname:firstInstance member of a structure consumed by an 1483_indirect drawing command_. 1484 1485.Valid Usage 1486**** 1487 * [[VUID-{refpage}-BaseInstance-04181]] 1488 The code:BaseInstance decoration must: be used only within the 1489 code:Vertex {ExecutionModel} 1490 * [[VUID-{refpage}-BaseInstance-04182]] 1491 The variable decorated with code:BaseInstance must: be declared using 1492 the code:Input {StorageClass} 1493 * [[VUID-{refpage}-BaseInstance-04183]] 1494 The variable decorated with code:BaseInstance must: be declared as a 1495 scalar 32-bit integer value 1496**** 1497-- 1498 1499[[interfaces-builtin-variables-basevertex]] 1500[open,refpage='BaseVertex',desc='First vertex being rendered',type='builtins'] 1501-- 1502:refpage: BaseVertex 1503 1504code:BaseVertex:: 1505 1506Decorating a variable with the code:BaseVertex built-in will make that 1507variable contain the integer value corresponding to the first vertex or 1508vertex offset that was passed to the command that invoked the current vertex 1509shader invocation. 1510For _non-indexed drawing commands_, this variable is the pname:firstVertex 1511parameter to a _direct drawing command_ or the pname:firstVertex member of 1512the structure consumed by an _indirect drawing command_. 1513For _indexed drawing commands_, this variable is the pname:vertexOffset 1514parameter to a _direct drawing command_ or the pname:vertexOffset member of 1515the structure consumed by an _indirect drawing command_. 1516 1517.Valid Usage 1518**** 1519 * [[VUID-{refpage}-BaseVertex-04184]] 1520 The code:BaseVertex decoration must: be used only within the code:Vertex 1521 {ExecutionModel} 1522 * [[VUID-{refpage}-BaseVertex-04185]] 1523 The variable decorated with code:BaseVertex must: be declared using the 1524 code:Input {StorageClass} 1525 * [[VUID-{refpage}-BaseVertex-04186]] 1526 The variable decorated with code:BaseVertex must: be declared as a 1527 scalar 32-bit integer value 1528**** 1529-- 1530endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1531 1532[open,refpage='ClipDistance',desc='Application-specified clip distances',type='builtins'] 1533-- 1534:refpage: ClipDistance 1535 1536code:ClipDistance:: 1537 1538Decorating a variable with the code:ClipDistance built-in decoration will 1539make that variable contain the mechanism for controlling user clipping. 1540code:ClipDistance is an array such that the i^th^ element of the array 1541specifies the clip distance for plane i. 1542A clip distance of 0 means the vertex is on the plane, a positive distance 1543means the vertex is inside the clip half-space, and a negative distance 1544means the vertex is outside the clip half-space. 1545 1546[NOTE] 1547.Note 1548==== 1549The array variable decorated with code:ClipDistance is explicitly sized by 1550the shader. 1551==== 1552 1553[NOTE] 1554.Note 1555==== 1556In the last <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization 1557shader stage>>, these values will be linearly interpolated across the 1558primitive and the portion of the primitive with interpolated distances less 1559than 0 will be considered outside the clip volume. 1560If code:ClipDistance is then used by a fragment shader, code:ClipDistance 1561contains these linearly interpolated values. 1562==== 1563 1564.Valid Usage 1565**** 1566 * [[VUID-{refpage}-ClipDistance-04187]] 1567 The code:ClipDistance decoration must: be used only within the 1568 code:MeshNV, code:Vertex, code:Fragment, code:TessellationControl, 1569 code:TessellationEvaluation, or code:Geometry {ExecutionModel} 1570 * [[VUID-{refpage}-ClipDistance-04188]] 1571 The variable decorated with code:ClipDistance within the code:MeshNV or 1572 code:Vertex {ExecutionModel} must: be declared using the code:Output 1573 {StorageClass} 1574 * [[VUID-{refpage}-ClipDistance-04189]] 1575 The variable decorated with code:ClipDistance within the code:Fragment 1576 {ExecutionModel} must: be declared using the code:Input {StorageClass} 1577 * [[VUID-{refpage}-ClipDistance-04190]] 1578 The variable decorated with code:ClipDistance within the 1579 code:TessellationControl, code:TessellationEvaluation, or code:Geometry 1580 {ExecutionModel} must: not be declared in a {StorageClass} other than 1581 code:Input or code:Output 1582 * [[VUID-{refpage}-ClipDistance-04191]] 1583 The variable decorated with code:ClipDistance must: be declared as an 1584 array of 32-bit floating-point values 1585**** 1586-- 1587 1588ifdef::VK_NV_mesh_shader[] 1589[[interfaces-builtin-variables-clipdistancepv]] 1590[open,refpage='ClipDistancePerViewNV',desc='Application-specified clip distances per view',type='builtins'] 1591-- 1592:refpage: ClipDistancePerViewNV 1593 1594code:ClipDistancePerViewNV:: 1595 1596Decorating a variable with the code:ClipDistancePerViewNV built-in 1597decoration will make that variable contain the per-view clip distances. 1598The per-view clip distances have the same semantics as code:ClipDistance. 1599 1600.Valid Usage 1601**** 1602 * [[VUID-{refpage}-ClipDistancePerViewNV-04192]] 1603 The code:ClipDistancePerViewNV decoration must: be used only within the 1604 code:MeshNV {ExecutionModel} 1605 * [[VUID-{refpage}-ClipDistancePerViewNV-04193]] 1606 The variable decorated with code:ClipDistancePerViewNV must: be declared 1607 using the code:Output {StorageClass} 1608 * [[VUID-{refpage}-ClipDistancePerViewNV-04194]] 1609 The variable decorated with code:ClipDistancePerViewNV must: also be 1610 decorated with the code:PerViewNV decoration 1611 * [[VUID-{refpage}-ClipDistancePerViewNV-04195]] 1612 The variable decorated with code:ClipDistancePerViewNV must: be declared 1613 as a two-dimensional array of 32-bit floating-point values 1614**** 1615-- 1616endif::VK_NV_mesh_shader[] 1617 1618[open,refpage='CullDistance',desc='Application-specified cull distances',type='builtins'] 1619-- 1620:refpage: CullDistance 1621 1622code:CullDistance:: 1623 1624Decorating a variable with the code:CullDistance built-in decoration will 1625make that variable contain the mechanism for controlling user culling. 1626If any member of this array is assigned a negative value for all vertices 1627belonging to a primitive, then the primitive is discarded before 1628rasterization. 1629 1630[NOTE] 1631.Note 1632==== 1633In fragment shaders, the values of the code:CullDistance array are linearly 1634interpolated across each primitive. 1635==== 1636 1637[NOTE] 1638.Note 1639==== 1640If code:CullDistance decorates an input variable, that variable will contain 1641the corresponding value from the code:CullDistance decorated output variable 1642from the previous shader stage. 1643==== 1644 1645.Valid Usage 1646**** 1647 * [[VUID-{refpage}-CullDistance-04196]] 1648 The code:CullDistance decoration must: be used only within the 1649 code:MeshNV, code:Vertex, code:Fragment, code:TessellationControl, 1650 code:TessellationEvaluation, or code:Geometry {ExecutionModel} 1651 * [[VUID-{refpage}-CullDistance-04197]] 1652 The variable decorated with code:CullDistance within the code:MeshNV or 1653 code:Vertex {ExecutionModel} must: be declared using the code:Output 1654 {StorageClass} 1655 * [[VUID-{refpage}-CullDistance-04198]] 1656 The variable decorated with code:CullDistance within the code:Fragment 1657 {ExecutionModel} must: be declared using the code:Input {StorageClass} 1658 * [[VUID-{refpage}-CullDistance-04199]] 1659 The variable decorated with code:CullDistance within the 1660 code:TessellationControl, code:TessellationEvaluation, or code:Geometry 1661 {ExecutionModel} must: not be declared using a {StorageClass} other than 1662 code:Input or code:Output 1663 * [[VUID-{refpage}-CullDistance-04200]] 1664 The variable decorated with code:CullDistance must: be declared as an 1665 array of 32-bit floating-point values 1666**** 1667-- 1668 1669ifdef::VK_NV_mesh_shader[] 1670[[interfaces-builtin-variables-culldistancepv]] 1671[open,refpage='CullDistancePerViewNV',desc='Application-specified cull distances per view',type='builtins'] 1672-- 1673:refpage: CullDistancePerViewNV 1674 1675code:CullDistancePerViewNV:: 1676 1677Decorating a variable with the code:CullDistancePerViewNV built-in 1678decoration will make that variable contain the per-view cull distances. 1679The per-view cull distances have the same semantics as code:CullDistance. 1680 1681.Valid Usage 1682**** 1683 * [[VUID-{refpage}-CullDistancePerViewNV-04201]] 1684 The code:CullDistancePerViewNV decoration must: be used only within the 1685 code:MeshNV {ExecutionModel} 1686 * [[VUID-{refpage}-CullDistancePerViewNV-04202]] 1687 The variable decorated with code:CullDistancePerViewNV must: be declared 1688 using the code:Output {StorageClass} 1689 * [[VUID-{refpage}-CullDistancePerViewNV-04203]] 1690 The variable decorated with code:CullDistancePerViewNV must: also be 1691 decorated with the code:PerViewNV decoration 1692 * [[VUID-{refpage}-CullDistancePerViewNV-04204]] 1693 The variable decorated with code:CullDistancePerViewNV must: be declared 1694 as a two-dimensional array of 32-bit floating-point values 1695**** 1696-- 1697endif::VK_NV_mesh_shader[] 1698 1699ifdef::VK_NV_ray_tracing_motion_blur[] 1700[[interfaces-builtin-variables-currentraytime]] 1701[open,refpage='CurrentRayTimeNV',desc='Time value of a ray intersection',type='builtins'] 1702-- 1703:refpage: CurrentRayTimeNV 1704 1705code:CurrentRayTimeNV:: 1706 1707A variable decorated with the code:CurrentRayTimeNV decoration contains the 1708time value passed in to code:OpTraceRayMotionNV which called this shader. 1709 1710.Valid Usage 1711**** 1712 * [[VUID-{refpage}-CurrentRayTimeNV-04942]] 1713 The code:CurrentRayTimeNV decoration must: be used only within the 1714 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 1715 code:MissKHR {ExecutionModel} 1716 * [[VUID-{refpage}-CurrentRayTimeNV-04943]] 1717 The variable decorated with code:CurrentRayTimeNV must: be declared 1718 using the code:Input {StorageClass} 1719 * [[VUID-{refpage}-CurrentRayTimeNV-04944]] 1720 The variable decorated with code:CurrentRayTimeNV must: be declared as a 1721 scalar 32-bit floating-point value 1722**** 1723-- 1724endif::VK_NV_ray_tracing_motion_blur[] 1725 1726 1727ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1728[[interfaces-builtin-variables-deviceindex]] 1729[open,refpage='DeviceIndex',desc='Index of the device executing the shader',type='builtins'] 1730-- 1731:refpage: DeviceIndex 1732 1733code:DeviceIndex:: 1734 1735The code:DeviceIndex decoration can: be applied to a shader input which will 1736be filled with the device index of the physical device that is executing the 1737current shader invocation. 1738This value will be in the range latexmath:[[0,max(1,physicalDeviceCount))], 1739where physicalDeviceCount is the pname:physicalDeviceCount member of 1740slink:VkDeviceGroupDeviceCreateInfo. 1741 1742.Valid Usage 1743**** 1744 * [[VUID-{refpage}-DeviceIndex-04205]] 1745 The variable decorated with code:DeviceIndex must: be declared using the 1746 code:Input {StorageClass} 1747 * [[VUID-{refpage}-DeviceIndex-04206]] 1748 The variable decorated with code:DeviceIndex must: be declared as a 1749 scalar 32-bit integer value 1750**** 1751-- 1752endif::VK_VERSION_1_1,VK_KHR_device_group[] 1753 1754ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1755[[interfaces-builtin-variables-drawindex]] 1756[open,refpage='DrawIndex',desc='Index of the current draw',type='builtins'] 1757-- 1758:refpage: DrawIndex 1759 1760code:DrawIndex:: 1761 1762Decorating a variable with the code:DrawIndex built-in will make that 1763variable contain the integer value corresponding to the zero-based index of 1764the drawing command that invoked the current 1765ifdef::VK_NV_mesh_shader[] 1766task, mesh, or 1767endif::VK_NV_mesh_shader[] 1768vertex shader invocation. 1769For _indirect drawing commands_, code:DrawIndex begins at zero and 1770increments by one for each drawing command executed. 1771The number of drawing commands is given by the pname:drawCount parameter. 1772For _direct drawing commands_, 1773ifdef::VK_EXT_multi_draw[] 1774if flink:vkCmdDrawMultiEXT or flink:vkCmdDrawMultiIndexedEXT is used, this 1775variable contains the integer value corresponding to the zero-based index of 1776the draw command. 1777Otherwise 1778endif::VK_EXT_multi_draw[] 1779code:DrawIndex is always zero. 1780code:DrawIndex is dynamically uniform. 1781 1782ifdef::VK_NV_mesh_shader[] 1783When task or mesh shaders are used, only the first active stage will have 1784proper access to the variable. 1785The value read by other stages is undefined:. 1786endif::VK_NV_mesh_shader[] 1787 1788.Valid Usage 1789**** 1790 * [[VUID-{refpage}-DrawIndex-04207]] 1791 The code:DrawIndex decoration must: be used only within the code:Vertex, 1792 code:MeshNV, or code:TaskNV {ExecutionModel} 1793 * [[VUID-{refpage}-DrawIndex-04208]] 1794 The variable decorated with code:DrawIndex must: be declared using the 1795 code:Input {StorageClass} 1796 * [[VUID-{refpage}-DrawIndex-04209]] 1797 The variable decorated with code:DrawIndex must: be declared as a scalar 1798 32-bit integer value 1799**** 1800-- 1801endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] 1802 1803[open,refpage='FragCoord',desc='Screen-space coordinate of the fragment center',type='builtins'] 1804-- 1805:refpage: FragCoord 1806 1807code:FragCoord:: 1808 1809Decorating a variable with the code:FragCoord built-in decoration will make 1810that variable contain the framebuffer coordinate 1811latexmath:[(x,y,z,\frac{1}{w})] of the fragment being processed. 1812The [eq]#(x,y)# coordinate [eq]#(0,0)# is the upper left corner of the upper 1813left pixel in the framebuffer. 1814+ 1815When <<primsrast-sampleshading,Sample Shading>> is enabled, the [eq]#x# and 1816[eq]#y# components of code:FragCoord reflect the location of one of the 1817samples corresponding to the shader invocation. 1818+ 1819Otherwise, the [eq]#x# and [eq]#y# components of code:FragCoord reflect the 1820location of the center of the fragment. 1821+ 1822The [eq]#z# component of code:FragCoord is the interpolated depth value of 1823the primitive. 1824+ 1825The [eq]#w# component is the interpolated latexmath:[\frac{1}{w}]. 1826+ 1827The code:Centroid interpolation decoration is ignored, but allowed, on 1828code:FragCoord. 1829 1830.Valid Usage 1831**** 1832 * [[VUID-{refpage}-FragCoord-04210]] 1833 The code:FragCoord decoration must: be used only within the 1834 code:Fragment {ExecutionModel} 1835 * [[VUID-{refpage}-FragCoord-04211]] 1836 The variable decorated with code:FragCoord must: be declared using the 1837 code:Input {StorageClass} 1838 * [[VUID-{refpage}-FragCoord-04212]] 1839 The variable decorated with code:FragCoord must: be declared as a 1840 four-component vector of 32-bit floating-point values 1841**** 1842-- 1843 1844[[interfaces-builtin-variables-fragdepth]] 1845[open,refpage='FragDepth',desc='Application-specified depth for depth testing',type='builtins'] 1846-- 1847:refpage: FragDepth 1848 1849code:FragDepth:: 1850 1851To have a shader supply a fragment-depth value, the shader must: declare the 1852code:DepthReplacing execution mode. 1853Such a shader's fragment-depth value will come from the variable decorated 1854with the code:FragDepth built-in decoration. 1855+ 1856This value will be used for any subsequent depth testing performed by the 1857implementation or writes to the depth attachment. 1858See <<fragops-shader-depthreplacement, fragment shader depth replacement>> 1859for details. 1860 1861.Valid Usage 1862**** 1863 * [[VUID-{refpage}-FragDepth-04213]] 1864 The code:FragDepth decoration must: be used only within the 1865 code:Fragment {ExecutionModel} 1866 * [[VUID-{refpage}-FragDepth-04214]] 1867 The variable decorated with code:FragDepth must: be declared using the 1868 code:Output {StorageClass} 1869 * [[VUID-{refpage}-FragDepth-04215]] 1870 The variable decorated with code:FragDepth must: be declared as a scalar 1871 32-bit floating-point value 1872 * [[VUID-{refpage}-FragDepth-04216]] 1873 If the shader dynamically writes to the variable decorated with 1874 code:FragDepth, the code:DepthReplacing {ExecutionMode} must: be 1875 declared 1876**** 1877-- 1878 1879ifdef::VK_EXT_fragment_density_map[] 1880[[interfaces-builtin-variables-fraginvocationcount]] 1881[open,refpage='FragInvocationCountEXT',desc='Number of fragment shader invocations for a fragment',type='builtins'] 1882-- 1883:refpage: FragInvocationCountEXT 1884 1885code:FragInvocationCountEXT:: 1886 1887Decorating a variable with the code:FragInvocationCountEXT built-in 1888decoration will make that variable contain the maximum number of fragment 1889shader invocations for the fragment, as determined by 1890pname:minSampleShading. 1891+ 1892If <<primsrast-sampleshading,Sample Shading>> is not enabled, 1893code:FragInvocationCountEXT will be filled with a value of 1. 1894 1895.Valid Usage 1896**** 1897 * [[VUID-{refpage}-FragInvocationCountEXT-04217]] 1898 The code:FragInvocationCountEXT decoration must: be used only within the 1899 code:Fragment {ExecutionModel} 1900 * [[VUID-{refpage}-FragInvocationCountEXT-04218]] 1901 The variable decorated with code:FragInvocationCountEXT must: be 1902 declared using the code:Input {StorageClass} 1903 * [[VUID-{refpage}-FragInvocationCountEXT-04219]] 1904 The variable decorated with code:FragInvocationCountEXT must: be 1905 declared as a scalar 32-bit integer value 1906**** 1907-- 1908endif::VK_EXT_fragment_density_map[] 1909 1910ifdef::VK_EXT_fragment_density_map[] 1911[[interfaces-builtin-variables-fragsize]] 1912[open,refpage='FragSizeEXT',desc='Size of the screen-space area covered by the fragment',type='builtins'] 1913-- 1914:refpage: FragSizeEXT 1915 1916code:FragSizeEXT:: 1917 1918Decorating a variable with the code:FragSizeEXT built-in decoration will 1919make that variable contain the dimensions in pixels of the 1920<<glossary-fragment-area,area>> that the fragment covers for that 1921invocation. 1922+ 1923If fragment density map is not enabled, code:FragSizeEXT will be filled with 1924a value of [eq]#(1,1)#. 1925 1926.Valid Usage 1927**** 1928 * [[VUID-{refpage}-FragSizeEXT-04220]] 1929 The code:FragSizeEXT decoration must: be used only within the 1930 code:Fragment {ExecutionModel} 1931 * [[VUID-{refpage}-FragSizeEXT-04221]] 1932 The variable decorated with code:FragSizeEXT must: be declared using the 1933 code:Input {StorageClass} 1934 * [[VUID-{refpage}-FragSizeEXT-04222]] 1935 The variable decorated with code:FragSizeEXT must: be declared as a 1936 two-component vector of 32-bit integer values 1937**** 1938-- 1939endif::VK_EXT_fragment_density_map[] 1940 1941ifdef::VK_EXT_shader_stencil_export[] 1942[[interfaces-builtin-variables-fragstencilref]] 1943[open,refpage='FragStencilRefEXT',desc='Application-specified stencil reference value used in stencil tests',type='builtins'] 1944-- 1945:refpage: FragStencilRefEXT 1946 1947code:FragStencilRefEXT:: 1948 1949Decorating a variable with the code:FragStencilRefEXT built-in decoration 1950will make that variable contain the new stencil reference value for all 1951samples covered by the fragment. 1952This value will be used as the stencil reference value used in stencil 1953testing. 1954+ 1955To write to code:FragStencilRefEXT, a shader must: declare the 1956code:StencilRefReplacingEXT execution mode. 1957If a shader declares the code:StencilRefReplacingEXT execution mode and 1958there is an execution path through the shader that does not set 1959code:FragStencilRefEXT, then the fragment's stencil reference value is 1960undefined: for executions of the shader that take that path. 1961+ 1962Only the least significant *s* bits of the integer value of the variable 1963decorated with code:FragStencilRefEXT are considered for stencil testing, 1964where *s* is the number of bits in the stencil framebuffer attachment, and 1965higher order bits are discarded. 1966+ 1967See <<fragops-shader-stencilrefreplacement, fragment shader stencil 1968reference replacement>> for more details. 1969 1970.Valid Usage 1971**** 1972 * [[VUID-{refpage}-FragStencilRefEXT-04223]] 1973 The code:FragStencilRefEXT decoration must: be used only within the 1974 code:Fragment {ExecutionModel} 1975 * [[VUID-{refpage}-FragStencilRefEXT-04224]] 1976 The variable decorated with code:FragStencilRefEXT must: be declared 1977 using the code:Output {StorageClass} 1978 * [[VUID-{refpage}-FragStencilRefEXT-04225]] 1979 The variable decorated with code:FragStencilRefEXT must: be declared as 1980 a scalar integer value 1981**** 1982-- 1983endif::VK_EXT_shader_stencil_export[] 1984 1985ifdef::VK_NV_shading_rate_image[] 1986[open,refpage='FragmentSizeNV',desc='Size of the screen-space area covered by the fragment',type='builtins'] 1987-- 1988:refpage: FragmentSizeNV 1989 1990code:FragmentSizeNV:: 1991 1992Decorating a variable with the code:FragmentSizeNV built-in decoration will 1993make that variable contain the width and height of the fragment. 1994 1995.Valid Usage 1996**** 1997 * [[VUID-{refpage}-FragmentSizeNV-04226]] 1998 The code:FragmentSizeNV decoration must: be used only within the 1999 code:Fragment {ExecutionModel} 2000 * [[VUID-{refpage}-FragmentSizeNV-04227]] 2001 The variable decorated with code:FragmentSizeNV must: be declared using 2002 the code:Input {StorageClass} 2003 * [[VUID-{refpage}-FragmentSizeNV-04228]] 2004 The variable decorated with code:FragmentSizeNV must: be declared as a 2005 two-component vector of 32-bit integer values 2006**** 2007-- 2008endif::VK_NV_shading_rate_image[] 2009 2010 2011[open,refpage='FrontFacing',desc='Front face determination of a fragment',type='builtins'] 2012-- 2013:refpage: FrontFacing 2014 2015code:FrontFacing:: 2016 2017Decorating a variable with the code:FrontFacing built-in decoration will 2018make that variable contain whether the fragment is front or back facing. 2019This variable is non-zero if the current fragment is considered to be part 2020of a <<primsrast-polygons-basic,front-facing>> polygon primitive or of a 2021non-polygon primitive and is zero if the fragment is considered to be part 2022of a back-facing polygon primitive. 2023 2024.Valid Usage 2025**** 2026 * [[VUID-{refpage}-FrontFacing-04229]] 2027 The code:FrontFacing decoration must: be used only within the 2028 code:Fragment {ExecutionModel} 2029 * [[VUID-{refpage}-FrontFacing-04230]] 2030 The variable decorated with code:FrontFacing must: be declared using the 2031 code:Input {StorageClass} 2032 * [[VUID-{refpage}-FrontFacing-04231]] 2033 The variable decorated with code:FrontFacing must: be declared as a 2034 boolean value 2035**** 2036-- 2037 2038ifdef::VK_EXT_conservative_rasterization[] 2039[open,refpage='FullyCoveredEXT',desc='Indication of whether a fragment is fully covered',type='builtins'] 2040-- 2041:refpage: FullyCoveredEXT 2042 2043code:FullyCoveredEXT:: 2044 2045Decorating a variable with the code:FullyCoveredEXT built-in decoration will 2046make that variable indicate whether the <<glossary-fragment-area,fragment 2047area>> is fully covered by the generating primitive. 2048This variable is non-zero if conservative rasterization is enabled and the 2049current fragment area is fully covered by the generating primitive, and is 2050zero if the fragment is not covered or partially covered, or conservative 2051rasterization is disabled. 2052 2053.Valid Usage 2054**** 2055 * [[VUID-{refpage}-FullyCoveredEXT-04232]] 2056 The code:FullyCoveredEXT decoration must: be used only within the 2057 code:Fragment {ExecutionModel} 2058 * [[VUID-{refpage}-FullyCoveredEXT-04233]] 2059 The variable decorated with code:FullyCoveredEXT must: be declared using 2060 the code:Input {StorageClass} 2061 * [[VUID-{refpage}-FullyCoveredEXT-04234]] 2062 The variable decorated with code:FullyCoveredEXT must: be declared as a 2063 boolean value 2064ifdef::VK_EXT_post_depth_coverage[] 2065 * [[VUID-{refpage}-conservativeRasterizationPostDepthCoverage-04235]] 2066 If 2067 sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage 2068 is not supported the code:PostDepthCoverage {ExecutionMode} must: not be 2069 declared, when a variable with the code:FullyCoveredEXT decoration is 2070 declared 2071endif::VK_EXT_post_depth_coverage[] 2072**** 2073-- 2074endif::VK_EXT_conservative_rasterization[] 2075 2076[open,refpage='GlobalInvocationId',desc='Global invocation ID',type='builtins'] 2077-- 2078:refpage: GlobalInvocationId 2079 2080code:GlobalInvocationId:: 2081 2082Decorating a variable with the code:GlobalInvocationId built-in decoration 2083will make that variable contain the location of the current invocation 2084within the global workgroup. 2085Each component is equal to the index of the local workgroup multiplied by 2086the size of the local workgroup plus code:LocalInvocationId. 2087 2088.Valid Usage 2089**** 2090 * [[VUID-{refpage}-GlobalInvocationId-04236]] 2091 The code:GlobalInvocationId decoration must: be used only within the 2092 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 2093 * [[VUID-{refpage}-GlobalInvocationId-04237]] 2094 The variable decorated with code:GlobalInvocationId must: be declared 2095 using the code:Input {StorageClass} 2096 * [[VUID-{refpage}-GlobalInvocationId-04238]] 2097 The variable decorated with code:GlobalInvocationId must: be declared as 2098 a three-component vector of 32-bit integer values 2099**** 2100-- 2101 2102[open,refpage='HelperInvocation',desc='Indication of whether a fragment shader is a helper invocation',type='builtins'] 2103-- 2104:refpage: HelperInvocation 2105 2106code:HelperInvocation:: 2107 2108Decorating a variable with the code:HelperInvocation built-in decoration 2109will make that variable contain whether the current invocation is a helper 2110invocation. 2111This variable is non-zero if the current fragment being shaded is a helper 2112invocation and zero otherwise. 2113A helper invocation is an invocation of the shader that is produced to 2114satisfy internal requirements such as the generation of derivatives. 2115 2116[NOTE] 2117.Note 2118==== 2119It is very likely that a helper invocation will have a value of 2120code:SampleMask fragment shader input value that is zero. 2121==== 2122 2123.Valid Usage 2124**** 2125 * [[VUID-{refpage}-HelperInvocation-04239]] 2126 The code:HelperInvocation decoration must: be used only within the 2127 code:Fragment {ExecutionModel} 2128 * [[VUID-{refpage}-HelperInvocation-04240]] 2129 The variable decorated with code:HelperInvocation must: be declared 2130 using the code:Input {StorageClass} 2131 * [[VUID-{refpage}-HelperInvocation-04241]] 2132 The variable decorated with code:HelperInvocation must: be declared as a 2133 boolean value 2134**** 2135-- 2136 2137ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2138[[interfaces-builtin-variables-hitkind]] 2139[open,refpage='HitKindKHR',desc='Kind of hit that triggered an any-hit or closest hit ray shader',type='builtins'] 2140-- 2141:refpage: HitKindKHR 2142 2143code:HitKindKHR:: 2144 2145A variable decorated with the code:HitKindKHR decoration will describe the 2146intersection that triggered the execution of the current shader. 2147The values are determined by the intersection shader. 2148For user-defined intersection shaders this is the value that was passed to 2149the "`Hit Kind`" operand of code:OpReportIntersectionKHR. 2150For triangle intersection candidates, this will be one of 2151code:HitKindFrontFacingTriangleKHR or code:HitKindBackFacingTriangleKHR. 2152 2153.Valid Usage 2154**** 2155 * [[VUID-{refpage}-HitKindKHR-04242]] 2156 The code:HitKindKHR decoration must: be used only within the 2157 code:AnyHitKHR or code:ClosestHitKHR {ExecutionModel} 2158 * [[VUID-{refpage}-HitKindKHR-04243]] 2159 The variable decorated with code:HitKindKHR must: be declared using the 2160 code:Input {StorageClass} 2161 * [[VUID-{refpage}-HitKindKHR-04244]] 2162 The variable decorated with code:HitKindKHR must: be declared as a 2163 scalar 32-bit integer value 2164**** 2165-- 2166 2167ifdef::VK_NV_ray_tracing[] 2168[[interfaces-builtin-variables-hitt]] 2169[open,refpage='HitTNV',desc='T value of a ray intersection',type='builtins'] 2170-- 2171:refpage: HitTNV 2172 2173code:HitTNV:: 2174 2175A variable decorated with the code:HitTNV decoration is equivalent to a 2176variable decorated with the code:RayTmaxKHR decoration. 2177 2178.Valid Usage 2179**** 2180 * [[VUID-{refpage}-HitTNV-04245]] 2181 The code:HitTNV decoration must: be used only within the code:AnyHitNV 2182 or code:ClosestHitNV {ExecutionModel} 2183 * [[VUID-{refpage}-HitTNV-04246]] 2184 The variable decorated with code:HitTNV must: be declared using the 2185 code:Input {StorageClass} 2186 * [[VUID-{refpage}-HitTNV-04247]] 2187 The variable decorated with code:HitTNV must: be declared as a scalar 2188 32-bit floating-point value 2189**** 2190-- 2191endif::VK_NV_ray_tracing[] 2192 2193[[interfaces-builtin-variables-incomingrayflags]] 2194[open,refpage='IncomingRayFlagsKHR',desc='Flags used to trace a ray',type='builtins'] 2195-- 2196:refpage: IncomingRayFlagsKHR 2197 2198code:IncomingRayFlagsKHR:: 2199 2200A variable with the code:IncomingRayFlagsKHR decoration will contain the ray 2201flags passed in to the trace call that invoked this particular shader. 2202Setting pipeline flags on the raytracing pipeline must: not cause any 2203corresponding flags to be set in variables with this decoration. 2204 2205.Valid Usage 2206**** 2207 * [[VUID-{refpage}-IncomingRayFlagsKHR-04248]] 2208 The code:IncomingRayFlagsKHR decoration must: be used only within the 2209 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 2210 code:MissKHR {ExecutionModel} 2211 * [[VUID-{refpage}-IncomingRayFlagsKHR-04249]] 2212 The variable decorated with code:IncomingRayFlagsKHR must: be declared 2213 using the code:Input {StorageClass} 2214 * [[VUID-{refpage}-IncomingRayFlagsKHR-04250]] 2215 The variable decorated with code:IncomingRayFlagsKHR must: be declared 2216 as a scalar 32-bit integer value 2217**** 2218-- 2219 2220[[interfaces-builtin-variables-instancecustomindex]] 2221[open,refpage='InstanceCustomIndexKHR',desc='Custom index associated with an intersected instance',type='builtins'] 2222-- 2223:refpage: InstanceCustomIndexKHR 2224 2225code:InstanceCustomIndexKHR:: 2226 2227A variable decorated with the code:InstanceCustomIndexKHR decoration will 2228contain the application-defined value of the instance that intersects the 2229current ray. 2230This variable contains the value that was specified in 2231slink:VkAccelerationStructureInstanceKHR::pname:instanceCustomIndex for the 2232current acceleration structure instance in the lower 24 bits and the upper 8 2233bits will be zero. 2234 2235.Valid Usage 2236**** 2237 * [[VUID-{refpage}-InstanceCustomIndexKHR-04251]] 2238 The code:InstanceCustomIndexKHR decoration must: be used only within the 2239 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 2240 {ExecutionModel} 2241 * [[VUID-{refpage}-InstanceCustomIndexKHR-04252]] 2242 The variable decorated with code:InstanceCustomIndexKHR must: be 2243 declared using the code:Input {StorageClass} 2244 * [[VUID-{refpage}-InstanceCustomIndexKHR-04253]] 2245 The variable decorated with code:InstanceCustomIndexKHR must: be 2246 declared as a scalar 32-bit integer value 2247**** 2248-- 2249 2250[[interfaces-builtin-variables-instanceid]] 2251[open,refpage='InstanceId',desc='Id associated with an intersected instance',type='builtins'] 2252-- 2253:refpage: InstanceId 2254 2255code:InstanceId:: 2256 2257Decorating a variable in an intersection, any-hit, or closest hit shader 2258with the code:InstanceId decoration will make that variable contain the 2259index of the instance that intersects the current ray. 2260 2261.Valid Usage 2262**** 2263 * [[VUID-{refpage}-InstanceId-04254]] 2264 The code:InstanceId decoration must: be used only within the 2265 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 2266 {ExecutionModel} 2267 * [[VUID-{refpage}-InstanceId-04255]] 2268 The variable decorated with code:InstanceId must: be declared using the 2269 code:Input {StorageClass} 2270 * [[VUID-{refpage}-InstanceId-04256]] 2271 The variable decorated with code:InstanceId must: be declared as a 2272 scalar 32-bit integer value 2273**** 2274-- 2275endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2276 2277[open,refpage='InvocationId',desc='Invocation ID in a geometry or tessellation control shader',type='builtins'] 2278-- 2279:refpage: InvocationId 2280 2281code:InvocationId:: 2282 2283Decorating a variable with the code:InvocationId built-in decoration will 2284make that variable contain the index of the current shader invocation in a 2285geometry shader, or the index of the output patch vertex in a tessellation 2286control shader. 2287+ 2288In a geometry shader, the index of the current shader invocation ranges from 2289zero to the number of <<geometry-invocations,instances>> declared in the 2290shader minus one. 2291If the instance count of the geometry shader is one or is not specified, 2292then code:InvocationId will be zero. 2293 2294.Valid Usage 2295**** 2296 * [[VUID-{refpage}-InvocationId-04257]] 2297 The code:InvocationId decoration must: be used only within the 2298 code:TessellationControl or code:Geometry {ExecutionModel} 2299 * [[VUID-{refpage}-InvocationId-04258]] 2300 The variable decorated with code:InvocationId must: be declared using 2301 the code:Input {StorageClass} 2302 * [[VUID-{refpage}-InvocationId-04259]] 2303 The variable decorated with code:InvocationId must: be declared as a 2304 scalar 32-bit integer value 2305**** 2306-- 2307 2308ifdef::VK_NV_shading_rate_image[] 2309[open,refpage='InvocationsPerPixelNV',desc='Number of fragment shader invocations for the current pixel',type='builtins'] 2310-- 2311:refpage: InvocationsPerPixelNV 2312 2313code:InvocationsPerPixelNV:: 2314 2315Decorating a variable with the code:InvocationsPerPixelNV built-in 2316decoration will make that variable contain the maximum number of fragment 2317shader invocations per pixel, as derived from the effective shading rate for 2318the fragment. 2319If a primitive does not fully cover a pixel, the number of fragment shader 2320invocations for that pixel may: be less than the value of 2321code:InvocationsPerPixelNV. 2322If the shading rate indicates a fragment covering multiple pixels, then 2323code:InvocationsPerPixelNV will be one. 2324 2325.Valid Usage 2326**** 2327 * [[VUID-{refpage}-InvocationsPerPixelNV-04260]] 2328 The code:InvocationsPerPixelNV decoration must: be used only within the 2329 code:Fragment {ExecutionModel} 2330 * [[VUID-{refpage}-InvocationsPerPixelNV-04261]] 2331 The variable decorated with code:InvocationsPerPixelNV must: be declared 2332 using the code:Input {StorageClass} 2333 * [[VUID-{refpage}-InvocationsPerPixelNV-04262]] 2334 The variable decorated with code:InvocationsPerPixelNV must: be declared 2335 as a scalar 32-bit integer value 2336**** 2337-- 2338endif::VK_NV_shading_rate_image[] 2339 2340[open,refpage='InstanceIndex',desc='Index of an instance',type='builtins'] 2341-- 2342:refpage: InstanceIndex 2343 2344code:InstanceIndex:: 2345 2346Decorating a variable in a vertex shader with the code:InstanceIndex 2347built-in decoration will make that variable contain the index of the 2348instance that is being processed by the current vertex shader invocation. 2349code:InstanceIndex begins at the pname:firstInstance parameter to 2350flink:vkCmdDraw or flink:vkCmdDrawIndexed or at the pname:firstInstance 2351member of a structure consumed by flink:vkCmdDrawIndirect or 2352flink:vkCmdDrawIndexedIndirect. 2353 2354.Valid Usage 2355**** 2356 * [[VUID-{refpage}-InstanceIndex-04263]] 2357 The code:InstanceIndex decoration must: be used only within the 2358 code:Vertex {ExecutionModel} 2359 * [[VUID-{refpage}-InstanceIndex-04264]] 2360 The variable decorated with code:InstanceIndex must: be declared using 2361 the code:Input {StorageClass} 2362 * [[VUID-{refpage}-InstanceIndex-04265]] 2363 The variable decorated with code:InstanceIndex must: be declared as a 2364 scalar 32-bit integer value 2365**** 2366-- 2367 2368ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2369[[interfaces-builtin-variables-launchid]] 2370[open,refpage='LaunchIdKHR',desc='Launch Id for ray shaders',type='builtins'] 2371-- 2372:refpage: LaunchIdKHR 2373 2374code:LaunchIdKHR:: 2375 2376A variable decorated with the code:LaunchIdKHR decoration will specify the 2377index of the work item being processed. 2378One work item is generated for each of the pname:width {times} pname:height 2379{times} pname:depth items dispatched by a flink:vkCmdTraceRaysKHR command. 2380All shader invocations inherit the same value for variables decorated with 2381code:LaunchIdKHR. 2382 2383.Valid Usage 2384**** 2385 * [[VUID-{refpage}-LaunchIdKHR-04266]] 2386 The code:LaunchIdKHR decoration must: be used only within the 2387 code:RayGenerationKHR, code:IntersectionKHR, code:AnyHitKHR, 2388 code:ClosestHitKHR, code:MissKHR, or code:CallableKHR {ExecutionModel} 2389 * [[VUID-{refpage}-LaunchIdKHR-04267]] 2390 The variable decorated with code:LaunchIdKHR must: be declared using the 2391 code:Input {StorageClass} 2392 * [[VUID-{refpage}-LaunchIdKHR-04268]] 2393 The variable decorated with code:LaunchIdKHR must: be declared as a 2394 three-component vector of 32-bit integer values 2395**** 2396-- 2397 2398[[interfaces-builtin-variables-launchsize]] 2399[open,refpage='LaunchSizeKHR',desc='Launch dimensions for ray shaders',type='builtins'] 2400-- 2401:refpage: LaunchSizeKHR 2402 2403code:LaunchSizeKHR:: 2404 2405A variable decorated with the code:LaunchSizeKHR decoration will contain the 2406pname:width, pname:height, and pname:depth dimensions passed to the 2407flink:vkCmdTraceRaysKHR command that initiated this shader execution. 2408The pname:width is in the first component, the pname:height is in the second 2409component, and the pname:depth is in the third component. 2410 2411.Valid Usage 2412**** 2413 * [[VUID-{refpage}-LaunchSizeKHR-04269]] 2414 The code:LaunchSizeKHR decoration must: be used only within the 2415 code:RayGenerationKHR, code:IntersectionKHR, code:AnyHitKHR, 2416 code:ClosestHitKHR, code:MissKHR, or code:CallableKHR {ExecutionModel} 2417 * [[VUID-{refpage}-LaunchSizeKHR-04270]] 2418 The variable decorated with code:LaunchSizeKHR must: be declared using 2419 the code:Input {StorageClass} 2420 * [[VUID-{refpage}-LaunchSizeKHR-04271]] 2421 The variable decorated with code:LaunchSizeKHR must: be declared as a 2422 three-component vector of 32-bit integer values 2423**** 2424-- 2425endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2426 2427[[interfaces-builtin-variables-layer]] 2428[open,refpage='Layer',desc='Layer index for layered rendering',type='builtins'] 2429-- 2430:refpage: Layer 2431 2432code:Layer:: 2433 2434Decorating a variable with the code:Layer built-in decoration will make that 2435variable contain the select layer of a multi-layer framebuffer attachment. 2436+ 2437In a 2438ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 2439ifdef::VK_NV_mesh_shader[] 2440mesh, 2441endif::VK_NV_mesh_shader[] 2442vertex, tessellation evaluation, or 2443endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 2444geometry shader, any variable decorated with code:Layer can be written with 2445the framebuffer layer index to which the primitive produced by that shader 2446will be directed. 2447ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 2448+ 2449The last active 2450<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2451stage>> (in pipeline order) controls the code:Layer that is used. 2452Outputs in previous shader stages are not used, even if the last stage fails 2453to write the code:Layer. 2454endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 2455+ 2456If the last active 2457<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2458stage>> shader entry point's interface does not include a variable decorated 2459with code:Layer, then the first layer is used. 2460If a <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2461stage>> shader entry point's interface includes a variable decorated with 2462code:Layer, it must: write the same value to code:Layer for all output 2463vertices of a given primitive. 2464If the code:Layer value is less than 0 or greater than or equal to the 2465number of layers in the framebuffer, then primitives may: still be 2466rasterized, fragment shaders may: be executed, and the framebuffer values 2467for all layers are undefined:. 2468+ 2469ifdef::VK_NV_viewport_array2[] 2470If a variable with the code:Layer decoration is also decorated with 2471code:ViewportRelativeNV, then the code:ViewportIndex is added to the layer 2472that is used for rendering and that is made available in the fragment 2473shader. 2474If the shader writes to a variable decorated code:ViewportMaskNV, then the 2475layer selected has a different value for each viewport a primitive is 2476rendered to. 2477endif::VK_NV_viewport_array2[] 2478+ 2479In a fragment shader, a variable decorated with code:Layer contains the 2480layer index of the primitive that the fragment invocation belongs to. 2481 2482.Valid Usage 2483**** 2484 * [[VUID-{refpage}-Layer-04272]] 2485 The code:Layer decoration must: be used only within the code:MeshNV, 2486 code:Vertex, code:TessellationEvaluation, code:Geometry, or 2487 code:Fragment {ExecutionModel} 2488ifdef::VK_VERSION_1_2[] 2489 * [[VUID-{refpage}-Layer-04273]] 2490 If the <<features-shaderOutputLayer,shaderOutputLayer>> feature is not 2491 enabled then the code:Layer decoration must: be used only within the 2492 code:Geometry or code:Fragment {ExecutionModel} 2493endif::VK_VERSION_1_2[] 2494 * [[VUID-{refpage}-Layer-04274]] 2495 The variable decorated with code:Layer within the code:MeshNV, 2496 code:Vertex, code:TessellationEvaluation, or code:Geometry 2497 {ExecutionModel} must: be declared using the code:Output {StorageClass} 2498 * [[VUID-{refpage}-Layer-04275]] 2499 The variable decorated with code:Layer within the code:Fragment 2500 {ExecutionModel} must: be declared using the code:Input {StorageClass} 2501 * [[VUID-{refpage}-Layer-04276]] 2502 The variable decorated with code:Layer must: be declared as a scalar 2503 32-bit integer value 2504**** 2505-- 2506 2507ifdef::VK_NV_mesh_shader[] 2508[[interfaces-builtin-variables-layerpv]] 2509[open,refpage='LayerPerViewNV',desc='Layer index per view for layered rendering',type='builtins'] 2510-- 2511:refpage: LayerPerViewNV 2512 2513code:LayerPerViewNV:: 2514 2515Decorating a variable with the code:LayerPerViewNV built-in decoration will 2516make that variable contain the per-view layer information. 2517The per-view layer has the same semantics as code:Layer, for each view. 2518 2519.Valid Usage 2520**** 2521 * [[VUID-{refpage}-LayerPerViewNV-04277]] 2522 The code:LayerPerViewNV decoration must: be used only within the 2523 code:MeshNV {ExecutionModel} 2524 * [[VUID-{refpage}-LayerPerViewNV-04278]] 2525 The variable decorated with code:LayerPerViewNV must: be declared using 2526 the code:Output {StorageClass} 2527 * [[VUID-{refpage}-LayerPerViewNV-04279]] 2528 The variable decorated with code:LayerPerViewNV must: also be decorated 2529 with the code:PerViewNV decoration 2530 * [[VUID-{refpage}-LayerPerViewNV-04280]] 2531 The variable decorated with code:LayerPerViewNV must: be declared as an 2532 array of scalar 32-bit integer values 2533**** 2534-- 2535endif::VK_NV_mesh_shader[] 2536 2537[open,refpage='LocalInvocationId',desc='Local invocation ID',type='builtins'] 2538-- 2539:refpage: LocalInvocationId 2540 2541code:LocalInvocationId:: 2542 2543Decorating a variable with the code:LocalInvocationId built-in decoration 2544will make that variable contain the location of the current 2545ifdef::VK_NV_mesh_shader[] 2546task, mesh, or 2547endif::VK_NV_mesh_shader[] 2548compute shader invocation within the local workgroup. 2549Each component ranges from zero through to the size of the workgroup in that 2550dimension minus one. 2551 2552[NOTE] 2553.Note 2554==== 2555If the size of the workgroup in a particular dimension is one, then the 2556code:LocalInvocationId in that dimension will be zero. 2557If the workgroup is effectively two-dimensional, then 2558code:LocalInvocationId.z will be zero. 2559If the workgroup is effectively one-dimensional, then both 2560code:LocalInvocationId.y and code:LocalInvocationId.z will be zero. 2561==== 2562 2563.Valid Usage 2564**** 2565 * [[VUID-{refpage}-LocalInvocationId-04281]] 2566 The code:LocalInvocationId decoration must: be used only within the 2567 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 2568 * [[VUID-{refpage}-LocalInvocationId-04282]] 2569 The variable decorated with code:LocalInvocationId must: be declared 2570 using the code:Input {StorageClass} 2571 * [[VUID-{refpage}-LocalInvocationId-04283]] 2572 The variable decorated with code:LocalInvocationId must: be declared as 2573 a three-component vector of 32-bit integer values 2574**** 2575-- 2576 2577[open,refpage='LocalInvocationIndex',desc='Linear local invocation index',type='builtins'] 2578-- 2579:refpage: LocalInvocationIndex 2580 2581code:LocalInvocationIndex:: 2582 2583Decorating a variable with the code:LocalInvocationIndex built-in decoration 2584will make that variable contain a one-dimensional representation of 2585code:LocalInvocationId. 2586This is computed as: 2587+ 2588[source,c++] 2589---- 2590LocalInvocationIndex = 2591 LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y + 2592 LocalInvocationId.y * WorkgroupSize.x + 2593 LocalInvocationId.x; 2594---- 2595 2596.Valid Usage 2597**** 2598 * [[VUID-{refpage}-LocalInvocationIndex-04284]] 2599 The code:LocalInvocationIndex decoration must: be used only within the 2600 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 2601 * [[VUID-{refpage}-LocalInvocationIndex-04285]] 2602 The variable decorated with code:LocalInvocationIndex must: be declared 2603 using the code:Input {StorageClass} 2604 * [[VUID-{refpage}-LocalInvocationIndex-04286]] 2605 The variable decorated with code:LocalInvocationIndex must: be declared 2606 as a scalar 32-bit integer value 2607**** 2608-- 2609 2610ifdef::VK_NV_mesh_shader[] 2611[[interfaces-builtin-variables-meshviewcount]] 2612[open,refpage='MeshViewCountNV',desc='Number of views processed by a mesh or task shader',type='builtins'] 2613-- 2614:refpage: MeshViewCountNV 2615 2616code:MeshViewCountNV:: 2617 2618Decorating a variable with the code:MeshViewCountNV built-in decoration will 2619make that variable contain the number of views processed by the current mesh 2620or task shader invocations. 2621 2622.Valid Usage 2623**** 2624 * [[VUID-{refpage}-MeshViewCountNV-04287]] 2625 The code:MeshViewCountNV decoration must: be used only within the 2626 code:MeshNV or code:TaskNV {ExecutionModel} 2627 * [[VUID-{refpage}-MeshViewCountNV-04288]] 2628 The variable decorated with code:MeshViewCountNV must: be declared using 2629 the code:Input {StorageClass} 2630 * [[VUID-{refpage}-MeshViewCountNV-04289]] 2631 The variable decorated with code:MeshViewCountNV must: be declared as a 2632 scalar 32-bit integer value 2633**** 2634-- 2635 2636[[interfaces-builtin-variables-meshviewindices]] 2637[open,refpage='MeshViewIndicesNV',desc='Indices of views processed by a mesh or task shader',type='builtins'] 2638-- 2639:refpage: MeshViewIndicesNV 2640 2641code:MeshViewIndicesNV:: 2642 2643Decorating a variable with the code:MeshViewIndicesNV built-in decoration 2644will make that variable contain the mesh view indices. 2645The mesh view indices is an array of values where each element holds the 2646view number of one of the views being processed by the current mesh or task 2647shader invocations. 2648The values of array elements with indices greater than or equal to 2649code:MeshViewCountNV are undefined:. 2650If the value of code:MeshViewIndicesNV[i] is [eq]#j#, then any outputs 2651decorated with code:PerViewNV will take on the value of array element 2652[eq]#i# when processing primitives for view index [eq]#j#. 2653 2654.Valid Usage 2655**** 2656 * [[VUID-{refpage}-MeshViewIndicesNV-04290]] 2657 The code:MeshViewIndicesNV decoration must: be used only within the 2658 code:MeshNV or code:TaskNV {ExecutionModel} 2659 * [[VUID-{refpage}-MeshViewIndicesNV-04291]] 2660 The variable decorated with code:MeshViewIndicesNV must: be declared 2661 using the code:Input {StorageClass} 2662 * [[VUID-{refpage}-MeshViewIndicesNV-04292]] 2663 The variable decorated with code:MeshViewIndicesNV must: be declared as 2664 an array of scalar 32-bit integer values 2665**** 2666-- 2667endif::VK_NV_mesh_shader[] 2668 2669ifdef::VK_VERSION_1_1[] 2670[open,refpage='NumSubgroups',desc='Number of subgroups in a workgroup',type='builtins'] 2671-- 2672:refpage: NumSubgroups 2673 2674code:NumSubgroups:: 2675 2676Decorating a variable with the code:NumSubgroups built-in decoration will 2677make that variable contain the number of subgroups in the local workgroup. 2678 2679.Valid Usage 2680**** 2681 * [[VUID-{refpage}-NumSubgroups-04293]] 2682 The code:NumSubgroups decoration must: be used only within the 2683 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 2684 * [[VUID-{refpage}-NumSubgroups-04294]] 2685 The variable decorated with code:NumSubgroups must: be declared using 2686 the code:Input {StorageClass} 2687 * [[VUID-{refpage}-NumSubgroups-04295]] 2688 The variable decorated with code:NumSubgroups must: be declared as a 2689 scalar 32-bit integer value 2690**** 2691-- 2692endif::VK_VERSION_1_1[] 2693 2694[open,refpage='NumWorkgroups',desc='Number of workgroups in a dispatch',type='builtins'] 2695-- 2696:refpage: NumWorkgroups 2697 2698code:NumWorkgroups:: 2699 2700Decorating a variable with the code:NumWorkgroups built-in decoration will 2701make that variable contain the number of local workgroups that are part of 2702the dispatch that the invocation belongs to. 2703Each component is equal to the values of the workgroup count parameters 2704passed into the dispatching commands. 2705 2706.Valid Usage 2707**** 2708 * [[VUID-{refpage}-NumWorkgroups-04296]] 2709 The code:NumWorkgroups decoration must: be used only within the 2710 code:GLCompute {ExecutionModel} 2711 * [[VUID-{refpage}-NumWorkgroups-04297]] 2712 The variable decorated with code:NumWorkgroups must: be declared using 2713 the code:Input {StorageClass} 2714 * [[VUID-{refpage}-NumWorkgroups-04298]] 2715 The variable decorated with code:NumWorkgroups must: be declared as a 2716 three-component vector of 32-bit integer values 2717**** 2718-- 2719 2720ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2721[[interfaces-builtin-variables-objectraydirection]] 2722[open,refpage='ObjectRayDirectionKHR',desc='Ray direction in object space',type='builtins'] 2723-- 2724:refpage: ObjectRayDirectionKHR 2725 2726code:ObjectRayDirectionKHR:: 2727 2728A variable decorated with the code:ObjectRayDirectionKHR decoration will 2729specify the direction of the ray being processed, in object space. 2730 2731.Valid Usage 2732**** 2733 * [[VUID-{refpage}-ObjectRayDirectionKHR-04299]] 2734 The code:ObjectRayDirectionKHR decoration must: be used only within the 2735 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 2736 {ExecutionModel} 2737 * [[VUID-{refpage}-ObjectRayDirectionKHR-04300]] 2738 The variable decorated with code:ObjectRayDirectionKHR must: be declared 2739 using the code:Input {StorageClass} 2740 * [[VUID-{refpage}-ObjectRayDirectionKHR-04301]] 2741 The variable decorated with code:ObjectRayDirectionKHR must: be declared 2742 as a three-component vector of 32-bit floating-point values 2743**** 2744-- 2745 2746[[interfaces-builtin-variables-objectrayorigin]] 2747[open,refpage='ObjectRayOriginKHR',desc='Ray origin in object space',type='builtins'] 2748-- 2749:refpage: ObjectRayOriginKHR 2750 2751code:ObjectRayOriginKHR:: 2752 2753A variable decorated with the code:ObjectRayOriginKHR decoration will 2754specify the origin of the ray being processed, in object space. 2755 2756.Valid Usage 2757**** 2758 * [[VUID-{refpage}-ObjectRayOriginKHR-04302]] 2759 The code:ObjectRayOriginKHR decoration must: be used only within the 2760 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 2761 {ExecutionModel} 2762 * [[VUID-{refpage}-ObjectRayOriginKHR-04303]] 2763 The variable decorated with code:ObjectRayOriginKHR must: be declared 2764 using the code:Input {StorageClass} 2765 * [[VUID-{refpage}-ObjectRayOriginKHR-04304]] 2766 The variable decorated with code:ObjectRayOriginKHR must: be declared as 2767 a three-component vector of 32-bit floating-point values 2768**** 2769-- 2770 2771[[interfaces-builtin-variables-objecttoworld]] 2772[open,refpage='ObjectToWorldKHR',desc='Transformation matrix from object to world space',type='builtins'] 2773-- 2774:refpage: ObjectToWorldKHR 2775 2776code:ObjectToWorldKHR:: 2777 2778A variable decorated with the code:ObjectToWorldKHR decoration will contain 2779the current object-to-world transformation matrix, which is determined by 2780the instance of the current intersection. 2781 2782.Valid Usage 2783**** 2784 * [[VUID-{refpage}-ObjectToWorldKHR-04305]] 2785 The code:ObjectToWorldKHR decoration must: be used only within the 2786 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 2787 {ExecutionModel} 2788 * [[VUID-{refpage}-ObjectToWorldKHR-04306]] 2789 The variable decorated with code:ObjectToWorldKHR must: be declared 2790 using the code:Input {StorageClass} 2791 * [[VUID-{refpage}-ObjectToWorldKHR-04307]] 2792 The variable decorated with code:ObjectToWorldKHR must: be declared as a 2793 matrix with four columns of three-component vectors of 32-bit 2794 floating-point values 2795**** 2796-- 2797endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2798 2799[open,refpage='PatchVertices',desc='Number of vertices in an input patch',type='builtins'] 2800-- 2801:refpage: PatchVertices 2802 2803code:PatchVertices:: 2804 2805Decorating a variable with the code:PatchVertices built-in decoration will 2806make that variable contain the number of vertices in the input patch being 2807processed by the shader. 2808In a Tessellation Control Shader, this is the same as the 2809name:patchControlPoints member of 2810slink:VkPipelineTessellationStateCreateInfo. 2811In a Tessellation Evaluation Shader, code:PatchVertices is equal to the 2812tessellation control output patch size. 2813When the same shader is used in different pipelines where the patch sizes 2814are configured differently, the value of the code:PatchVertices variable 2815will also differ. 2816 2817.Valid Usage 2818**** 2819 * [[VUID-{refpage}-PatchVertices-04308]] 2820 The code:PatchVertices decoration must: be used only within the 2821 code:TessellationControl or code:TessellationEvaluation {ExecutionModel} 2822 * [[VUID-{refpage}-PatchVertices-04309]] 2823 The variable decorated with code:PatchVertices must: be declared using 2824 the code:Input {StorageClass} 2825 * [[VUID-{refpage}-PatchVertices-04310]] 2826 The variable decorated with code:PatchVertices must: be declared as a 2827 scalar 32-bit integer value 2828**** 2829-- 2830 2831[open,refpage='PointCoord',desc='Fragment coordinates in screen-space within a point primitive',type='builtins'] 2832-- 2833:refpage: PointCoord 2834 2835code:PointCoord:: 2836 2837Decorating a variable with the code:PointCoord built-in decoration will make 2838that variable contain the coordinate of the current fragment within the 2839point being rasterized, normalized to the size of the point with origin in 2840the upper left corner of the point, as described in 2841<<primsrast-points-basic,Basic Point Rasterization>>. 2842If the primitive the fragment shader invocation belongs to is not a point, 2843then the variable decorated with code:PointCoord contains an undefined: 2844value. 2845 2846[NOTE] 2847.Note 2848==== 2849Depending on how the point is rasterized, code:PointCoord may: never reach 2850[eq]#(0,0)# or [eq]#(1,1)#. 2851==== 2852 2853.Valid Usage 2854**** 2855 * [[VUID-{refpage}-PointCoord-04311]] 2856 The code:PointCoord decoration must: be used only within the 2857 code:Fragment {ExecutionModel} 2858 * [[VUID-{refpage}-PointCoord-04312]] 2859 The variable decorated with code:PointCoord must: be declared using the 2860 code:Input {StorageClass} 2861 * [[VUID-{refpage}-PointCoord-04313]] 2862 The variable decorated with code:PointCoord must: be declared as a 2863 two-component vector of 32-bit floating-point values 2864**** 2865-- 2866 2867[open,refpage='PointSize',desc='Size of a point primitive',type='builtins'] 2868-- 2869:refpage: PointSize 2870 2871code:PointSize:: 2872 2873Decorating a variable with the code:PointSize built-in decoration will make 2874that variable contain the size of point primitives. 2875The value written to the variable decorated with code:PointSize by the last 2876<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2877stage>> in the pipeline is used as the framebuffer-space size of points 2878produced by rasterization. 2879 2880[NOTE] 2881.Note 2882==== 2883When code:PointSize decorates a variable in the code:Input {StorageClass}, 2884it contains the data written to the output variable decorated with 2885code:PointSize from the previous shader stage. 2886==== 2887 2888.Valid Usage 2889**** 2890 * [[VUID-{refpage}-PointSize-04314]] 2891 The code:PointSize decoration must: be used only within the code:MeshNV, 2892 code:Vertex, code:TessellationControl, code:TessellationEvaluation, or 2893 code:Geometry {ExecutionModel} 2894 * [[VUID-{refpage}-PointSize-04315]] 2895 The variable decorated with code:PointSize within the code:MeshNV or 2896 code:Vertex {ExecutionModel} must: be declared using the code:Output 2897 {StorageClass} 2898 * [[VUID-{refpage}-PointSize-04316]] 2899 The variable decorated with code:PointSize within the 2900 code:TessellationControl, code:TessellationEvaluation, or code:Geometry 2901 {ExecutionModel} must: not be declared using a {StorageClass} other than 2902 code:Input or code:Output 2903 * [[VUID-{refpage}-PointSize-04317]] 2904 The variable decorated with code:PointSize must: be declared as a scalar 2905 32-bit floating-point value 2906**** 2907-- 2908 2909[open,refpage='Position',desc='Vertex position',type='builtins'] 2910-- 2911:refpage: Position 2912 2913code:Position:: 2914 2915Decorating a variable with the code:Position built-in decoration will make 2916that variable contain the position of the current vertex. 2917In the last <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization 2918shader stage>>, the value of the variable decorated with code:Position is 2919used in subsequent primitive assembly, clipping, and rasterization 2920operations. 2921 2922[NOTE] 2923.Note 2924==== 2925When code:Position decorates a variable in the code:Input {StorageClass}, it 2926contains the data written to the output variable decorated with 2927code:Position from the previous shader stage. 2928==== 2929 2930.Valid Usage 2931**** 2932 * [[VUID-{refpage}-Position-04318]] 2933 The code:Position decoration must: be used only within the code:MeshNV, 2934 code:Vertex, code:TessellationControl, code:TessellationEvaluation, or 2935 code:Geometry {ExecutionModel} 2936 * [[VUID-{refpage}-Position-04319]] 2937 The variable decorated with code:Position within code:MeshNV or 2938 code:Vertex {ExecutionModel} must: be declared using the code:Output 2939 {StorageClass} 2940 * [[VUID-{refpage}-Position-04320]] 2941 The variable decorated with code:Position within 2942 code:TessellationControl, code:TessellationEvaluation, or code:Geometry 2943 {ExecutionModel} must: not be declared using a {StorageClass} other than 2944 code:Input or code:Output 2945 * [[VUID-{refpage}-Position-04321]] 2946 The variable decorated with code:Position must: be declared as a 2947 four-component vector of 32-bit floating-point values 2948**** 2949-- 2950 2951ifdef::VK_NVX_multiview_per_view_attributes[] 2952[[interfaces-builtin-variables-positionperview]] 2953[open,refpage='PositionPerViewNV',desc='Vertex position per view',type='builtins'] 2954-- 2955:refpage: PositionPerViewNV 2956 2957code:PositionPerViewNV:: 2958 2959Decorating a variable with the code:PositionPerViewNV built-in decoration 2960will make that variable contain the position of the current vertex, for each 2961view. 2962+ 2963Elements of the array correspond to views in a multiview subpass, and those 2964elements corresponding to views in the view mask of the subpass the shader 2965is compiled against will be used as the position value for those views. 2966For the final 2967<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2968stage>> in the pipeline, values written to an output variable decorated with 2969code:PositionPerViewNV are used in subsequent primitive assembly, clipping, 2970and rasterization operations, as with code:Position. 2971code:PositionPerViewNV output in an earlier 2972<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2973stage>> is available as an input in the subsequent 2974<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2975stage>>. 2976+ 2977If a shader is compiled against a subpass that has the 2978ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX bit set, then 2979the position values for each view must: not differ in any component other 2980than the X component. 2981If the values do differ, one will be chosen in an implementation-dependent 2982manner. 2983 2984.Valid Usage 2985**** 2986 * [[VUID-{refpage}-PositionPerViewNV-04322]] 2987 The code:PositionPerViewNV decoration must: be used only within the 2988 code:MeshNV, code:Vertex, code:TessellationControl, 2989 code:TessellationEvaluation, or code:Geometry {ExecutionModel} 2990 * [[VUID-{refpage}-PositionPerViewNV-04323]] 2991 The variable decorated with code:PositionPerViewNV within the 2992 code:Vertex, or code:MeshNV {ExecutionModel} must: be declared using the 2993 code:Output {StorageClass} 2994 * [[VUID-{refpage}-PositionPerViewNV-04324]] 2995 The variable decorated with code:PositionPerViewNV within the 2996 code:TessellationControl, code:TessellationEvaluation, or code:Geometry 2997 {ExecutionModel} must: not be declared using a {StorageClass} other than 2998 code:Input or code:Output 2999 * [[VUID-{refpage}-PositionPerViewNV-04325]] 3000 The variable decorated with code:PositionPerViewNV must: be declared as 3001 an array of four-component vector of 32-bit floating-point values with 3002 at least as many elements as the maximum view in the subpass's view mask 3003 plus one 3004 * [[VUID-{refpage}-PositionPerViewNV-04326]] 3005 The array variable decorated with code:PositionPerViewNV must: only be 3006 indexed by a constant or specialization constant 3007**** 3008-- 3009endif::VK_NVX_multiview_per_view_attributes[] 3010 3011ifdef::VK_NV_mesh_shader[] 3012[[interfaces-builtin-variables-primitivecount]] 3013[open,refpage='PrimitiveCountNV',desc='Number of primitives output by a mesh shader',type='builtins'] 3014-- 3015:refpage: PrimitiveCountNV 3016 3017code:PrimitiveCountNV:: 3018+ 3019Decorating a variable with the code:PrimitiveCountNV decoration will make 3020that variable contain the primitive count. 3021The primitive count specifies the number of primitives in the output mesh 3022produced by the mesh shader that will be processed by subsequent pipeline 3023stages. 3024 3025.Valid Usage 3026**** 3027 * [[VUID-{refpage}-PrimitiveCountNV-04327]] 3028 The code:PrimitiveCountNV decoration must: be used only within the 3029 code:MeshNV {ExecutionModel} 3030 * [[VUID-{refpage}-PrimitiveCountNV-04328]] 3031 The variable decorated with code:PrimitiveCountNV must: be declared 3032 using the code:Output {StorageClass} 3033 * [[VUID-{refpage}-PrimitiveCountNV-04329]] 3034 The variable decorated with code:PrimitiveCountNV must: be declared as a 3035 scalar 32-bit integer value 3036**** 3037-- 3038endif::VK_NV_mesh_shader[] 3039 3040[open,refpage='PrimitiveId',desc='Primitive ID',type='builtins'] 3041-- 3042:refpage: PrimitiveId 3043 3044code:PrimitiveId:: 3045 3046Decorating a variable with the code:PrimitiveId built-in decoration will 3047make that variable contain the index of the current primitive. 3048+ 3049The index of the first primitive generated by a drawing command is zero, and 3050the index is incremented after every individual point, line, or triangle 3051primitive is processed. 3052+ 3053For triangles drawn as points or line segments (see <<primsrast-polygonmode, 3054Polygon Mode>>), the primitive index is incremented only once, even if 3055multiple points or lines are eventually drawn. 3056+ 3057Variables decorated with code:PrimitiveId are reset to zero between each 3058instance drawn. 3059+ 3060Restarting a primitive topology using primitive restart has no effect on the 3061value of variables decorated with code:PrimitiveId. 3062+ 3063In tessellation control and tessellation evaluation shaders, it will contain 3064the index of the patch within the current set of rendering primitives that 3065corresponds to the shader invocation. 3066+ 3067In a geometry shader, it will contain the number of primitives presented as 3068input to the shader since the current set of rendering primitives was 3069started. 3070+ 3071In a fragment shader, it will contain the primitive index written by the 3072ifdef::VK_NV_mesh_shader[] 3073mesh shader if a mesh shader is present, or the primitive index written by 3074the 3075endif::VK_NV_mesh_shader[] 3076geometry shader if a geometry shader is present, or with the value that 3077would have been presented as input to the geometry shader had it been 3078present. 3079ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 3080+ 3081In an intersection, any-hit, or closest hit shader, it will contain the 3082index within the geometry of the triangle or bounding box being processed. 3083endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 3084 3085[NOTE] 3086.Note 3087==== 3088When the code:PrimitiveId decoration is applied to an output variable in the 3089ifdef::VK_NV_mesh_shader[] 3090mesh shader or 3091endif::VK_NV_mesh_shader[] 3092geometry shader, the resulting value is seen through the code:PrimitiveId 3093decorated input variable in the fragment shader. 3094 3095The fragment shader using code:PrimitiveId will need to declare either the 3096ifdef::VK_NV_mesh_shader[code:MeshShadingNV,] 3097code:Geometry or code:Tessellation capability to satisfy the requirement 3098SPIR-V has to use code:PrimitiveId. 3099==== 3100 3101.Valid Usage 3102**** 3103 * [[VUID-{refpage}-PrimitiveId-04330]] 3104 The code:PrimitiveId decoration must: be used only within the 3105 code:MeshNV, code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, 3106 code:TessellationControl, code:TessellationEvaluation, code:Geometry, or 3107 code:Fragment {ExecutionModel} 3108 * [[VUID-{refpage}-Fragment-04331]] 3109 If pipeline contains both the code:Fragment and code:Geometry 3110 {ExecutionModel} and a variable decorated with code:PrimitiveId is read 3111 from code:Fragment shader, then the code:Geometry shader must: write to 3112 the output variables decorated with code:PrimitiveId in all execution 3113 paths 3114 * [[VUID-{refpage}-Fragment-04332]] 3115 If pipeline contains both the code:Fragment and code:MeshNV 3116 {ExecutionModel} and a variable decorated with code:PrimitiveId is read 3117 from code:Fragment shader, then the code:MeshNV shader must: write to 3118 the output variables decorated with code:PrimitiveId in all execution 3119 paths 3120 * [[VUID-{refpage}-Fragment-04333]] 3121 If code:Fragment {ExecutionModel} contains a variable decorated with 3122 code:PrimitiveId, then either the code:MeshShadingNV, code:Geometry or 3123 code:Tessellation capability must: also be declared 3124 * [[VUID-{refpage}-PrimitiveId-04334]] 3125 The variable decorated with code:PrimitiveId within the 3126 code:TessellationControl, code:TessellationEvaluation, code:Fragment, 3127 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 3128 {ExecutionModel} must: be declared using the code:Input {StorageClass} 3129 * [[VUID-{refpage}-PrimitiveId-04335]] 3130 The variable decorated with code:PrimitiveId within the code:Geometry 3131 {ExecutionModel} must: be declared using the code:Input or code:Output 3132 {StorageClass} 3133 * [[VUID-{refpage}-PrimitiveId-04336]] 3134 The variable decorated with code:PrimitiveId within the code:MeshNV 3135 {ExecutionModel} must: be declared using the code:Output {StorageClass} 3136 * [[VUID-{refpage}-PrimitiveId-04337]] 3137 The variable decorated with code:PrimitiveId must: be declared as a 3138 scalar 32-bit integer value 3139**** 3140-- 3141 3142ifdef::VK_NV_mesh_shader[] 3143[[interfaces-builtin-variables-primitiveindices]] 3144[open,refpage='PrimitiveIndicesNV',desc='Indices of primitives in a mesh shader',type='builtins'] 3145-- 3146:refpage: PrimitiveIndicesNV 3147 3148code:PrimitiveIndicesNV:: 3149+ 3150Decorating a variable with the code:PrimitiveIndicesNV decoration will make 3151that variable contain the output array of vertex index values. 3152Depending on the output primitive type declared using the execution mode, 3153the indices are split into groups of one (code:OutputPoints), two 3154(code:OutputLinesNV), or three (code:OutputTriangles) indices and each group 3155generates a primitive. 3156 3157.Valid Usage 3158**** 3159 * [[VUID-{refpage}-PrimitiveIndicesNV-04338]] 3160 The code:PrimitiveIndicesNV decoration must: be used only within the 3161 code:MeshNV {ExecutionModel} 3162 * [[VUID-{refpage}-PrimitiveIndicesNV-04339]] 3163 The variable decorated with code:PrimitiveIndicesNV must: be declared 3164 using the code:Output {StorageClass} 3165 * [[VUID-{refpage}-PrimitiveIndicesNV-04340]] 3166 The variable decorated with code:PrimitiveIndicesNV must: be declared as 3167 an array of scalar 32-bit integer values 3168 * [[VUID-{refpage}-PrimitiveIndicesNV-04341]] 3169 All index values of the array decorated with code:PrimitiveIndicesNV 3170 must: be in the range [eq]#[0, N-1]#, where [eq]#N# is the value 3171 specified by the code:OutputVertices {ExecutionMode} 3172 * [[VUID-{refpage}-OutputPoints-04342]] 3173 If the {ExecutionMode} is code:OutputPoints, then the array decorated 3174 with code:PrimitiveIndicesNV must be the size of the value specified by 3175 code:OutputPrimitivesNV 3176 * [[VUID-{refpage}-OutputLinesNV-04343]] 3177 If the {ExecutionMode} is code:OutputLinesNV, then the array decorated 3178 with code:PrimitiveIndicesNV must be the size of two times the value 3179 specified by code:OutputPrimitivesNV 3180 * [[VUID-{refpage}-OutputTrianglesNV-04344]] 3181 If the {ExecutionMode} is code:OutputTrianglesNV, then the array 3182 decorated with code:PrimitiveIndicesNV must be the size of three times 3183 the value specified by code:OutputPrimitivesNV 3184**** 3185-- 3186endif::VK_NV_mesh_shader[] 3187 3188ifdef::VK_KHR_fragment_shading_rate[] 3189[[interfaces-builtin-variables-primitiveshadingrate]] 3190[open,refpage='PrimitiveShadingRateKHR',desc='Primitive contribution to fragment shading rate',type='builtins'] 3191-- 3192:refpage: PrimitiveShadingRateKHR 3193 3194code:PrimitiveShadingRateKHR:: 3195 3196Decorating a variable with the code:PrimitiveShadingRateKHR built-in 3197decoration will make that variable contain the 3198<<primsrast-fragment-shading-rate-primitive, primitive fragment shading 3199rate>>. 3200+ 3201The value written to the variable decorated with 3202code:PrimitiveShadingRateKHR by the last 3203<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 3204stage>> in the pipeline is used as the 3205<<primsrast-fragment-shading-rate-primitive, primitive fragment shading 3206rate>>. 3207Outputs in previous shader stages are ignored. 3208+ 3209If the last active 3210<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 3211stage>> shader entry point's interface does not include a variable decorated 3212with code:PrimitiveShadingRateKHR, then it is as if the shader specified a 3213fragment shading rate value of 0, indicating a horizontal and vertical rate 3214of 1 pixel. 3215+ 3216If a shader has code:PrimitiveShadingRateKHR in the output interface and 3217there is an execution path through the shader that does not write to it, its 3218value is undefined: for executions of the shader that take that path. 3219 3220.Valid Usage 3221**** 3222 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04484]] 3223 The code:PrimitiveShadingRateKHR decoration must: be used only within 3224 the code:MeshNV, code:Vertex, or code:Geometry {ExecutionModel} 3225 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04485]] 3226 The variable decorated with code:PrimitiveShadingRateKHR must: be 3227 declared using the code:Output {StorageClass} 3228 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04486]] 3229 The variable decorated with code:PrimitiveShadingRateKHR must: be 3230 declared as a scalar 32-bit integer value 3231 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04487]] 3232 The value written to code:PrimitiveShadingRateKHR must: include no more 3233 than one of code:Vertical2Pixels and code:Vertical4Pixels 3234 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04488]] 3235 The value written to code:PrimitiveShadingRateKHR must: include no more 3236 than one of code:Horizontal2Pixels and code:Horizontal4Pixels 3237 * [[VUID-{refpage}-PrimitiveShadingRateKHR-04489]] 3238 The value written to code:PrimitiveShadingRateKHR must: not have any 3239 bits set other than those defined by *Fragment Shading Rate Flags* 3240 enumerants in the SPIR-V specification 3241**** 3242-- 3243endif::VK_KHR_fragment_shading_rate[] 3244 3245ifdef::VK_KHR_ray_tracing_pipeline[] 3246[[interfaces-builtin-variables-raygeometryindex]] 3247[open,refpage='RayGeometryIndexKHR',desc='Geometry index in a ray shader',type='builtins'] 3248-- 3249:refpage: RayGeometryIndexKHR 3250 3251code:RayGeometryIndexKHR:: 3252 3253A variable decorated with the code:RayGeometryIndexKHR decoration will 3254contain the <<acceleration-structure-geometry-index, geometry index>> for 3255the acceleration structure geometry currently being shaded. 3256 3257.Valid Usage 3258**** 3259 * [[VUID-{refpage}-RayGeometryIndexKHR-04345]] 3260 The code:RayGeometryIndexKHR decoration must: be used only within the 3261 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 3262 {ExecutionModel} 3263 * [[VUID-{refpage}-RayGeometryIndexKHR-04346]] 3264 The variable decorated with code:RayGeometryIndexKHR must: be declared 3265 using the code:Input {StorageClass} 3266 * [[VUID-{refpage}-RayGeometryIndexKHR-04347]] 3267 The variable decorated with code:RayGeometryIndexKHR must: be declared 3268 as a scalar 32-bit integer value 3269**** 3270-- 3271endif::VK_KHR_ray_tracing_pipeline[] 3272 3273ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 3274[[interfaces-builtin-variables-raytmax]] 3275[open,refpage='RayTmaxKHR',desc='Maximum T value of a ray',type='builtins'] 3276-- 3277:refpage: RayTmaxKHR 3278 3279code:RayTmaxKHR:: 3280 3281A variable decorated with the code:RayTmaxKHR decoration will contain the 3282parametric [eq]#t~max~# value of the ray being processed. 3283The value is independent of the space in which the ray origin and direction 3284exist. 3285The value is initialized to the parameter passed into code:OpTraceRayKHR. 3286+ 3287The [eq]#t~max~# value changes throughout the lifetime of the ray that 3288produced the intersection. 3289In the closest hit shader, the value reflects the closest distance to the 3290intersected primitive. 3291In the any-hit shader, it reflects the distance to the primitive currently 3292being intersected. 3293In the intersection shader, it reflects the distance to the closest 3294primitive intersected so far or the initial value. 3295The value can change in the intersection shader after calling 3296code:OpReportIntersectionKHR if the corresponding any-hit shader does not 3297ignore the intersection. 3298In a miss shader, the value is identical to the parameter passed into 3299code:OpTraceRayKHR. 3300 3301.Valid Usage 3302**** 3303 * [[VUID-{refpage}-RayTmaxKHR-04348]] 3304 The code:RayTmaxKHR decoration must: be used only within the 3305 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 3306 code:MissKHR {ExecutionModel} 3307 * [[VUID-{refpage}-RayTmaxKHR-04349]] 3308 The variable decorated with code:RayTmaxKHR must: be declared using the 3309 code:Input {StorageClass} 3310 * [[VUID-{refpage}-RayTmaxKHR-04350]] 3311 The variable decorated with code:RayTmaxKHR must: be declared as a 3312 scalar 32-bit floating-point value 3313**** 3314-- 3315 3316[[interfaces-builtin-variables-raytmin]] 3317[open,refpage='RayTminKHR',desc='Minimum T value of a ray',type='builtins'] 3318-- 3319:refpage: RayTminKHR 3320 3321code:RayTminKHR:: 3322 3323A variable decorated with the code:RayTminKHR decoration will contain the 3324parametric [eq]#t~min~# value of the ray being processed. 3325The value is independent of the space in which the ray origin and direction 3326exist. 3327The value is given by the parameter passed into code:OpTraceRayKHR. 3328+ 3329The [eq]#t~min~# value remains constant for the duration of the ray query. 3330 3331.Valid Usage 3332**** 3333 * [[VUID-{refpage}-RayTminKHR-04351]] 3334 The code:RayTminKHR decoration must: be used only within the 3335 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 3336 code:MissKHR {ExecutionModel} 3337 * [[VUID-{refpage}-RayTminKHR-04352]] 3338 The variable decorated with code:RayTminKHR must: be declared using the 3339 code:Input {StorageClass} 3340 * [[VUID-{refpage}-RayTminKHR-04353]] 3341 The variable decorated with code:RayTminKHR must: be declared as a 3342 scalar 32-bit floating-point value 3343**** 3344-- 3345endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 3346 3347[open,refpage='SampleId',desc='Sample ID within a fragment',type='builtins'] 3348-- 3349:refpage: SampleId 3350 3351code:SampleId:: 3352 3353Decorating a variable with the code:SampleId built-in decoration will make 3354that variable contain the <<primsrast-multisampling-coverage-mask, coverage 3355index>> for the current fragment shader invocation. 3356code:SampleId ranges from zero to the number of samples in the framebuffer 3357minus one. 3358If a fragment shader entry point's interface includes an input variable 3359decorated with code:SampleId, <<primsrast-sampleshading,Sample Shading>> is 3360considered enabled with a pname:minSampleShading value of 1.0. 3361 3362.Valid Usage 3363**** 3364 * [[VUID-{refpage}-SampleId-04354]] 3365 The code:SampleId decoration must: be used only within the code:Fragment 3366 {ExecutionModel} 3367 * [[VUID-{refpage}-SampleId-04355]] 3368 The variable decorated with code:SampleId must: be declared using the 3369 code:Input {StorageClass} 3370 * [[VUID-{refpage}-SampleId-04356]] 3371 The variable decorated with code:SampleId must: be declared as a scalar 3372 32-bit integer value 3373**** 3374-- 3375 3376[[interfaces-builtin-variables-samplemask]] 3377[open,refpage='SampleMask',desc='Coverage mask for a fragment shader invocation',type='builtins'] 3378-- 3379:refpage: SampleMask 3380 3381code:SampleMask:: 3382 3383Decorating a variable with the code:SampleMask built-in decoration will make 3384any variable contain the <<fragops-shader-samplemask, sample mask>> for the 3385current fragment shader invocation. 3386+ 3387A variable in the code:Input storage class decorated with code:SampleMask 3388will contain a bitmask of the set of samples covered by the primitive 3389generating the fragment during rasterization. 3390It has a sample bit set if and only if the sample is considered covered for 3391this fragment shader invocation. 3392code:SampleMask[] is an array of integers. 3393Bits are mapped to samples in a manner where bit B of mask M 3394(`SampleMask[M]`) corresponds to sample [eq]#32 {times} M {plus} B#. 3395+ 3396A variable in the code:Output storage class decorated with code:SampleMask 3397is an array of integers forming a bit array in a manner similar to an input 3398variable decorated with code:SampleMask, but where each bit represents 3399coverage as computed by the shader. 3400This computed code:SampleMask is combined with the generated coverage mask 3401in the <<fragops-covg, multisample coverage>> operation. 3402+ 3403Variables decorated with code:SampleMask must: be either an unsized array, 3404or explicitly sized to be no larger than the implementation-dependent 3405maximum sample-mask (as an array of 32-bit elements), determined by the 3406maximum number of samples. 3407+ 3408If a fragment shader entry point's interface includes an output variable 3409decorated with code:SampleMask, the sample mask will be undefined: for any 3410array elements of any fragment shader invocations that fail to assign a 3411value. 3412If a fragment shader entry point's interface does not include an output 3413variable decorated with code:SampleMask, the sample mask has no effect on 3414the processing of a fragment. 3415 3416.Valid Usage 3417**** 3418 * [[VUID-{refpage}-SampleMask-04357]] 3419 The code:SampleMask decoration must: be used only within the 3420 code:Fragment {ExecutionModel} 3421 * [[VUID-{refpage}-SampleMask-04358]] 3422 The variable decorated with code:SampleMask must: be declared using the 3423 code:Input or code:Output {StorageClass} 3424 * [[VUID-{refpage}-SampleMask-04359]] 3425 The variable decorated with code:SampleMask must: be declared as an 3426 array of 32-bit integer values 3427**** 3428-- 3429 3430[open,refpage='SamplePosition',desc='Position of a shaded sample',type='builtins'] 3431-- 3432:refpage: SamplePosition 3433 3434code:SamplePosition:: 3435 3436Decorating a variable with the code:SamplePosition built-in decoration will 3437make that variable contain the sub-pixel position of the sample being 3438shaded. 3439The top left of the pixel is considered to be at coordinate [eq]#(0,0)# and 3440the bottom right of the pixel is considered to be at coordinate [eq]#(1,1)#. 3441ifdef::VK_EXT_fragment_density_map[] 3442// Markup here is weird. To get all these paragraphs indented properly for 3443// the keyword, the '+' connector must be *inside* ifdefs w/o blank lines. 3444+ 3445If the render pass has a fragment density map attachment, the variable will 3446instead contain the sub-fragment position of the sample being shaded. 3447The top left of the fragment is considered to be at coordinate [eq]#(0,0)# 3448and the bottom right of the fragment is considered to be at coordinate 3449[eq]#(1,1)# for any fragment area. 3450endif::VK_EXT_fragment_density_map[] 3451+ 3452If a fragment shader entry point's interface includes an input variable 3453decorated with code:SamplePosition, <<primsrast-sampleshading,Sample 3454Shading>> is considered enabled with a pname:minSampleShading value of 1.0. 3455ifdef::VK_EXT_sample_locations[] 3456+ 3457If the current pipeline uses <<primsrast-samplelocations, custom sample 3458locations>> the value of any variable decorated with the code:SamplePosition 3459built-in decoration is undefined:. 3460endif::VK_EXT_sample_locations[] 3461 3462.Valid Usage 3463**** 3464 * [[VUID-{refpage}-SamplePosition-04360]] 3465 The code:SamplePosition decoration must: be used only within the 3466 code:Fragment {ExecutionModel} 3467 * [[VUID-{refpage}-SamplePosition-04361]] 3468 The variable decorated with code:SamplePosition must: be declared using 3469 the code:Input {StorageClass} 3470 * [[VUID-{refpage}-SamplePosition-04362]] 3471 The variable decorated with code:SamplePosition must: be declared as a 3472 two-component vector of 32-bit floating-point values 3473**** 3474-- 3475 3476ifdef::VK_KHR_fragment_shading_rate[] 3477[open,refpage='ShadingRateKHR',desc='Shading rate of a fragment',type='builtins'] 3478-- 3479:refpage: ShadingRateKHR 3480 3481code:ShadingRateKHR:: 3482 3483Decorating a variable with the code:ShadingRateKHR built-in decoration will 3484make that variable contain the <<primsrast-fragment-shading-rate, fragment 3485shading rate>> for the current fragment invocation. 3486 3487.Valid Usage 3488**** 3489 * [[VUID-{refpage}-ShadingRateKHR-04490]] 3490 The code:ShadingRateKHR decoration must: be used only within the 3491 code:Fragment {ExecutionModel} 3492 * [[VUID-{refpage}-ShadingRateKHR-04491]] 3493 The variable decorated with code:ShadingRateKHR must: be declared using 3494 the code:Input {StorageClass} 3495 * [[VUID-{refpage}-ShadingRateKHR-04492]] 3496 The variable decorated with code:ShadingRateKHR must: be declared as a 3497 scalar 32-bit integer value 3498**** 3499-- 3500endif::VK_KHR_fragment_shading_rate[] 3501 3502ifdef::VK_NV_shader_sm_builtins[] 3503[[interfaces-builtin-variables-smcountnv]] 3504[open,refpage='SMCountNV',desc='Number of SMs on the device',type='builtins'] 3505-- 3506:refpage: SMCountNV 3507 3508code:SMCountNV:: 3509 3510Decorating a variable with the code:SMCountNV built-in decoration will make 3511that variable contain the number of SMs on the device. 3512 3513.Valid Usage 3514**** 3515 * [[VUID-{refpage}-SMCountNV-04363]] 3516 The variable decorated with code:SMCountNV must: be declared using the 3517 code:Input {StorageClass} 3518 * [[VUID-{refpage}-SMCountNV-04364]] 3519 The variable decorated with code:SMCountNV must: be declared as a scalar 3520 32-bit integer value 3521**** 3522-- 3523 3524[[interfaces-builtin-variables-smidnv]] 3525[open,refpage='SMIDNV',desc='SM ID on which a shader invocation is running',type='builtins'] 3526-- 3527:refpage: SMIDNV 3528 3529code:SMIDNV:: 3530 3531Decorating a variable with the code:SMIDNV built-in decoration will make 3532that variable contain the ID of the SM on which the current shader 3533invocation is running. 3534This variable is in the range [eq]#[0, code:SMCountNV-1]#. 3535 3536.Valid Usage 3537**** 3538 * [[VUID-{refpage}-SMIDNV-04365]] 3539 The variable decorated with code:SMIDNV must: be declared using the 3540 code:Input {StorageClass} 3541 * [[VUID-{refpage}-SMIDNV-04366]] 3542 The variable decorated with code:SMIDNV must: be declared as a scalar 3543 32-bit integer value 3544**** 3545-- 3546endif::VK_NV_shader_sm_builtins[] 3547 3548ifdef::VK_VERSION_1_1[] 3549[open,refpage='SubgroupId',desc='Subgroup ID ',type='builtins'] 3550-- 3551:refpage: SubgroupId 3552 3553code:SubgroupId:: 3554+ 3555Decorating a variable with the code:SubgroupId built-in decoration will make 3556that variable contain the index of the subgroup within the local workgroup. 3557This variable is in range [0, code:NumSubgroups-1]. 3558 3559.Valid Usage 3560**** 3561 * [[VUID-{refpage}-SubgroupId-04367]] 3562 The code:SubgroupId decoration must: be used only within the 3563 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 3564 * [[VUID-{refpage}-SubgroupId-04368]] 3565 The variable decorated with code:SubgroupId must: be declared using the 3566 code:Input {StorageClass} 3567 * [[VUID-{refpage}-SubgroupId-04369]] 3568 The variable decorated with code:SubgroupId must: be declared as a 3569 scalar 32-bit integer value 3570**** 3571-- 3572endif::VK_VERSION_1_1[] 3573 3574ifdef::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[] 3575[[interfaces-builtin-variables-sgeq]] 3576[open,refpage='SubgroupEqMask',desc='Mask of shader invocations in a subgroup with the same subgroup local invocation ID',type='builtins'] 3577-- 3578:refpage: SubgroupEqMask 3579 3580code:SubgroupEqMask:: 3581+ 3582Decorating a variable with the code:SubgroupEqMask builtin decoration will 3583make that variable contain the _subgroup mask_ of the current subgroup 3584invocation. 3585The bit corresponding to the code:SubgroupLocalInvocationId is set in the 3586variable decorated with code:SubgroupEqMask. 3587All other bits are set to zero. 3588+ 3589code:SubgroupEqMaskKHR is an alias of code:SubgroupEqMask. 3590 3591.Valid Usage 3592**** 3593 * [[VUID-{refpage}-SubgroupEqMask-04370]] 3594 The variable decorated with code:SubgroupEqMask must: be declared using 3595 the code:Input {StorageClass} 3596 * [[VUID-{refpage}-SubgroupEqMask-04371]] 3597 The variable decorated with code:SubgroupEqMask must: be declared as a 3598 four-component vector of 32-bit integer values 3599**** 3600-- 3601 3602[[interfaces-builtin-variables-sgge]] 3603[open,refpage='SubgroupGeMask',desc='Mask of shader invocations in a subgroup with the same or higher subgroup local invocation ID',type='builtins'] 3604-- 3605:refpage: SubgroupGeMask 3606 3607code:SubgroupGeMask:: 3608+ 3609Decorating a variable with the code:SubgroupGeMask builtin decoration will 3610make that variable contain the _subgroup mask_ of the current subgroup 3611invocation. 3612The bits corresponding to the invocations greater than or equal to 3613code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the 3614variable decorated with code:SubgroupGeMask. 3615All other bits are set to zero. 3616+ 3617code:SubgroupGeMaskKHR is an alias of code:SubgroupGeMask. 3618 3619.Valid Usage 3620**** 3621 * [[VUID-{refpage}-SubgroupGeMask-04372]] 3622 The variable decorated with code:SubgroupGeMask must: be declared using 3623 the code:Input {StorageClass} 3624 * [[VUID-{refpage}-SubgroupGeMask-04373]] 3625 The variable decorated with code:SubgroupGeMask must: be declared as a 3626 four-component vector of 32-bit integer values 3627**** 3628-- 3629 3630[[interfaces-builtin-variables-sggt]] 3631[open,refpage='SubgroupGtMask',desc='Mask of shader invocations in a subgroup with a higher subgroup local invocation ID',type='builtins'] 3632-- 3633:refpage: SubgroupGtMask 3634 3635code:SubgroupGtMask:: 3636+ 3637Decorating a variable with the code:SubgroupGtMask builtin decoration will 3638make that variable contain the _subgroup mask_ of the current subgroup 3639invocation. 3640The bits corresponding to the invocations greater than 3641code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the 3642variable decorated with code:SubgroupGtMask. 3643All other bits are set to zero. 3644+ 3645code:SubgroupGtMaskKHR is an alias of code:SubgroupGtMask. 3646 3647.Valid Usage 3648**** 3649 * [[VUID-{refpage}-SubgroupGtMask-04374]] 3650 The variable decorated with code:SubgroupGtMask must: be declared using 3651 the code:Input {StorageClass} 3652 * [[VUID-{refpage}-SubgroupGtMask-04375]] 3653 The variable decorated with code:SubgroupGtMask must: be declared as a 3654 four-component vector of 32-bit integer values 3655**** 3656-- 3657 3658[[interfaces-builtin-variables-sgle]] 3659[open,refpage='SubgroupLeMask',desc='Mask of shader invocations in a subgroup with the same or lower subgroup local invocation ID',type='builtins'] 3660-- 3661:refpage: SubgroupLeMask 3662 3663code:SubgroupLeMask:: 3664+ 3665Decorating a variable with the code:SubgroupLeMask builtin decoration will 3666make that variable contain the _subgroup mask_ of the current subgroup 3667invocation. 3668The bits corresponding to the invocations less than or equal to 3669code:SubgroupLocalInvocationId are set in the variable decorated with 3670code:SubgroupLeMask. 3671All other bits are set to zero. 3672+ 3673code:SubgroupLeMaskKHR is an alias of code:SubgroupLeMask. 3674 3675.Valid Usage 3676**** 3677 * [[VUID-{refpage}-SubgroupLeMask-04376]] 3678 The variable decorated with code:SubgroupLeMask must: be declared using 3679 the code:Input {StorageClass} 3680 * [[VUID-{refpage}-SubgroupLeMask-04377]] 3681 The variable decorated with code:SubgroupLeMask must: be declared as a 3682 four-component vector of 32-bit integer values 3683**** 3684-- 3685 3686[[interfaces-builtin-variables-sglt]] 3687[open,refpage='SubgroupLtMask',desc='Mask of shader invocations in a subgroup with a lower subgroup local invocation ID',type='builtins'] 3688-- 3689:refpage: SubgroupLtMask 3690 3691code:SubgroupLtMask:: 3692+ 3693Decorating a variable with the code:SubgroupLtMask builtin decoration will 3694make that variable contain the _subgroup mask_ of the current subgroup 3695invocation. 3696The bits corresponding to the invocations less than 3697code:SubgroupLocalInvocationId are set in the variable decorated with 3698code:SubgroupLtMask. 3699All other bits are set to zero. 3700+ 3701code:SubgroupLtMaskKHR is an alias of code:SubgroupLtMask. 3702 3703.Valid Usage 3704**** 3705 * [[VUID-{refpage}-SubgroupLtMask-04378]] 3706 The variable decorated with code:SubgroupLtMask must: be declared using 3707 the code:Input {StorageClass} 3708 * [[VUID-{refpage}-SubgroupLtMask-04379]] 3709 The variable decorated with code:SubgroupLtMask must: be declared as a 3710 four-component vector of 32-bit integer values 3711**** 3712-- 3713 3714[[interfaces-builtin-variables-sgli]] 3715[open,refpage='SubgroupLocalInvocationId',desc='ID of the invocation within a subgroup',type='builtins'] 3716-- 3717:refpage: SubgroupLocalInvocationId 3718 3719code:SubgroupLocalInvocationId:: 3720+ 3721Decorating a variable with the code:SubgroupLocalInvocationId builtin 3722decoration will make that variable contain the index of the invocation 3723within the subgroup. 3724This variable is in range [0,code:SubgroupSize-1]. 3725 3726[NOTE] 3727.Note 3728==== 3729There is no direct relationship between code:SubgroupLocalInvocationId and 3730code:LocalInvocationId or code:LocalInvocationIndex. 3731ifdef::VK_EXT_subgroup_size_control[] 3732If the pipeline was created with 3733ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, 3734applications can compute their own local invocation index to serve the same 3735purpose: 3736 3737[eq]#index = code:SubgroupLocalInvocationId + code:SubgroupId * 3738code:SubgroupSize# 3739 3740If full subgroups are not enabled, some subgroups may be dispatched with 3741inactive invocations that do not correspond to a local workgroup invocation, 3742making the value of [eq]#index# unreliable. 3743endif::VK_EXT_subgroup_size_control[] 3744==== 3745 3746.Valid Usage 3747**** 3748 * [[VUID-{refpage}-SubgroupLocalInvocationId-04380]] 3749 The variable decorated with code:SubgroupLocalInvocationId must: be 3750 declared using the code:Input {StorageClass} 3751 * [[VUID-{refpage}-SubgroupLocalInvocationId-04381]] 3752 The variable decorated with code:SubgroupLocalInvocationId must: be 3753 declared as a scalar 32-bit integer value 3754**** 3755-- 3756 3757[[interfaces-builtin-variables-sgs]] 3758[open,refpage='SubgroupSize',desc='Size of a subgroup',type='builtins'] 3759-- 3760:refpage: SubgroupSize 3761 3762code:SubgroupSize:: 3763+ 3764Decorating a variable with the code:SubgroupSize builtin decoration will 3765make that variable contain the implementation-dependent 3766<<limits-subgroup-size,number of invocations in a subgroup>>. 3767This value must: be a power-of-two integer. 3768+ 3769ifdef::VK_EXT_subgroup_size_control[] 3770If the pipeline was created with the 3771ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 3772flag set, the code:SubgroupSize decorated variable will contain the subgroup 3773size for each subgroup that gets dispatched. 3774This value must: be between <<limits-min-subgroup-size,minSubgroupSize>> and 3775<<limits-max-subgroup-size,maxSubgroupSize>> and must: be uniform with 3776<<shaders-scope-subgroup, subgroup scope>>. 3777The value may: vary across a single draw call, and for fragment shaders may: 3778vary across a single primitive. 3779In compute dispatches, code:SubgroupSize must: be uniform with 3780<<shaders-scope-command, command scope>>. 3781+ 3782If the pipeline was created with a chained 3783slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure, the 3784code:SubgroupSize decorated variable will match 3785<<pipelines-required-subgroup-size, pname:requiredSubgroupSize>>. 3786+ 3787If the pipeline was not created with the 3788ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 3789flag set and no slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT 3790structure was chained, the 3791endif::VK_EXT_subgroup_size_control[] 3792ifndef::VK_EXT_subgroup_size_control[] 3793The 3794endif::VK_EXT_subgroup_size_control[] 3795variable decorated with code:SubgroupSize will match <<limits-subgroup-size, 3796pname:subgroupSize>>. 3797+ 3798The maximum number of invocations that an implementation can support per 3799subgroup is 128. 3800 3801.Valid Usage 3802**** 3803 * [[VUID-{refpage}-SubgroupSize-04382]] 3804 The variable decorated with code:SubgroupSize must: be declared using 3805 the code:Input {StorageClass} 3806 * [[VUID-{refpage}-SubgroupSize-04383]] 3807 The variable decorated with code:SubgroupSize must: be declared as a 3808 scalar 32-bit integer value 3809**** 3810-- 3811endif::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[] 3812 3813ifdef::VK_NV_mesh_shader[] 3814[[interfaces-builtin-variables-taskcount]] 3815[open,refpage='TaskCountNV',desc='Number of mesh shader workgroups that will be generated',type='builtins'] 3816-- 3817:refpage: TaskCountNV 3818 3819code:TaskCountNV:: 3820+ 3821Decorating a variable with the code:TaskCountNV decoration will make that 3822variable contain the task count. 3823The task count specifies the number of subsequent mesh shader workgroups 3824that get generated upon completion of the task shader. 3825 3826.Valid Usage 3827**** 3828 * [[VUID-{refpage}-TaskCountNV-04384]] 3829 The code:TaskCountNV decoration must: be used only within the 3830 code:TaskNV {ExecutionModel} 3831 * [[VUID-{refpage}-TaskCountNV-04385]] 3832 The variable decorated with code:TaskCountNV must: be declared using the 3833 code:Output {StorageClass} 3834 * [[VUID-{refpage}-TaskCountNV-04386]] 3835 The variable decorated with code:TaskCountNV must: be declared as a 3836 scalar 32-bit integer value 3837**** 3838-- 3839endif::VK_NV_mesh_shader[] 3840 3841[open,refpage='TessCoord',desc='Barycentric coordinate of a tessellated vertex within a patch',type='builtins'] 3842-- 3843:refpage: TessCoord 3844 3845code:TessCoord:: 3846 3847Decorating a variable with the code:TessCoord built-in decoration will make 3848that variable contain the three-dimensional [eq]#(u,v,w)# barycentric 3849coordinate of the tessellated vertex within the patch. 3850[eq]#u#, [eq]#v#, and [eq]#w# are in the range [eq]#[0,1]# and vary linearly 3851across the primitive being subdivided. 3852For the tessellation modes of code:Quads or code:IsoLines, the third 3853component is always zero. 3854 3855.Valid Usage 3856**** 3857 * [[VUID-{refpage}-TessCoord-04387]] 3858 The code:TessCoord decoration must: be used only within the 3859 code:TessellationEvaluation {ExecutionModel} 3860 * [[VUID-{refpage}-TessCoord-04388]] 3861 The variable decorated with code:TessCoord must: be declared using the 3862 code:Input {StorageClass} 3863 * [[VUID-{refpage}-TessCoord-04389]] 3864 The variable decorated with code:TessCoord must: be declared as a 3865 three-component vector of 32-bit floating-point values 3866**** 3867-- 3868 3869[open,refpage='TessLevelOuter',desc='Outer tessellation levels',type='builtins'] 3870-- 3871:refpage: TessLevelOuter 3872 3873code:TessLevelOuter:: 3874 3875Decorating a variable with the code:TessLevelOuter built-in decoration will 3876make that variable contain the outer tessellation levels for the current 3877patch. 3878+ 3879In tessellation control shaders, the variable decorated with 3880code:TessLevelOuter can: be written to, which controls the tessellation 3881factors for the resulting patch. 3882These values are used by the tessellator to control primitive tessellation 3883and can: be read by tessellation evaluation shaders. 3884+ 3885In tessellation evaluation shaders, the variable decorated with 3886code:TessLevelOuter can: read the values written by the tessellation control 3887shader. 3888 3889.Valid Usage 3890**** 3891 * [[VUID-{refpage}-TessLevelOuter-04390]] 3892 The code:TessLevelOuter decoration must: be used only within the 3893 code:TessellationControl or code:TessellationEvaluation {ExecutionModel} 3894 * [[VUID-{refpage}-TessLevelOuter-04391]] 3895 The variable decorated with code:TessLevelOuter within the 3896 code:TessellationControl {ExecutionModel} must: be declared using the 3897 code:Output {StorageClass} 3898 * [[VUID-{refpage}-TessLevelOuter-04392]] 3899 The variable decorated with code:TessLevelOuter within the 3900 code:TessellationEvaluation {ExecutionModel} must: be declared using the 3901 code:Input {StorageClass} 3902 * [[VUID-{refpage}-TessLevelOuter-04393]] 3903 The variable decorated with code:TessLevelOuter must: be declared as an 3904 array of size four, containing 32-bit floating-point values 3905**** 3906-- 3907 3908[open,refpage='TessLevelInner',desc='Inner tessellation levels',type='builtins'] 3909-- 3910:refpage: TessLevelInner 3911 3912code:TessLevelInner:: 3913 3914Decorating a variable with the code:TessLevelInner built-in decoration will 3915make that variable contain the inner tessellation levels for the current 3916patch. 3917+ 3918In tessellation control shaders, the variable decorated with 3919code:TessLevelInner can: be written to, which controls the tessellation 3920factors for the resulting patch. 3921These values are used by the tessellator to control primitive tessellation 3922and can: be read by tessellation evaluation shaders. 3923+ 3924In tessellation evaluation shaders, the variable decorated with 3925code:TessLevelInner can: read the values written by the tessellation control 3926shader. 3927 3928.Valid Usage 3929**** 3930 * [[VUID-{refpage}-TessLevelInner-04394]] 3931 The code:TessLevelInner decoration must: be used only within the 3932 code:TessellationControl or code:TessellationEvaluation {ExecutionModel} 3933 * [[VUID-{refpage}-TessLevelInner-04395]] 3934 The variable decorated with code:TessLevelInner within the 3935 code:TessellationControl {ExecutionModel} must: be declared using the 3936 code:Output {StorageClass} 3937 * [[VUID-{refpage}-TessLevelInner-04396]] 3938 The variable decorated with code:TessLevelInner within the 3939 code:TessellationEvaluation {ExecutionModel} must: be declared using the 3940 code:Input {StorageClass} 3941 * [[VUID-{refpage}-TessLevelInner-04397]] 3942 The variable decorated with code:TessLevelInner must: be declared as an 3943 array of size two, containing 32-bit floating-point values 3944**** 3945-- 3946 3947[open,refpage='VertexIndex',desc='Vertex index of a shader invocation',type='builtins'] 3948-- 3949:refpage: VertexIndex 3950 3951code:VertexIndex:: 3952 3953Decorating a variable with the code:VertexIndex built-in decoration will 3954make that variable contain the index of the vertex that is being processed 3955by the current vertex shader invocation. 3956For non-indexed draws, this variable begins at the pname:firstVertex 3957parameter to flink:vkCmdDraw or the pname:firstVertex member of a structure 3958consumed by flink:vkCmdDrawIndirect and increments by one for each vertex in 3959the draw. 3960For indexed draws, its value is the content of the index buffer for the 3961vertex plus the pname:vertexOffset parameter to flink:vkCmdDrawIndexed or 3962the pname:vertexOffset member of the structure consumed by 3963flink:vkCmdDrawIndexedIndirect. 3964 3965[NOTE] 3966.Note 3967==== 3968code:VertexIndex starts at the same starting value for each instance. 3969==== 3970 3971.Valid Usage 3972**** 3973 * [[VUID-{refpage}-VertexIndex-04398]] 3974 The code:VertexIndex decoration must: be used only within the 3975 code:Vertex {ExecutionModel} 3976 * [[VUID-{refpage}-VertexIndex-04399]] 3977 The variable decorated with code:VertexIndex must: be declared using the 3978 code:Input {StorageClass} 3979 * [[VUID-{refpage}-VertexIndex-04400]] 3980 The variable decorated with code:VertexIndex must: be declared as a 3981 scalar 32-bit integer value 3982**** 3983-- 3984 3985ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 3986[[interfaces-builtin-variables-viewindex]] 3987[open,refpage='ViewIndex',desc='View index of a shader invocation',type='builtins'] 3988-- 3989:refpage: ViewIndex 3990 3991code:ViewIndex:: 3992 3993The code:ViewIndex decoration can: be applied to a shader input which will 3994be filled with the index of the view that is being processed by the current 3995shader invocation. 3996+ 3997If multiview is enabled in the render pass, this value will be one of the 3998bits set in the view mask of the subpass the pipeline is compiled against. 3999If multiview is not enabled in the render pass, this value will be zero. 4000 4001.Valid Usage 4002**** 4003 * [[VUID-{refpage}-ViewIndex-04401]] 4004 The code:ViewIndex decoration must: not be used within the 4005 code:GLCompute {ExecutionModel} 4006 * [[VUID-{refpage}-ViewIndex-04402]] 4007 The variable decorated with code:ViewIndex must: be declared using the 4008 code:Input {StorageClass} 4009 * [[VUID-{refpage}-ViewIndex-04403]] 4010 The variable decorated with code:ViewIndex must: be declared as a scalar 4011 32-bit integer value 4012**** 4013-- 4014endif::VK_VERSION_1_1,VK_KHR_multiview[] 4015 4016[[interfaces-builtin-variables-viewportindex]] 4017[open,refpage='ViewportIndex',desc='Viewport index used',type='builtins'] 4018-- 4019:refpage: ViewportIndex 4020 4021code:ViewportIndex:: 4022 4023Decorating a variable with the code:ViewportIndex built-in decoration will 4024make that variable contain the index of the viewport. 4025+ 4026In a 4027ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 4028ifdef::VK_NV_mesh_shader[] 4029mesh, 4030endif::VK_NV_mesh_shader[] 4031vertex, tessellation evaluation, or 4032endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 4033geometry shader, the variable decorated with code:ViewportIndex can be 4034written to with the viewport index to which the primitive produced by that 4035shader will be directed. 4036+ 4037The selected viewport index is used to select the 4038ifndef::VK_NV_scissor_exclusive[] 4039viewport transform and 4040endif::VK_NV_scissor_exclusive[] 4041ifdef::VK_NV_scissor_exclusive[] 4042viewport transform, scissor rectangle, and exclusive 4043endif::VK_NV_scissor_exclusive[] 4044scissor rectangle. 4045ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 4046+ 4047The last active 4048_<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4049stage>>_ (in pipeline order) controls the code:ViewportIndex that is used. 4050Outputs in previous shader stages are not used, even if the last stage fails 4051to write the code:ViewportIndex. 4052endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[] 4053+ 4054If the last active 4055<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4056stage>> shader entry point's interface does not include a variable decorated 4057with code:ViewportIndex, then the first viewport is used. 4058If a <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4059stage>> shader entry point's interface includes a variable decorated with 4060code:ViewportIndex, it must: write the same value to code:ViewportIndex for 4061all output vertices of a given primitive. 4062+ 4063In a fragment shader, the variable decorated with code:ViewportIndex 4064contains the viewport index of the primitive that the fragment invocation 4065belongs to. 4066 4067.Valid Usage 4068**** 4069 * [[VUID-{refpage}-ViewportIndex-04404]] 4070 The code:ViewportIndex decoration must: be used only within the 4071 code:MeshNV, code:Vertex, code:TessellationEvaluation, code:Geometry, or 4072 code:Fragment {ExecutionModel} 4073ifdef::VK_VERSION_1_2[] 4074 * [[VUID-{refpage}-ViewportIndex-04405]] 4075 If the <<features-shaderOutputViewportIndex,shaderOutputViewportIndex>> 4076 feature is not enabled then the code:ViewportIndex decoration must: be 4077 used only within the code:Geometry or code:Fragment {ExecutionModel} 4078endif::VK_VERSION_1_2[] 4079 * [[VUID-{refpage}-ViewportIndex-04406]] 4080 The variable decorated with code:ViewportIndex within the code:MeshNV, 4081 code:Vertex, code:TessellationEvaluation, or code:Geometry 4082 {ExecutionModel} must: be declared using the code:Output {StorageClass} 4083 * [[VUID-{refpage}-ViewportIndex-04407]] 4084 The variable decorated with code:ViewportIndex within the code:Fragment 4085 {ExecutionModel} must: be declared using the code:Input {StorageClass} 4086 * [[VUID-{refpage}-ViewportIndex-04408]] 4087 The variable decorated with code:ViewportIndex must: be declared as a 4088 scalar 32-bit integer value 4089**** 4090-- 4091 4092ifdef::VK_NV_viewport_array2[] 4093[[interfaces-builtin-variables-viewportmask]] 4094[open,refpage='ViewportMaskNV',desc='Mask of the viewports used',type='builtins'] 4095-- 4096:refpage: ViewportMaskNV 4097 4098code:ViewportMaskNV:: 4099 4100Decorating a variable with the code:ViewportMaskNV built-in decoration will 4101make that variable contain the viewport mask. 4102+ 4103In a 4104ifdef::VK_NV_mesh_shader[] 4105mesh, 4106endif::VK_NV_mesh_shader[] 4107vertex, tessellation evaluation, or geometry shader, the variable decorated 4108with code:ViewportMaskNV can be written to with the mask of which viewports 4109the primitive produced by that shader will directed. 4110+ 4111The code:ViewportMaskNV variable must: be an array that has 4112[eq]#{lceil}(sname:VkPhysicalDeviceLimits::pname:maxViewports / 32){rceil}# 4113elements. 4114When a shader writes to this variable, bit B of element M controls whether a 4115primitive is emitted to viewport [eq]#32 {times} M {plus} B#. 4116The viewports indicated by the mask are used to select the 4117ifndef::VK_NV_scissor_exclusive[] 4118viewport transform and 4119endif::VK_NV_scissor_exclusive[] 4120ifdef::VK_NV_scissor_exclusive[] 4121viewport transform, scissor rectangle, and exclusive 4122endif::VK_NV_scissor_exclusive[] 4123scissor rectangle that a primitive will be transformed by. 4124+ 4125The last active 4126_<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4127stage>>_ (in pipeline order) controls the code:ViewportMaskNV that is used. 4128Outputs in previous shader stages are not used, even if the last stage fails 4129to write the code:ViewportMaskNV. 4130When code:ViewportMaskNV is written by the final 4131<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4132stage>>, any variable decorated with code:ViewportIndex in the fragment 4133shader will have the index of the viewport that was used in generating that 4134fragment. 4135+ 4136If a <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4137stage>> shader entry point's interface includes a variable decorated with 4138code:ViewportMaskNV, it must: write the same value to code:ViewportMaskNV 4139for all output vertices of a given primitive. 4140 4141.Valid Usage 4142**** 4143 * [[VUID-{refpage}-ViewportMaskNV-04409]] 4144 The code:ViewportMaskNV decoration must: be used only within the 4145 code:Vertex, code:MeshNV, code:TessellationEvaluation, or code:Geometry 4146 {ExecutionModel} 4147 * [[VUID-{refpage}-ViewportMaskNV-04410]] 4148 The variable decorated with code:ViewportMaskNV must: be declared using 4149 the code:Output {StorageClass} 4150 * [[VUID-{refpage}-ViewportMaskNV-04411]] 4151 The variable decorated with code:ViewportMaskNV must: be declared as an 4152 array of 32-bit integer values 4153**** 4154-- 4155endif::VK_NV_viewport_array2[] 4156 4157ifdef::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[] 4158[[interfaces-builtin-variables-viewportmaskperview]] 4159[open,refpage='ViewportMaskPerViewNV',desc='Mask of viewports broadcast to per view',type='builtins'] 4160-- 4161:refpage: ViewportMaskPerViewNV 4162 4163code:ViewportMaskPerViewNV:: 4164 4165Decorating a variable with the code:ViewportMaskPerViewNV built-in 4166decoration will make that variable contain the mask of viewports primitives 4167are broadcast to, for each view. 4168+ 4169The value written to an element of code:ViewportMaskPerViewNV in the last 4170<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4171stage>> is a bitmask indicating which viewports the primitive will be 4172directed to. 4173The primitive will be broadcast to the viewport corresponding to each 4174non-zero bit of the bitmask, and that viewport index is used to select the 4175ifndef::VK_NV_scissor_exclusive[] 4176viewport transform and 4177endif::VK_NV_scissor_exclusive[] 4178ifdef::VK_NV_scissor_exclusive[] 4179viewport transform, scissor rectangle, and exclusive 4180endif::VK_NV_scissor_exclusive[] 4181scissor rectangle, for each view. 4182The same values must: be written to all vertices in a given primitive, or 4183else the set of viewports used for that primitive is undefined:. 4184+ 4185Elements of the array correspond to views in a multiview subpass, and those 4186elements corresponding to views in the view mask of the subpass the shader 4187is compiled against will be used as the viewport mask value for those views. 4188code:ViewportMaskPerViewNV output in an earlier 4189<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4190stage>> is not available as an input in the subsequent 4191<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 4192stage>>. 4193+ 4194Although code:ViewportMaskNV is an array, code:ViewportMaskPerViewNV is not 4195a two-dimensional array. 4196Instead, code:ViewportMaskPerViewNV is limited to 32 viewports. 4197 4198.Valid Usage 4199**** 4200 * [[VUID-{refpage}-ViewportMaskPerViewNV-04412]] 4201 The code:ViewportMaskPerViewNV decoration must: be used only within the 4202 code:Vertex, code:MeshNV, code:TessellationControl, 4203 code:TessellationEvaluation, or code:Geometry {ExecutionModel} 4204 * [[VUID-{refpage}-ViewportMaskPerViewNV-04413]] 4205 The variable decorated with code:ViewportMaskPerViewNV must: be declared 4206 using the code:Output {StorageClass} 4207 * [[VUID-{refpage}-ViewportMaskPerViewNV-04414]] 4208 The variable decorated with code:ViewportMaskPerViewNV must: be declared 4209 as an array of 32-bit integer values 4210 * [[VUID-{refpage}-ViewportMaskPerViewNV-04415]] 4211 The array decorated with code:ViewportMaskPerViewNV must: be a size less 4212 than or equal to 32 4213 * [[VUID-{refpage}-ViewportMaskPerViewNV-04416]] 4214 The array decorated with code:ViewportMaskPerViewNV must: be a size 4215 greater than the maximum view in the subpass's view mask 4216 * [[VUID-{refpage}-ViewportMaskPerViewNV-04417]] 4217 The array variable decorated with code:ViewportMaskPerViewNV must: only 4218 be indexed by a constant or specialization constant 4219**** 4220-- 4221endif::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[] 4222 4223ifdef::VK_NV_shader_sm_builtins[] 4224[[interfaces-builtin-variables-warpspersmnv]] 4225[open,refpage='WarpsPerSMNV',desc='Number of warps per SM',type='builtins'] 4226-- 4227:refpage: WarpsPerSMNV 4228 4229code:WarpsPerSMNV:: 4230 4231Decorating a variable with the code:WarpsPerSMNV built-in decoration will 4232make that variable contain the maximum number of warps executing on a SM. 4233 4234.Valid Usage 4235**** 4236 * [[VUID-{refpage}-WarpsPerSMNV-04418]] 4237 The variable decorated with code:WarpsPerSMNV must: be declared using 4238 the code:Input {StorageClass} 4239 * [[VUID-{refpage}-WarpsPerSMNV-04419]] 4240 The variable decorated with code:WarpsPerSMNV must: be declared as a 4241 scalar 32-bit integer value 4242**** 4243-- 4244 4245[[interfaces-builtin-variables-warpidnv]] 4246[open,refpage='WarpIDNV',desc='Warp ID within an SM of a shader invocation',type='builtins'] 4247-- 4248:refpage: WarpIDNV 4249 4250code:WarpIDNV:: 4251 4252Decorating a variable with the code:WarpIDNV built-in decoration will make 4253that variable contain the ID of the warp on a SM on which the current shader 4254invocation is running. 4255This variable is in the range [eq]#[0, code:WarpsPerSMNV-1]#. 4256 4257.Valid Usage 4258**** 4259 * [[VUID-{refpage}-WarpIDNV-04420]] 4260 The variable decorated with code:WarpIDNV must: be declared using the 4261 code:Input {StorageClass} 4262 * [[VUID-{refpage}-WarpIDNV-04421]] 4263 The variable decorated with code:WarpIDNV must: be declared as a scalar 4264 32-bit integer value 4265**** 4266-- 4267endif::VK_NV_shader_sm_builtins[] 4268 4269[open,refpage='WorkgroupId',desc='Workgroup ID of a shader',type='builtins'] 4270-- 4271:refpage: WorkgroupId 4272 4273code:WorkgroupId:: 4274 4275Decorating a variable with the code:WorkgroupId built-in decoration will 4276make that variable contain the global workgroup that the current invocation 4277is a member of. 4278Each component ranges from a base value to a [eq]#base {plus} count# value, 4279based on the parameters passed into the dispatching commands. 4280 4281.Valid Usage 4282**** 4283 * [[VUID-{refpage}-WorkgroupId-04422]] 4284 The code:WorkgroupId decoration must: be used only within the 4285 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 4286 * [[VUID-{refpage}-WorkgroupId-04423]] 4287 The variable decorated with code:WorkgroupId must: be declared using the 4288 code:Input {StorageClass} 4289 * [[VUID-{refpage}-WorkgroupId-04424]] 4290 The variable decorated with code:WorkgroupId must: be declared as a 4291 three-component vector of 32-bit integer values 4292**** 4293-- 4294 4295[open,refpage='WorkgroupSize',desc='Size of a workgroup',type='builtins'] 4296-- 4297:refpage: WorkgroupSize 4298 4299code:WorkgroupSize:: 4300 4301Decorating an object with the code:WorkgroupSize built-in decoration will 4302make that object contain the dimensions of a local workgroup. 4303If an object is decorated with the code:WorkgroupSize decoration, this takes 4304precedence over any code:LocalSize 4305ifdef::VK_KHR_maintenance4[or code:LocalSizeId] 4306execution mode. 4307 4308.Valid Usage 4309**** 4310 * [[VUID-{refpage}-WorkgroupSize-04425]] 4311 The code:WorkgroupSize decoration must: be used only within the 4312 code:GLCompute, code:MeshNV, or code:TaskNV {ExecutionModel} 4313 * [[VUID-{refpage}-WorkgroupSize-04426]] 4314 The variable decorated with code:WorkgroupSize must: be a specialization 4315 constant or a constant 4316 * [[VUID-{refpage}-WorkgroupSize-04427]] 4317 The variable decorated with code:WorkgroupSize must: be declared as a 4318 three-component vector of 32-bit integer values 4319**** 4320-- 4321 4322ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4323[[interfaces-builtin-variables-worldraydirection]] 4324[open,refpage='WorldRayDirectionKHR',desc='Ray direction in world space',type='builtins'] 4325-- 4326:refpage: WorldRayDirectionKHR 4327 4328code:WorldRayDirectionKHR:: 4329 4330A variable decorated with the code:WorldRayDirectionKHR decoration will 4331specify the direction of the ray being processed, in world space. 4332The value is given by the parameter passed into code:OpTraceRayKHR. 4333 4334.Valid Usage 4335**** 4336 * [[VUID-{refpage}-WorldRayDirectionKHR-04428]] 4337 The code:WorldRayDirectionKHR decoration must: be used only within the 4338 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 4339 code:MissKHR {ExecutionModel} 4340 * [[VUID-{refpage}-WorldRayDirectionKHR-04429]] 4341 The variable decorated with code:WorldRayDirectionKHR must: be declared 4342 using the code:Input {StorageClass} 4343 * [[VUID-{refpage}-WorldRayDirectionKHR-04430]] 4344 The variable decorated with code:WorldRayDirectionKHR must: be declared 4345 as a three-component vector of 32-bit floating-point values 4346**** 4347-- 4348 4349[[interfaces-builtin-variables-worldrayorigin]] 4350[open,refpage='WorldRayOriginKHR',desc='Ray origin in world space',type='builtins'] 4351-- 4352:refpage: WorldRayOriginKHR 4353 4354code:WorldRayOriginKHR:: 4355 4356A variable decorated with the code:WorldRayOriginKHR decoration will specify 4357the origin of the ray being processed, in world space. 4358The value is given by the parameter passed into code:OpTraceRayKHR. 4359 4360.Valid Usage 4361**** 4362 * [[VUID-{refpage}-WorldRayOriginKHR-04431]] 4363 The code:WorldRayOriginKHR decoration must: be used only within the 4364 code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or 4365 code:MissKHR {ExecutionModel} 4366 * [[VUID-{refpage}-WorldRayOriginKHR-04432]] 4367 The variable decorated with code:WorldRayOriginKHR must: be declared 4368 using the code:Input {StorageClass} 4369 * [[VUID-{refpage}-WorldRayOriginKHR-04433]] 4370 The variable decorated with code:WorldRayOriginKHR must: be declared as 4371 a three-component vector of 32-bit floating-point values 4372**** 4373-- 4374 4375[[interfaces-builtin-variables-worldtoobject]] 4376[open,refpage='WorldToObjectKHR',desc='Transformation matrix from world to object space',type='builtins'] 4377-- 4378:refpage: WorldToObjectKHR 4379 4380code:WorldToObjectKHR:: 4381 4382A variable decorated with the code:WorldToObjectKHR decoration will contain 4383the current world-to-object transformation matrix, which is determined by 4384the instance of the current intersection. 4385 4386.Valid Usage 4387**** 4388 * [[VUID-{refpage}-WorldToObjectKHR-04434]] 4389 The code:WorldToObjectKHR decoration must: be used only within the 4390 code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR 4391 {ExecutionModel} 4392 * [[VUID-{refpage}-WorldToObjectKHR-04435]] 4393 The variable decorated with code:WorldToObjectKHR must: be declared 4394 using the code:Input {StorageClass} 4395 * [[VUID-{refpage}-WorldToObjectKHR-04436]] 4396 The variable decorated with code:WorldToObjectKHR must: be declared as a 4397 matrix with four columns of three-component vectors of 32-bit 4398 floating-point values 4399**** 4400-- 4401endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4402