Vulkan® 1.3.283 - A Specification

15. Shader Interfaces

When a pipeline is created, the set of shaders specified in the corresponding VkPipelineCreateInfo structure are implicitly linked at a number of different interfaces.

This chapter describes valid uses for a set of SPIR-V decorations. Any other use of one of these decorations is invalid, with the exception that, when using SPIR-V versions 1.4 and earlier: Block, BufferBlock, Offset, ArrayStride, and MatrixStride can also decorate types and type members used by variables in the Private and Function storage classes.

Note

In this chapter, there are references to SPIR-V terms such as the MeshNV execution model. These terms will appear even in a build of the specification which does not support any extensions. This is as intended, since these terms appear in the unified SPIR-V specification without such qualifiers.

15.1. Shader Input and Output Interfaces

When multiple stages are present in a pipeline, the outputs of one stage form an interface with the inputs of the next stage. When such an interface involves a shader, shader outputs are matched against the inputs of the next stage, and shader inputs are matched against the outputs of the previous stage.

All the variables forming the shader input and output interfaces are listed as operands to the OpEntryPoint instruction and are declared with the Input or Output storage classes, respectively, in the SPIR-V module. These generally form the interfaces between consecutive shader stages, regardless of any non-shader stages between the consecutive shader stages.

There are two classes of variables that can be matched between shader stages, built-in variables and user-defined variables. Each class has a different set of matching criteria.

Output variables of a shader stage have undefined values until the shader writes to them or uses the Initializer operand when declaring the variable.

15.1.1. Built-in Interface Block

Shader built-in variables meeting the following requirements define the built-in interface block. They must

be explicitly declared (there are no implicit built-ins),
be identified with a BuiltIn decoration,
form object types as described in the Built-in Variables section, and
be declared in a block whose top-level members are the built-ins.

There must be no more than one built-in interface block per shader per interface .

Built-ins must not have any Location or Component decorations.

15.1.2. User-defined Variable Interface

The non-built-in variables listed by OpEntryPoint with the Input or Output storage class form the user-defined variable interface. These must have numeric type or, recursively, composite types of such types. If an implementation supports storageInputOutput16, components can have a width of 16 bits. These variables must be identified with a Location decoration and can also be identified with a Component decoration.

15.1.3. Interface Matching

An output variable, block, or structure member in a given shader stage has an interface match with an input variable, block, or structure member in a subsequent shader stage if they both adhere to the following conditions:

They have equivalent decorations, other than:
- one is not decorated with Component and the other is declared with a Component of 0
- Interpolation decorations
- RelaxedPrecision if one is an input variable and the other an output variable
Their types match as follows:
- if the input is declared in a tessellation control or geometry shader as an OpTypeArray with an Element Type equivalent to the OpType* declaration of the output, and neither is a structure member; or
- if the maintenance4 feature is enabled, they are declared as OpTypeVector variables, and the output has a Component Count value higher than that of the input but the same Component Type; or
- if in any other case they are declared with an equivalent OpType* declaration.
If both are structures and every member has an interface match.

Note

The word “structure” above refers to both variables that have an OpTypeStruct type and interface blocks (which are also declared as OpTypeStruct).

All input variables and blocks must have an interface match in the preceding shader stage, except for built-in variables in fragment shaders. Shaders can declare and write to output variables that are not declared or read by the subsequent stage.

The value of an input variable is undefined if the preceding stage does not write to a matching output variable, as described above.

15.1.4. Location Assignment

This section describes Location assignments for user-defined variables and how many Location slots are consumed by a given user-variable type. As mentioned above, some inputs and outputs have an additional level of arrayness relative to other shader inputs and outputs. This outer array level is removed from the type before considering how many Location slots the type consumes.

The Location value specifies an interface slot comprised of a 32-bit four-component vector conveyed between stages. The Component specifies word components within these vector Location slots. Only types with widths of 16, 32 or 64 are supported in shader interfaces.

Inputs and outputs of the following types consume a single interface Location:

16-bit scalar and vector types, and
32-bit scalar and vector types, and
64-bit scalar and 2-component vector types.

64-bit three- and four-component vectors consume two consecutive Location slots.

If a declared input or output is an array of size n and each element takes m Location slots, it will be assigned m × n consecutive Location slots starting with the specified Location.

If the declared input or output is an n × m 16-, 32- or 64-bit matrix, it will be assigned multiple Location slots starting with the specified Location. The number of Location slots assigned for each matrix will be the same as for an n-element array of m-component vectors.

An OpVariable with a structure type that is not a block must be decorated with a Location.

When an OpVariable with a structure type (either block or non-block) is decorated with a Location, the members in the structure type must not be decorated with a Location. The OpVariable’s members are assigned consecutive Location slots in declaration order, starting from the first member, which is assigned the Location decoration from the OpVariable.

When a block-type OpVariable is declared without a Location decoration, each member in its structure type must be decorated with a Location. Types nested deeper than the top-level members must not have Location decorations.

The Location slots consumed by block and structure members are determined by applying the rules above in a depth-first traversal of the instantiated members as though the structure or block member were declared as an input or output variable of the same type.

Any two inputs listed as operands on the same OpEntryPoint must not be assigned the same Location slot and Component word, either explicitly or implicitly. Any two outputs listed as operands on the same OpEntryPoint must not be assigned the same Location slot and Component word, either explicitly or implicitly.

The number of input and output Location slots available for a shader input or output interface is limited, and dependent on the shader stage as described in Shader Input and Output Locations. All variables in both the built-in interface block and the user-defined variable interface count against these limits. Each effective Location must have a value less than the number of Location slots available for the given interface, as specified in the “Locations Available” column in Shader Input and Output Locations.

Table 10. Shader Input and Output Locations
Shader Interface	Locations Available
vertex input	`maxVertexInputAttributes`
vertex output	`maxVertexOutputComponents` / 4
tessellation control input	`maxTessellationControlPerVertexInputComponents` / 4
tessellation control output	`maxTessellationControlPerVertexOutputComponents` / 4
tessellation evaluation input	`maxTessellationEvaluationInputComponents` / 4
tessellation evaluation output	`maxTessellationEvaluationOutputComponents` / 4
geometry input	`maxGeometryInputComponents` / 4
geometry output	`maxGeometryOutputComponents` / 4
fragment input	`maxFragmentInputComponents` / 4
fragment output	`maxFragmentOutputAttachments`

15.1.5. Component Assignment

The Component decoration allows the Location to be more finely specified for scalars and vectors, down to the individual Component word within a Location slot that are consumed. The Component word within a Location are 0, 1, 2, and 3. A variable or block member starting at Component N will consume Component words N, N+1, N+2, … up through its size. For 16-, and 32-bit types, it is invalid if this sequence of Component words gets larger than 3. A scalar 64-bit type will consume two of these Component words in sequence, and a two-component 64-bit vector type will consume all four Component words available within a Location. A three- or four-component 64-bit vector type must not specify a non-zero Component decoration. A three-component 64-bit vector type will consume all four Component words of the first Location and Component 0 and 1 of the second Location. This leaves Component 2 and 3 available for other component-qualified declarations.

A scalar or two-component 64-bit data type must not specify a Component decoration of 1 or 3. A Component decoration must not be specified for any type that is not a scalar or vector.

A four-component 64-bit data type will consume all four Component words of the first Location and all four Component words of the second Location.

15.2. Vertex Input Interface

When the vertex stage is present in a pipeline, the vertex shader input variables form an interface with the vertex input attributes. The vertex shader input variables are matched by the Location and Component decorations to the vertex input attributes specified in the pVertexInputState member of the VkGraphicsPipelineCreateInfo structure.

The vertex shader input variables listed by OpEntryPoint with the Input storage class form the vertex input interface. These variables must be identified with a Location decoration and can also be identified with a Component decoration.

For the purposes of interface matching: variables declared without a Component decoration are considered to have a Component decoration of zero. The number of available vertex input Location slots is given by the maxVertexInputAttributes member of the VkPhysicalDeviceLimits structure.

See Attribute Location and Component Assignment for details.

All vertex shader inputs declared as above must have a corresponding attribute and binding in the pipeline.

15.3. Fragment Output Interface

When the fragment stage is present in a pipeline, the fragment shader outputs form an interface with the output attachments defined by a render pass instance. The fragment shader output variables are matched by the Location and Component decorations to specified color attachments.

The fragment shader output variables listed by OpEntryPoint with the Output storage class form the fragment output interface. These variables must be identified with a Location decoration. They can also be identified with a Component decoration and/or an Index decoration. For the purposes of interface matching: variables declared without a Component decoration are considered to have a Component decoration of zero, and variables declared without an Index decoration are considered to have an Index decoration of zero.

A fragment shader output variable identified with a Location decoration of i is associated with the color attachment indicated by VkRenderingInfo::pColorAttachments[i]. When using render pass objects, it is associated with the color attachment indicated by VkSubpassDescription::pColorAttachments[i]. Values are written to those attachments after passing through the blending unit as described in Blending, if enabled. Locations are consumed as described in Location Assignment. The number of available fragment output Location slots is given by the maxFragmentOutputAttachments member of the VkPhysicalDeviceLimits structure.

When an active fragment shader invocation finishes, the values of all fragment shader outputs are copied out and used as blend inputs or color attachments writes. If the invocation does not set a value for them, the input values to those blending or color attachment writes are undefined.

Components of the output variables are assigned as described in Component Assignment. Output Component words identified as 0, 1, 2, and 3 will be directed to the R, G, B, and A inputs to the blending unit, respectively, or to the output attachment if blending is disabled. If two variables are placed within the same Location, they must have the same underlying type (floating-point or integer). Component words which do not correspond to any fragment shader output will also result in undefined values for blending or color attachment writes.

Fragment outputs identified with an Index of zero are directed to the first input of the blending unit associated with the corresponding Location. Outputs identified with an Index of one are directed to the second input of the corresponding blending unit.

There must be no output variable which has the same Location, Component, and Index as any other, either explicitly declared or implied.

Output values written by a fragment shader must be declared with either OpTypeFloat or OpTypeInt, and a Width of 32. If storageInputOutput16 is supported, output values written by a fragment shader can be also declared with either OpTypeFloat or OpTypeInt and a Width of 16. Composites of these types are also permitted. If the color attachment has a signed or unsigned normalized fixed-point format, color values are assumed to be floating-point and are converted to fixed-point as described in Conversion From Floating-Point to Normalized Fixed-Point; If the color attachment has an integer format, color values are assumed to be integers and converted to the bit-depth of the target. Any value that cannot be represented in the attachment’s format is undefined. For any other attachment format no conversion is performed. If the type of the values written by the fragment shader do not match the format of the corresponding color attachment, the resulting values are undefined for those components.

15.4. Fragment Input Attachment Interface

When a fragment stage is present in a pipeline, the fragment shader subpass inputs form an interface with the input attachments of the current subpass. The fragment shader subpass input variables are matched by InputAttachmentIndex decorations to the input attachments specified in the pInputAttachments array of the VkSubpassDescription structure describing the subpass that the fragment shader is executed in.

The fragment shader subpass input variables with the UniformConstant storage class and a decoration of InputAttachmentIndex that are statically used by OpEntryPoint form the fragment input attachment interface. These variables must be declared with a type of OpTypeImage, a Dim operand of SubpassData, an Arrayed operand of 0, and a Sampled operand of 2. The MS operand of the OpTypeImage must be 0 if the samples field of the corresponding VkAttachmentDescription is VK_SAMPLE_COUNT_1_BIT and 1 otherwise.

A subpass input variable identified with an InputAttachmentIndex decoration of i reads from the input attachment indicated by pInputAttachments[i] member of VkSubpassDescription. If the subpass input variable is declared as an array of size N, it consumes N consecutive input attachments, starting with the index specified. There must not be more than one input variable with the same InputAttachmentIndex whether explicitly declared or implied by an array declaration per image aspect. A multi-aspect image (e.g. a depth/stencil format) can use the same input variable. The number of available input attachment indices is given by the maxPerStageDescriptorInputAttachments member of the VkPhysicalDeviceLimits structure.

Variables identified with the InputAttachmentIndex must only be used by a fragment stage. The numeric format of the subpass input must match the format of the corresponding input attachment, or the values of subpass loads from these variables are undefined. If the framebuffer attachment contains both depth and stencil aspects, the numeric format of the subpass input determines if depth or stencil aspect is accessed by the shader.

See Input Attachment for more details.

15.4.1. Fragment Input Attachment Compatibility

An input attachment that is statically accessed by a fragment shader must be backed by a descriptor that is equivalent to the VkImageView in the VkFramebuffer, except for subresourceRange.aspectMask. The aspectMask must be equal to the aspect accessed by the shader.

15.5. Shader Resource Interface

When a shader stage accesses buffer or image resources, as described in the Resource Descriptors section, the shader resource variables must be matched with the pipeline layout that is provided at pipeline creation time.

The set of shader variables that form the shader resource interface for a stage are the variables statically used by that stage’s OpEntryPoint with a storage class of Uniform, UniformConstant, StorageBuffer, or PushConstant. For the fragment shader, this includes the fragment input attachment interface.

The shader resource interface consists of two sub-interfaces: the push constant interface and the descriptor set interface.

15.5.1. Push Constant Interface

The shader variables defined with a storage class of PushConstant that are statically used by the shader entry points for the pipeline define the push constant interface. They must be:

typed as OpTypeStruct,
identified with a Block decoration, and
laid out explicitly using the Offset, ArrayStride, and MatrixStride decorations as specified in Offset and Stride Assignment.

There must be no more than one push constant block statically used per shader entry point.

Each statically used member of a push constant block must be placed at an Offset such that the entire member is entirely contained within the VkPushConstantRange for each OpEntryPoint that uses it, and the stageFlags for that range must specify the appropriate VkShaderStageFlagBits for that stage. The Offset decoration for any member of a push constant block must not cause the space required for that member to extend outside the range [0, maxPushConstantsSize).

Any member of a push constant block that is declared as an array must only be accessed with dynamically uniform indices.

15.5.2. Descriptor Set Interface

The descriptor set interface is comprised of the shader variables with the storage class of StorageBuffer, Uniform or UniformConstant (including the variables in the fragment input attachment interface) that are statically used by the shader entry points for the pipeline.

These variables must have DescriptorSet and Binding decorations specified, which are assigned and matched with the VkDescriptorSetLayout objects in the pipeline layout as described in DescriptorSet and Binding Assignment.

The Image Format of an OpTypeImage declaration must not be Unknown, for variables which are used for OpImageRead, OpImageSparseRead, or OpImageWrite operations, except under the following conditions:

For OpImageWrite, if the image format is listed in the storage without format list and if the shaderStorageImageWriteWithoutFormat feature is enabled and the shader module declares the StorageImageWriteWithoutFormat capability.
For OpImageWrite, if the image format supports VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT and the shader module declares the StorageImageWriteWithoutFormat capability.
For OpImageRead or OpImageSparseRead, if the image format is listed in the storage without format list and if the shaderStorageImageReadWithoutFormat feature is enabled and the shader module declares the StorageImageReadWithoutFormat capability.
For OpImageRead or OpImageSparseRead, if the image format supports VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT and the shader module declares the StorageImageReadWithoutFormat capability.
For OpImageRead, if Dim is SubpassData (indicating a read from an input attachment).

The Image Format of an OpTypeImage declaration must not be Unknown, for variables which are used for OpAtomic* operations.

Variables identified with the Uniform storage class are used to access transparent buffer backed resources. Such variables must be:

typed as OpTypeStruct, or an array of this type,
identified with a Block or BufferBlock decoration, and
laid out explicitly using the Offset, ArrayStride, and MatrixStride decorations as specified in Offset and Stride Assignment.

Variables identified with the StorageBuffer storage class are used to access transparent buffer backed resources. Such variables must be:

typed as OpTypeStruct, or an array of this type,
identified with a Block decoration, and
laid out explicitly using the Offset, ArrayStride, and MatrixStride decorations as specified in Offset and Stride Assignment.

The Offset decoration for any member of a Block-decorated variable in the Uniform storage class must not cause the space required for that variable to extend outside the range [0, maxUniformBufferRange). The Offset decoration for any member of a Block-decorated variable in the StorageBuffer storage class must not cause the space required for that variable to extend outside the range [0, maxStorageBufferRange).

Variables identified with the Uniform storage class can also be used to access transparent descriptor set backed resources when the variable is assigned to a descriptor set layout binding with a descriptorType of VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK. In this case the variable must be typed as OpTypeStruct and cannot be aggregated into arrays of that type. Further, the Offset decoration for any member of such a variable must not cause the space required for that variable to extend outside the range [0,maxInlineUniformBlockSize).

Variables identified with a storage class of UniformConstant and a decoration of InputAttachmentIndex must be declared as described in Fragment Input Attachment Interface.

SPIR-V variables decorated with a descriptor set and binding that identify a combined image sampler descriptor can have a type of OpTypeImage, OpTypeSampler (Sampled=1), or OpTypeSampledImage.

Arrays of any of these types can be indexed with constant integral expressions. The following features must be enabled and capabilities must be declared in order to index such arrays with dynamically uniform or non-uniform indices:

Storage images (except storage texel buffers and input attachments):
- Dynamically uniform: shaderStorageImageArrayDynamicIndexing and StorageImageArrayDynamicIndexing
- Non-uniform: shaderStorageImageArrayNonUniformIndexing and StorageImageArrayNonUniformIndexing
Storage texel buffers:
- Dynamically uniform: shaderStorageTexelBufferArrayDynamicIndexing and StorageTexelBufferArrayDynamicIndexing
- Non-uniform: shaderStorageTexelBufferArrayNonUniformIndexing and StorageTexelBufferArrayNonUniformIndexing
Input attachments:
- Dynamically uniform: shaderInputAttachmentArrayDynamicIndexing and InputAttachmentArrayDynamicIndexing
- Non-uniform: shaderInputAttachmentArrayNonUniformIndexing and InputAttachmentArrayNonUniformIndexing
Sampled images (except uniform texel buffers), samplers and combined image samplers:
- Dynamically uniform: shaderSampledImageArrayDynamicIndexing and SampledImageArrayDynamicIndexing
- Non-uniform: shaderSampledImageArrayNonUniformIndexing and SampledImageArrayNonUniformIndexing
Uniform texel buffers:
- Dynamically uniform: shaderUniformTexelBufferArrayDynamicIndexing and UniformTexelBufferArrayDynamicIndexing
- Non-uniform: shaderUniformTexelBufferArrayNonUniformIndexing and UniformTexelBufferArrayNonUniformIndexing
Uniform buffers:
- Dynamically uniform: shaderUniformBufferArrayDynamicIndexing and UniformBufferArrayDynamicIndexing
- Non-uniform: shaderUniformBufferArrayNonUniformIndexing and UniformBufferArrayNonUniformIndexing
Storage buffers:
- Dynamically uniform: shaderStorageBufferArrayDynamicIndexing and StorageBufferArrayDynamicIndexing
- Non-uniform: shaderStorageBufferArrayNonUniformIndexing and StorageBufferArrayNonUniformIndexing

If an instruction loads from or stores to a resource (including atomics and image instructions) and the resource descriptor being accessed is not dynamically uniform, then the corresponding non-uniform indexing feature must be enabled and the capability must be declared. If an instruction loads from or stores to a resource (including atomics and image instructions) and the resource descriptor being accessed is loaded from an array element with a non-constant index, then the corresponding dynamic or non-uniform indexing feature must be enabled and the capability must be declared.

If the combined image sampler enables sampler Y′C_BC_R conversion, it must be indexed only by constant integral expressions when aggregated into arrays in shader code, irrespective of the shaderSampledImageArrayDynamicIndexing feature.

Table 11. Shader Resource and Descriptor Type Correspondence
Resource type	Descriptor Type
sampler	`VK_DESCRIPTOR_TYPE_SAMPLER` or `VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER`
sampled image	`VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE` or `VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER`
storage image	`VK_DESCRIPTOR_TYPE_STORAGE_IMAGE`
combined image sampler	`VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER`
uniform texel buffer	`VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER`
storage texel buffer	`VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER`
uniform buffer	`VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER` or `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC`
storage buffer	`VK_DESCRIPTOR_TYPE_STORAGE_BUFFER` or `VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC`
input attachment	`VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT`
inline uniform block	`VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK`

Table 12. Shader Resource and Storage Class Correspondence
Resource type	Storage Class	Type¹	Decoration(s)²
sampler	`UniformConstant`	`OpTypeSampler`
sampled image	`UniformConstant`	`OpTypeImage` (`Sampled`=1)
storage image	`UniformConstant`	`OpTypeImage` (`Sampled`=2)
combined image sampler	`UniformConstant`	`OpTypeSampledImage` `OpTypeImage` (`Sampled`=1) `OpTypeSampler`
uniform texel buffer	`UniformConstant`	`OpTypeImage` (`Dim`=`Buffer`, `Sampled`=1)
storage texel buffer	`UniformConstant`	`OpTypeImage` (`Dim`=`Buffer`, `Sampled`=2)
uniform buffer	`Uniform`	`OpTypeStruct`	`Block`, `Offset`, (`ArrayStride`), (`MatrixStride`)
storage buffer	`Uniform`	`OpTypeStruct`	`BufferBlock`, `Offset`, (`ArrayStride`), (`MatrixStride`)
storage buffer	`StorageBuffer`	`OpTypeStruct`	`Block`, `Offset`, (`ArrayStride`), (`MatrixStride`)
input attachment	`UniformConstant`	`OpTypeImage` (`Dim`=`SubpassData`, `Sampled`=2)	`InputAttachmentIndex`
inline uniform block	`Uniform`	`OpTypeStruct`	`Block`, `Offset`, (`ArrayStride`), (`MatrixStride`)

1: Where OpTypeImage is referenced, the Dim values Buffer and Subpassdata are only accepted where they are specifically referenced. They do not correspond to resource types where a generic OpTypeImage is specified.
2: In addition to DescriptorSet and Binding.

15.5.3. DescriptorSet and Binding Assignment

A variable decorated with a DescriptorSet decoration of s and a Binding decoration of b indicates that this variable is associated with the VkDescriptorSetLayoutBinding that has a binding equal to b in pSetLayouts[s] that was specified in VkPipelineLayoutCreateInfo.

DescriptorSet decoration values must be between zero and maxBoundDescriptorSets minus one, inclusive. Binding decoration values can be any 32-bit unsigned integer value, as described in Descriptor Set Layout. Each descriptor set has its own binding name space.

If the Binding decoration is used with an array, the entire array is assigned that binding value. The array must be a single-dimensional array and size of the array must be no larger than the number of descriptors in the binding. If the array is runtime-sized, then array elements greater than or equal to the size of that binding in the bound descriptor set must not be used. If the array is runtime-sized, the runtimeDescriptorArray feature must be enabled and the RuntimeDescriptorArray capability must be declared. The index of each element of the array is referred to as the arrayElement. For the purposes of interface matching and descriptor set operations, if a resource variable is not an array, it is treated as if it has an arrayElement of zero.

There is a limit on the number of resources of each type that can be accessed by a pipeline stage as shown in Shader Resource Limits. The “Resources Per Stage” column gives the limit on the number each type of resource that can be statically used for an entry point in any given stage in a pipeline. The “Resource Types” column lists which resource types are counted against the limit. Some resource types count against multiple limits.

The pipeline layout may include descriptor sets and bindings which are not referenced by any variables statically used by the entry points for the shader stages in the binding’s stageFlags.

However, if a variable assigned to a given DescriptorSet and Binding is statically used by the entry point for a shader stage, the pipeline layout must contain a descriptor set layout binding in that descriptor set layout and for that binding number, and that binding’s stageFlags must include the appropriate VkShaderStageFlagBits for that stage. The variable must be of a valid resource type determined by its SPIR-V type and storage class, as defined in Shader Resource and Storage Class Correspondence. The descriptor set layout binding must be of a corresponding descriptor type, as defined in Shader Resource and Descriptor Type Correspondence.

Note

There are no limits on the number of shader variables that can have overlapping set and binding values in a shader; but which resources are statically used has an impact. If any shader variable identifying a resource is statically used in a shader, then the underlying descriptor bound at the declared set and binding must support the declared type in the shader when the shader executes.

If multiple shader variables are declared with the same set and binding values, and with the same underlying descriptor type, they can all be statically used within the same shader. However, accesses are not automatically synchronized, and Aliased decorations should be used to avoid data hazards (see section 2.18.2 Aliasing in the SPIR-V specification).

If multiple shader variables with the same set and binding values are declared in a single shader, but with different declared types, where any of those are not supported by the relevant bound descriptor, that shader can only be executed if the variables with the unsupported type are not statically used.

A noteworthy example of using multiple statically-used shader variables sharing the same descriptor set and binding values is a descriptor of type VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER that has multiple corresponding shader variables in the UniformConstant storage class, where some could be OpTypeImage (Sampled=1), some could be OpTypeSampler, and some could be OpTypeSampledImage.

Table 13. Shader Resource Limits
Resources per Stage	Resource Types
`maxPerStageDescriptorSamplers` or `maxPerStageDescriptorUpdateAfterBindSamplers`	sampler
	combined image sampler
`maxPerStageDescriptorSampledImages` or `maxPerStageDescriptorUpdateAfterBindSampledImages`	sampled image
	combined image sampler
	uniform texel buffer
`maxPerStageDescriptorStorageImages` or `maxPerStageDescriptorUpdateAfterBindStorageImages`	storage image
	storage texel buffer
`maxPerStageDescriptorUniformBuffers` or `maxPerStageDescriptorUpdateAfterBindUniformBuffers`	uniform buffer
	uniform buffer dynamic
`maxPerStageDescriptorStorageBuffers` or `maxPerStageDescriptorUpdateAfterBindStorageBuffers`	storage buffer
	storage buffer dynamic
`maxPerStageDescriptorInputAttachments` or `maxPerStageDescriptorUpdateAfterBindInputAttachments`	input attachment¹
`maxPerStageDescriptorInlineUniformBlocks` or `maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks`	inline uniform block

1: Input attachments can only be used in the fragment shader stage

15.5.4. Offset and Stride Assignment

Certain objects must be explicitly laid out using the Offset, ArrayStride, and MatrixStride, as described in SPIR-V explicit layout validation rules. All such layouts also must conform to the following requirements.

Note

The numeric order of Offset decorations does not need to follow member declaration order.

Alignment Requirements

There are different alignment requirements depending on the specific resources and on the features enabled on the device.

Matrix types are defined in terms of arrays as follows:

A column-major matrix with C columns and R rows is equivalent to a C element array of vectors with R components.
A row-major matrix with C columns and R rows is equivalent to an R element array of vectors with C components.

The scalar alignment of the type of an OpTypeStruct member is defined recursively as follows:

A scalar of size N has a scalar alignment of N.
A vector type has a scalar alignment equal to that of its component type.
An array type has a scalar alignment equal to that of its element type.
A structure has a scalar alignment equal to the largest scalar alignment of any of its members.
A matrix type inherits scalar alignment from the equivalent array declaration.

The base alignment of the type of an OpTypeStruct member is defined recursively as follows:

A scalar has a base alignment equal to its scalar alignment.
A two-component vector has a base alignment equal to twice its scalar alignment.
A three- or four-component vector has a base alignment equal to four times its scalar alignment.
An array has a base alignment equal to the base alignment of its element type.
A structure has a base alignment equal to the largest base alignment of any of its members. An empty structure has a base alignment equal to the size of the smallest scalar type permitted by the capabilities declared in the SPIR-V module. (e.g., for a 1 byte aligned empty struct in the StorageBuffer storage class, StorageBuffer8BitAccess or UniformAndStorageBuffer8BitAccess must be declared in the SPIR-V module.)
A matrix type inherits base alignment from the equivalent array declaration.

The extended alignment of the type of an OpTypeStruct member is similarly defined as follows:

A scalar or vector type has an extended alignment equal to its base alignment.
An array or structure type has an extended alignment equal to the largest extended alignment of any of its members, rounded up to a multiple of 16.
A matrix type inherits extended alignment from the equivalent array declaration.

A member is defined to improperly straddle if either of the following are true:

It is a vector with total size less than or equal to 16 bytes, and has Offset decorations placing its first byte at F and its last byte at L, where floor(F / 16) != floor(L / 16).
It is a vector with total size greater than 16 bytes and has its Offset decorations placing its first byte at a non-integer multiple of 16.

Standard Buffer Layout

Every member of an OpTypeStruct that is required to be explicitly laid out must be aligned according to the first matching rule as follows. If the struct is contained in pointer types of multiple storage classes, it must satisfy the requirements for every storage class used to reference it.

If the scalarBlockLayout feature is enabled on the device and the storage class is Uniform, StorageBuffer, PhysicalStorageBuffer, or PushConstant then every member must be aligned according to its scalar alignment.
All vectors must be aligned according to their scalar alignment.
If the uniformBufferStandardLayout feature is not enabled on the device, then any member of an OpTypeStruct with a storage class of Uniform and a decoration of Block must be aligned according to its extended alignment.
Every other member must be aligned according to its base alignment.

Note

Even if scalar alignment is supported, it is generally more performant to use the base alignment.

The memory layout must obey the following rules:

The Offset decoration of any member must be a multiple of its alignment.
Any ArrayStride or MatrixStride decoration must be a multiple of the alignment of the array or matrix as defined above.

If one of the conditions below applies

The storage class is Uniform, StorageBuffer, PhysicalStorageBuffer, or PushConstant, and the scalarBlockLayout feature is not enabled on the device.
The storage class is any other storage class.

the memory layout must also obey the following rules:

Vectors must not improperly straddle, as defined above.
The Offset decoration of a member must not place it between the end of a structure, an array or a matrix and the next multiple of the alignment of that structure, array or matrix.

Note

The std430 layout in GLSL satisfies these rules for types using the base alignment. The std140 layout satisfies the rules for types using the extended alignment.

15.6. Built-In Variables

Built-in variables are accessed in shaders by declaring a variable decorated with a BuiltIn SPIR-V decoration. The meaning of each BuiltIn decoration is as follows. In the remainder of this section, the name of a built-in is used interchangeably with a term equivalent to a variable decorated with that particular built-in. Built-ins that represent integer values can be declared as either signed or unsigned 32-bit integers.

As mentioned above, some inputs and outputs have an additional level of arrayness relative to other shader inputs and outputs. This level of arrayness is not included in the type descriptions below, but must be included when declaring the built-in.

BaseInstance: Decorating a variable with the BaseInstance built-in will make that variable contain the integer value corresponding to the first instance that was passed to the command that invoked the current vertex shader invocation. BaseInstance is the firstInstance parameter to a direct drawing command or the firstInstance member of a structure consumed by an indirect drawing command.

Valid Usage

VUID-BaseInstance-BaseInstance-04181
The BaseInstance decoration must be used only within the Vertex Execution Model
VUID-BaseInstance-BaseInstance-04182
The variable decorated with BaseInstance must be declared using the Input Storage Class
VUID-BaseInstance-BaseInstance-04183
The variable decorated with BaseInstance must be declared as a scalar 32-bit integer value

BaseVertex: Decorating a variable with the BaseVertex built-in will make that variable contain the integer value corresponding to the first vertex or vertex offset that was passed to the command that invoked the current vertex shader invocation. For non-indexed drawing commands, this variable is the firstVertex parameter to a direct drawing command or the firstVertex member of the structure consumed by an indirect drawing command. For indexed drawing commands, this variable is the vertexOffset parameter to a direct drawing command or the vertexOffset member of the structure consumed by an indirect drawing command.

Valid Usage

VUID-BaseVertex-BaseVertex-04184
The BaseVertex decoration must be used only within the Vertex Execution Model
VUID-BaseVertex-BaseVertex-04185
The variable decorated with BaseVertex must be declared using the Input Storage Class
VUID-BaseVertex-BaseVertex-04186
The variable decorated with BaseVertex must be declared as a scalar 32-bit integer value

ClipDistance: Decorating a variable with the ClipDistance built-in decoration will make that variable contain the mechanism for controlling user clipping. ClipDistance is an array such that the i^th element of the array specifies the clip distance for plane i. A clip distance of 0 means the vertex is on the plane, a positive distance means the vertex is inside the clip half-space, and a negative distance means the vertex is outside the clip half-space.

Note

The array variable decorated with ClipDistance is explicitly sized by the shader.

Note

In the last pre-rasterization shader stage, these values will be linearly interpolated across the primitive and the portion of the primitive with interpolated distances less than 0 will be considered outside the clip volume. If ClipDistance is then used by a fragment shader, ClipDistance contains these linearly interpolated values.

Valid Usage

VUID-ClipDistance-ClipDistance-04187
The ClipDistance decoration must be used only within the MeshEXT, MeshNV, Vertex, Fragment, TessellationControl, TessellationEvaluation, or Geometry Execution Model
VUID-ClipDistance-ClipDistance-04188
The variable decorated with ClipDistance within the MeshEXT, MeshNV, or Vertex Execution Model must be declared using the Output Storage Class
VUID-ClipDistance-ClipDistance-04189
The variable decorated with ClipDistance within the Fragment Execution Model must be declared using the Input Storage Class
VUID-ClipDistance-ClipDistance-04190
The variable decorated with ClipDistance within the TessellationControl, TessellationEvaluation, or Geometry Execution Model must not be declared in a Storage Class other than Input or Output
VUID-ClipDistance-ClipDistance-04191
The variable decorated with ClipDistance must be declared as an array of 32-bit floating-point values

CullDistance: Decorating a variable with the CullDistance built-in decoration will make that variable contain the mechanism for controlling user culling. If any member of this array is assigned a negative value for all vertices belonging to a primitive, then the primitive is discarded before rasterization.

Note

In fragment shaders, the values of the CullDistance array are linearly interpolated across each primitive.

Note

If CullDistance decorates an input variable, that variable will contain the corresponding value from the CullDistance decorated output variable from the previous shader stage.

Valid Usage

VUID-CullDistance-CullDistance-04196
The CullDistance decoration must be used only within the MeshEXT, MeshNV, Vertex, Fragment, TessellationControl, TessellationEvaluation, or Geometry Execution Model
VUID-CullDistance-CullDistance-04197
The variable decorated with CullDistance within the MeshEXT, MeshNV or Vertex Execution Model must be declared using the Output Storage Class
VUID-CullDistance-CullDistance-04198
The variable decorated with CullDistance within the Fragment Execution Model must be declared using the Input Storage Class
VUID-CullDistance-CullDistance-04199
The variable decorated with CullDistance within the TessellationControl, TessellationEvaluation, or Geometry Execution Model must not be declared using a Storage Class other than Input or Output
VUID-CullDistance-CullDistance-04200
The variable decorated with CullDistance must be declared as an array of 32-bit floating-point values

DeviceIndex: The DeviceIndex decoration can be applied to a shader input which will be filled with the device index of the physical device that is executing the current shader invocation. This value will be in the range $[0, m a x (1, p h y s i c a l D e v i c e C o u n t))$ , where physicalDeviceCount is the physicalDeviceCount member of VkDeviceGroupDeviceCreateInfo.

Valid Usage

VUID-DeviceIndex-DeviceIndex-04205
The variable decorated with DeviceIndex must be declared using the Input Storage Class
VUID-DeviceIndex-DeviceIndex-04206
The variable decorated with DeviceIndex must be declared as a scalar 32-bit integer value

DrawIndex: Decorating a variable with the DrawIndex built-in will make that variable contain the integer value corresponding to the zero-based index of the draw that invoked the current vertex shader invocation. For indirect drawing commands, DrawIndex begins at zero and increments by one for each draw executed. The number of draws is given by the drawCount parameter. For direct drawing commands, DrawIndex is always zero. DrawIndex is dynamically uniform.

Valid Usage

VUID-DrawIndex-DrawIndex-04207
The DrawIndex decoration must be used only within the Vertex, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-DrawIndex-DrawIndex-04208
The variable decorated with DrawIndex must be declared using the Input Storage Class
VUID-DrawIndex-DrawIndex-04209
The variable decorated with DrawIndex must be declared as a scalar 32-bit integer value

FragCoord: Decorating a variable with the FragCoord built-in decoration will make that variable contain the framebuffer coordinate $(x, y, z, \frac{1}{w})$ of the fragment being processed. The (x,y) coordinate (0,0) is the upper left corner of the upper left pixel in the framebuffer.

When Sample Shading is enabled, the x and y components of FragCoord reflect the location of one of the samples corresponding to the shader invocation.

Otherwise, the x and y components of FragCoord reflect the location of the center of the fragment.

The z component of FragCoord is the interpolated depth value of the primitive.

The w component is the interpolated $\frac{1}{w}$ .

The Centroid interpolation decoration is ignored, but allowed, on FragCoord.

Valid Usage

VUID-FragCoord-FragCoord-04210
The FragCoord decoration must be used only within the Fragment Execution Model
VUID-FragCoord-FragCoord-04211
The variable decorated with FragCoord must be declared using the Input Storage Class
VUID-FragCoord-FragCoord-04212
The variable decorated with FragCoord must be declared as a four-component vector of 32-bit floating-point values

FragDepth: To have a shader supply a fragment-depth value, the shader must declare the DepthReplacing execution mode. Such a shader’s fragment-depth value will come from the variable decorated with the FragDepth built-in decoration.

This value will be used for any subsequent depth testing performed by the implementation or writes to the depth attachment. See fragment shader depth replacement for details.

Valid Usage

VUID-FragDepth-FragDepth-04213
The FragDepth decoration must be used only within the Fragment Execution Model
VUID-FragDepth-FragDepth-04214
The variable decorated with FragDepth must be declared using the Output Storage Class
VUID-FragDepth-FragDepth-04215
The variable decorated with FragDepth must be declared as a scalar 32-bit floating-point value
VUID-FragDepth-FragDepth-04216
If the shader dynamically writes to the variable decorated with FragDepth, the DepthReplacing Execution Mode must be declared

FrontFacing: Decorating a variable with the FrontFacing built-in decoration will make that variable contain whether the fragment is front or back facing. This variable is non-zero if the current fragment is considered to be part of a front-facing polygon primitive or of a non-polygon primitive and is zero if the fragment is considered to be part of a back-facing polygon primitive.

Valid Usage

VUID-FrontFacing-FrontFacing-04229
The FrontFacing decoration must be used only within the Fragment Execution Model
VUID-FrontFacing-FrontFacing-04230
The variable decorated with FrontFacing must be declared using the Input Storage Class
VUID-FrontFacing-FrontFacing-04231
The variable decorated with FrontFacing must be declared as a boolean value

GlobalInvocationId: Decorating a variable with the GlobalInvocationId built-in decoration will make that variable contain the location of the current invocation within the global workgroup. Each component is equal to the index of the local workgroup multiplied by the size of the local workgroup plus LocalInvocationId.

Valid Usage

VUID-GlobalInvocationId-GlobalInvocationId-04236
The GlobalInvocationId decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-GlobalInvocationId-GlobalInvocationId-04237
The variable decorated with GlobalInvocationId must be declared using the Input Storage Class
VUID-GlobalInvocationId-GlobalInvocationId-04238
The variable decorated with GlobalInvocationId must be declared as a three-component vector of 32-bit integer values

HelperInvocation: Decorating a variable with the HelperInvocation built-in decoration will make that variable contain whether the current invocation is a helper invocation. This variable is non-zero if the current fragment being shaded is a helper invocation and zero otherwise. A helper invocation is an invocation of the shader that is produced to satisfy internal requirements such as the generation of derivatives.

Note

It is very likely that a helper invocation will have a value of SampleMask fragment shader input value that is zero.

Valid Usage

VUID-HelperInvocation-HelperInvocation-04239
The HelperInvocation decoration must be used only within the Fragment Execution Model
VUID-HelperInvocation-HelperInvocation-04240
The variable decorated with HelperInvocation must be declared using the Input Storage Class
VUID-HelperInvocation-HelperInvocation-04241
The variable decorated with HelperInvocation must be declared as a boolean value

InvocationId: Decorating a variable with the InvocationId built-in decoration will make that variable contain the index of the current shader invocation in a geometry shader, or the index of the output patch vertex in a tessellation control shader.

In a geometry shader, the index of the current shader invocation ranges from zero to the number of instances declared in the shader minus one. If the instance count of the geometry shader is one or is not specified, then InvocationId will be zero.

Valid Usage

VUID-InvocationId-InvocationId-04257
The InvocationId decoration must be used only within the TessellationControl or Geometry Execution Model
VUID-InvocationId-InvocationId-04258
The variable decorated with InvocationId must be declared using the Input Storage Class
VUID-InvocationId-InvocationId-04259
The variable decorated with InvocationId must be declared as a scalar 32-bit integer value

InstanceIndex: Decorating a variable in a vertex shader with the InstanceIndex built-in decoration will make that variable contain the index of the instance that is being processed by the current vertex shader invocation. InstanceIndex begins at the firstInstance parameter to vkCmdDraw or vkCmdDrawIndexed or at the firstInstance member of a structure consumed by vkCmdDrawIndirect or vkCmdDrawIndexedIndirect.

Valid Usage

VUID-InstanceIndex-InstanceIndex-04263
The InstanceIndex decoration must be used only within the Vertex Execution Model
VUID-InstanceIndex-InstanceIndex-04264
The variable decorated with InstanceIndex must be declared using the Input Storage Class
VUID-InstanceIndex-InstanceIndex-04265
The variable decorated with InstanceIndex must be declared as a scalar 32-bit integer value

Layer: Decorating a variable with the Layer built-in decoration will make that variable contain the select layer of a multi-layer framebuffer attachment.

In a vertex, tessellation evaluation, or geometry shader, any variable decorated with Layer can be written with the framebuffer layer index to which the primitive produced by that shader will be directed.

The last active pre-rasterization shader stage (in pipeline order) controls the Layer that is used. Outputs in previous shader stages are not used, even if the last stage fails to write the Layer.

If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with Layer, then the first layer is used. If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated with Layer, it must write the same value to Layer for all output vertices of a given primitive. If the Layer value is less than 0 or greater than or equal to the number of layers in the framebuffer, then primitives may still be rasterized, fragment shaders may be executed, and the framebuffer values for all layers are undefined.

In a fragment shader, a variable decorated with Layer contains the layer index of the primitive that the fragment invocation belongs to.

Valid Usage

VUID-Layer-Layer-04272
The Layer decoration must be used only within the MeshEXT, MeshNV, Vertex, TessellationEvaluation, Geometry, or Fragment Execution Model
VUID-Layer-Layer-04273
If the shaderOutputLayer feature is not enabled then the Layer decoration must be used only within the Geometry or Fragment Execution Model
VUID-Layer-Layer-04274
The variable decorated with Layer within the MeshEXT, MeshNV, Vertex, TessellationEvaluation, or Geometry Execution Model must be declared using the Output Storage Class
VUID-Layer-Layer-04275
The variable decorated with Layer within the Fragment Execution Model must be declared using the Input Storage Class
VUID-Layer-Layer-04276
The variable decorated with Layer must be declared as a scalar 32-bit integer value
VUID-Layer-Layer-07039
The variable decorated with Layer within the MeshEXT Execution Model must also be decorated with the PerPrimitiveEXT decoration

LocalInvocationId: Decorating a variable with the LocalInvocationId built-in decoration will make that variable contain the location of the current compute shader invocation within the local workgroup. Each component ranges from zero through to the size of the workgroup in that dimension minus one.

Note

If the size of the workgroup in a particular dimension is one, then the LocalInvocationId in that dimension will be zero. If the workgroup is effectively two-dimensional, then LocalInvocationId.z will be zero. If the workgroup is effectively one-dimensional, then both LocalInvocationId.y and LocalInvocationId.z will be zero.

Valid Usage

VUID-LocalInvocationId-LocalInvocationId-04281
The LocalInvocationId decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-LocalInvocationId-LocalInvocationId-04282
The variable decorated with LocalInvocationId must be declared using the Input Storage Class
VUID-LocalInvocationId-LocalInvocationId-04283
The variable decorated with LocalInvocationId must be declared as a three-component vector of 32-bit integer values

LocalInvocationIndex

Decorating a variable with the LocalInvocationIndex built-in decoration will make that variable contain a one-dimensional representation of LocalInvocationId. This is computed as:

LocalInvocationIndex =
    LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y +
    LocalInvocationId.y * WorkgroupSize.x +
    LocalInvocationId.x;

Valid Usage

VUID-LocalInvocationIndex-LocalInvocationIndex-04284
The LocalInvocationIndex decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-LocalInvocationIndex-LocalInvocationIndex-04285
The variable decorated with LocalInvocationIndex must be declared using the Input Storage Class
VUID-LocalInvocationIndex-LocalInvocationIndex-04286
The variable decorated with LocalInvocationIndex must be declared as a scalar 32-bit integer value

NumSubgroups: Decorating a variable with the NumSubgroups built-in decoration will make that variable contain the number of subgroups in the local workgroup.

Valid Usage

VUID-NumSubgroups-NumSubgroups-04293
The NumSubgroups decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-NumSubgroups-NumSubgroups-04294
The variable decorated with NumSubgroups must be declared using the Input Storage Class
VUID-NumSubgroups-NumSubgroups-04295
The variable decorated with NumSubgroups must be declared as a scalar 32-bit integer value

NumWorkgroups: Decorating a variable with the NumWorkgroups built-in decoration will make that variable contain the number of local workgroups that are part of the dispatch that the invocation belongs to. Each component is equal to the values of the workgroup count parameters passed into the dispatching commands.

Valid Usage

VUID-NumWorkgroups-NumWorkgroups-04296
The NumWorkgroups decoration must be used only within the GLCompute, MeshEXT, or TaskEXT Execution Model
VUID-NumWorkgroups-NumWorkgroups-04297
The variable decorated with NumWorkgroups must be declared using the Input Storage Class
VUID-NumWorkgroups-NumWorkgroups-04298
The variable decorated with NumWorkgroups must be declared as a three-component vector of 32-bit integer values

PatchVertices: Decorating a variable with the PatchVertices built-in decoration will make that variable contain the number of vertices in the input patch being processed by the shader. In a Tessellation Control Shader, this is the same as the name:patchControlPoints member of VkPipelineTessellationStateCreateInfo. In a Tessellation Evaluation Shader, PatchVertices is equal to the tessellation control output patch size. When the same shader is used in different pipelines where the patch sizes are configured differently, the value of the PatchVertices variable will also differ.

Valid Usage

VUID-PatchVertices-PatchVertices-04308
The PatchVertices decoration must be used only within the TessellationControl or TessellationEvaluation Execution Model
VUID-PatchVertices-PatchVertices-04309
The variable decorated with PatchVertices must be declared using the Input Storage Class
VUID-PatchVertices-PatchVertices-04310
The variable decorated with PatchVertices must be declared as a scalar 32-bit integer value

PointCoord: Decorating a variable with the PointCoord built-in decoration will make that variable contain the coordinate of the current fragment within the point being rasterized, normalized to the size of the point with origin in the upper left corner of the point, as described in Basic Point Rasterization. If the primitive the fragment shader invocation belongs to is not a point, then the variable decorated with PointCoord contains an undefined value.

Note

Depending on how the point is rasterized, PointCoord may never reach (0,0) or (1,1).

Valid Usage

VUID-PointCoord-PointCoord-04311
The PointCoord decoration must be used only within the Fragment Execution Model
VUID-PointCoord-PointCoord-04312
The variable decorated with PointCoord must be declared using the Input Storage Class
VUID-PointCoord-PointCoord-04313
The variable decorated with PointCoord must be declared as a two-component vector of 32-bit floating-point values

PointSize: Decorating a variable with the PointSize built-in decoration will make that variable contain the size of point primitives . The value written to the variable decorated with PointSize by the last pre-rasterization shader stage in the pipeline is used as the framebuffer-space size of points produced by rasterization.

Note

When PointSize decorates a variable in the Input Storage Class, it contains the data written to the output variable decorated with PointSize from the previous shader stage.

Valid Usage

VUID-PointSize-PointSize-04314
The PointSize decoration must be used only within the MeshEXT, MeshNV, Vertex, TessellationControl, TessellationEvaluation, or Geometry Execution Model
VUID-PointSize-PointSize-04315
The variable decorated with PointSize within the MeshEXT, MeshNV, or Vertex Execution Model must be declared using the Output Storage Class
VUID-PointSize-PointSize-04316
The variable decorated with PointSize within the TessellationControl, TessellationEvaluation, or Geometry Execution Model must not be declared using a Storage Class other than Input or Output
VUID-PointSize-PointSize-04317
The variable decorated with PointSize must be declared as a scalar 32-bit floating-point value

Position: Decorating a variable with the Position built-in decoration will make that variable contain the position of the current vertex. In the last pre-rasterization shader stage, the value of the variable decorated with Position is used in subsequent primitive assembly, clipping, and rasterization operations.

Note

When Position decorates a variable in the Input Storage Class, it contains the data written to the output variable decorated with Position from the previous shader stage.

Valid Usage

VUID-Position-Position-04318
The Position decoration must be used only within the MeshEXT, MeshNV, Vertex, TessellationControl, TessellationEvaluation, or Geometry Execution Model
VUID-Position-Position-04319
The variable decorated with Position within the MeshEXT, MeshNV, or Vertex Execution Model must be declared using the Output Storage Class
VUID-Position-Position-04320
The variable decorated with Position within the TessellationControl, TessellationEvaluation, or Geometry Execution Model must not be declared using a Storage Class other than Input or Output
VUID-Position-Position-04321
The variable decorated with Position must be declared as a four-component vector of 32-bit floating-point values

PrimitiveId: Decorating a variable with the PrimitiveId built-in decoration will make that variable contain the index of the current primitive.

The index of the first primitive generated by a drawing command is zero, and the index is incremented after every individual point, line, or triangle primitive is processed.

For triangles drawn as points or line segments (see Polygon Mode), the primitive index is incremented only once, even if multiple points or lines are eventually drawn.

Variables decorated with PrimitiveId are reset to zero between each instance drawn.

Restarting a primitive topology using primitive restart has no effect on the value of variables decorated with PrimitiveId.

In tessellation control and tessellation evaluation shaders, it will contain the index of the patch within the current set of rendering primitives that corresponds to the shader invocation.

In a geometry shader, it will contain the number of primitives presented as input to the shader since the current set of rendering primitives was started.

In a fragment shader, it will contain the primitive index written by the geometry shader if a geometry shader is present, or with the value that would have been presented as input to the geometry shader had it been present.

Note

When the PrimitiveId decoration is applied to an output variable in the geometry shader, the resulting value is seen through the PrimitiveId decorated input variable in the fragment shader.

The fragment shader using PrimitiveId will need to declare either the Geometry or Tessellation capability to satisfy the requirement SPIR-V has to use PrimitiveId.

Valid Usage

VUID-PrimitiveId-PrimitiveId-04330
The PrimitiveId decoration must be used only within the MeshEXT, MeshNV, IntersectionKHR, AnyHitKHR, ClosestHitKHR, TessellationControl, TessellationEvaluation, Geometry, or Fragment Execution Model
VUID-PrimitiveId-Fragment-04331
If pipeline contains both the Fragment and Geometry Execution Model and a variable decorated with PrimitiveId is read from Fragment shader, then the Geometry shader must write to the output variables decorated with PrimitiveId in all execution paths
VUID-PrimitiveId-Fragment-04332
If pipeline contains both the Fragment and MeshEXT or MeshNV Execution Model and a variable decorated with PrimitiveId is read from Fragment shader, then the MeshEXT or MeshNV shader must write to the output variables decorated with PrimitiveId in all execution paths
VUID-PrimitiveId-Fragment-04333
If Fragment Execution Model contains a variable decorated with PrimitiveId, then either the MeshShadingEXT, MeshShadingNV, Geometry or Tessellation capability must also be declared
VUID-PrimitiveId-PrimitiveId-04334
The variable decorated with PrimitiveId within the TessellationControl, TessellationEvaluation, Fragment, IntersectionKHR, AnyHitKHR, or ClosestHitKHR Execution Model must be declared using the Input Storage Class
VUID-PrimitiveId-PrimitiveId-04335
The variable decorated with PrimitiveId within the Geometry Execution Model must be declared using the Input or Output Storage Class
VUID-PrimitiveId-PrimitiveId-04336
The variable decorated with PrimitiveId within the MeshEXT or MeshNV Execution Model must be declared using the Output Storage Class
VUID-PrimitiveId-PrimitiveId-04337
The variable decorated with PrimitiveId must be declared as a scalar 32-bit integer value
VUID-PrimitiveId-PrimitiveId-07040
The variable decorated with PrimitiveId within the MeshEXT Execution Model must also be decorated with the PerPrimitiveEXT decoration

SampleId: Decorating a variable with the SampleId built-in decoration will make that variable contain the coverage index for the current fragment shader invocation. SampleId ranges from zero to the number of samples in the framebuffer minus one. If a fragment shader entry point’s interface includes an input variable decorated with SampleId, Sample Shading is considered enabled with a minSampleShading value of 1.0.

Valid Usage

VUID-SampleId-SampleId-04354
The SampleId decoration must be used only within the Fragment Execution Model
VUID-SampleId-SampleId-04355
The variable decorated with SampleId must be declared using the Input Storage Class
VUID-SampleId-SampleId-04356
The variable decorated with SampleId must be declared as a scalar 32-bit integer value

SampleMask: Decorating a variable with the SampleMask built-in decoration will make any variable contain the sample mask for the current fragment shader invocation.

A variable in the Input storage class decorated with SampleMask will contain a bitmask of the set of samples covered by the primitive generating the fragment during rasterization. It has a sample bit set if and only if the sample is considered covered for this fragment shader invocation. SampleMask[] is an array of integers. Bits are mapped to samples in a manner where bit B of mask M (SampleMask[M]) corresponds to sample 32 × M + B.

A variable in the Output storage class decorated with SampleMask is an array of integers forming a bit array in a manner similar to an input variable decorated with SampleMask, but where each bit represents coverage as computed by the shader. This computed SampleMask is combined with the generated coverage mask in the multisample coverage operation.

Variables decorated with SampleMask must be either an unsized array, or explicitly sized to be no larger than the implementation-dependent maximum sample-mask (as an array of 32-bit elements), determined by the maximum number of samples.

If a fragment shader entry point’s interface includes an output variable decorated with SampleMask, the sample mask will be undefined for any array elements of any fragment shader invocations that fail to assign a value. If a fragment shader entry point’s interface does not include an output variable decorated with SampleMask, the sample mask has no effect on the processing of a fragment.

Valid Usage

VUID-SampleMask-SampleMask-04357
The SampleMask decoration must be used only within the Fragment Execution Model
VUID-SampleMask-SampleMask-04358
The variable decorated with SampleMask must be declared using the Input or Output Storage Class
VUID-SampleMask-SampleMask-04359
The variable decorated with SampleMask must be declared as an array of 32-bit integer values

SamplePosition: Decorating a variable with the SamplePosition built-in decoration will make that variable contain the sub-pixel position of the sample being shaded. The top left of the pixel is considered to be at coordinate (0,0) and the bottom right of the pixel is considered to be at coordinate (1,1).

If a fragment shader entry point’s interface includes an input variable decorated with SamplePosition, Sample Shading is considered enabled with a minSampleShading value of 1.0.

Valid Usage

VUID-SamplePosition-SamplePosition-04360
The SamplePosition decoration must be used only within the Fragment Execution Model
VUID-SamplePosition-SamplePosition-04361
The variable decorated with SamplePosition must be declared using the Input Storage Class
VUID-SamplePosition-SamplePosition-04362
The variable decorated with SamplePosition must be declared as a two-component vector of 32-bit floating-point values

SubgroupId: Decorating a variable with the SubgroupId built-in decoration will make that variable contain the index of the subgroup within the local workgroup. This variable is in range [0, NumSubgroups-1].

Valid Usage

VUID-SubgroupId-SubgroupId-04367
The SubgroupId decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-SubgroupId-SubgroupId-04368
The variable decorated with SubgroupId must be declared using the Input Storage Class
VUID-SubgroupId-SubgroupId-04369
The variable decorated with SubgroupId must be declared as a scalar 32-bit integer value

SubgroupEqMask: Decorating a variable with the SubgroupEqMask builtin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bit corresponding to the SubgroupLocalInvocationId is set in the variable decorated with SubgroupEqMask. All other bits are set to zero.

SubgroupEqMaskKHR is an alias of SubgroupEqMask.

Valid Usage

VUID-SubgroupEqMask-SubgroupEqMask-04370
The variable decorated with SubgroupEqMask must be declared using the Input Storage Class
VUID-SubgroupEqMask-SubgroupEqMask-04371
The variable decorated with SubgroupEqMask must be declared as a four-component vector of 32-bit integer values

SubgroupGeMask: Decorating a variable with the SubgroupGeMask builtin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater than or equal to SubgroupLocalInvocationId through SubgroupSize-1 are set in the variable decorated with SubgroupGeMask. All other bits are set to zero.

SubgroupGeMaskKHR is an alias of SubgroupGeMask.

Valid Usage

VUID-SubgroupGeMask-SubgroupGeMask-04372
The variable decorated with SubgroupGeMask must be declared using the Input Storage Class
VUID-SubgroupGeMask-SubgroupGeMask-04373
The variable decorated with SubgroupGeMask must be declared as a four-component vector of 32-bit integer values

SubgroupGtMask: Decorating a variable with the SubgroupGtMask builtin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater than SubgroupLocalInvocationId through SubgroupSize-1 are set in the variable decorated with SubgroupGtMask. All other bits are set to zero.

SubgroupGtMaskKHR is an alias of SubgroupGtMask.

Valid Usage

VUID-SubgroupGtMask-SubgroupGtMask-04374
The variable decorated with SubgroupGtMask must be declared using the Input Storage Class
VUID-SubgroupGtMask-SubgroupGtMask-04375
The variable decorated with SubgroupGtMask must be declared as a four-component vector of 32-bit integer values

SubgroupLeMask: Decorating a variable with the SubgroupLeMask builtin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less than or equal to SubgroupLocalInvocationId are set in the variable decorated with SubgroupLeMask. All other bits are set to zero.

SubgroupLeMaskKHR is an alias of SubgroupLeMask.

Valid Usage

VUID-SubgroupLeMask-SubgroupLeMask-04376
The variable decorated with SubgroupLeMask must be declared using the Input Storage Class
VUID-SubgroupLeMask-SubgroupLeMask-04377
The variable decorated with SubgroupLeMask must be declared as a four-component vector of 32-bit integer values

SubgroupLtMask: Decorating a variable with the SubgroupLtMask builtin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less than SubgroupLocalInvocationId are set in the variable decorated with SubgroupLtMask. All other bits are set to zero.

SubgroupLtMaskKHR is an alias of SubgroupLtMask.

Valid Usage

VUID-SubgroupLtMask-SubgroupLtMask-04378
The variable decorated with SubgroupLtMask must be declared using the Input Storage Class
VUID-SubgroupLtMask-SubgroupLtMask-04379
The variable decorated with SubgroupLtMask must be declared as a four-component vector of 32-bit integer values

SubgroupLocalInvocationId: Decorating a variable with the SubgroupLocalInvocationId builtin decoration will make that variable contain the index of the invocation within the subgroup. This variable is in range [0,SubgroupSize-1].

If VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT is specified, or if module declares SPIR-V version 1.6 or higher, and the local workgroup size in the X dimension of the stage is a multiple of SubgroupSize, full subgroups are enabled for that pipeline stage. When full subgroups are enabled, subgroups must be launched with all invocations active, i.e., there is an active invocation with SubgroupLocalInvocationId for each value in range [0,SubgroupSize-1].

Note

There is no direct relationship between SubgroupLocalInvocationId and LocalInvocationId or LocalInvocationIndex. If the pipeline was created with full subgroups applications can compute their own local invocation index to serve the same purpose:

index = SubgroupLocalInvocationId + SubgroupId × SubgroupSize

If full subgroups are not enabled, some subgroups may be dispatched with inactive invocations that do not correspond to a local workgroup invocation, making the value of index unreliable.

Note

VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT is effectively deprecated when compiling SPIR-V 1.6 shaders, as this behavior is the default for Vulkan with SPIR-V 1.6. This is more aligned with developer expectations, and avoids applications unexpectedly breaking in the future.

Valid Usage

VUID-SubgroupLocalInvocationId-SubgroupLocalInvocationId-04380
The variable decorated with SubgroupLocalInvocationId must be declared using the Input Storage Class
VUID-SubgroupLocalInvocationId-SubgroupLocalInvocationId-04381
The variable decorated with SubgroupLocalInvocationId must be declared as a scalar 32-bit integer value

SubgroupSize: Decorating a variable with the SubgroupSize builtin decoration will make that variable contain the implementation-dependent number of invocations in a subgroup. This value must be a power-of-two integer.

If the pipeline was created with the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set, or the SPIR-V module is at least version 1.6, the SubgroupSize decorated variable will contain the subgroup size for each subgroup that gets dispatched. This value must be between minSubgroupSize and maxSubgroupSize and must be uniform with subgroup scope. The value may vary across a single draw call, and for fragment shaders may vary across a single primitive. In compute dispatches, SubgroupSize must be uniform with command scope.

If the pipeline was created with a chained VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure, the SubgroupSize decorated variable will match requiredSubgroupSize.

If SPIR-V module is less than version 1.6 and the pipeline was not created with the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure was chained, the variable decorated with SubgroupSize will match subgroupSize.

The maximum number of invocations that an implementation can support per subgroup is 128.

Note

The old behavior for SubgroupSize is considered deprecated as certain compute algorithms cannot be easily implemented without the guarantees of VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT and VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT.

Valid Usage

VUID-SubgroupSize-SubgroupSize-04382
The variable decorated with SubgroupSize must be declared using the Input Storage Class
VUID-SubgroupSize-SubgroupSize-04383
The variable decorated with SubgroupSize must be declared as a scalar 32-bit integer value

TessCoord: Decorating a variable with the TessCoord built-in decoration will make that variable contain the three-dimensional (u,v,w) barycentric coordinate of the tessellated vertex within the patch. u, v, and w are in the range [0,1] and vary linearly across the primitive being subdivided. For the tessellation modes of Quads or IsoLines, the third component is always zero.

Valid Usage

VUID-TessCoord-TessCoord-04387
The TessCoord decoration must be used only within the TessellationEvaluation Execution Model
VUID-TessCoord-TessCoord-04388
The variable decorated with TessCoord must be declared using the Input Storage Class
VUID-TessCoord-TessCoord-04389
The variable decorated with TessCoord must be declared as a three-component vector of 32-bit floating-point values

TessLevelOuter: Decorating a variable with the TessLevelOuter built-in decoration will make that variable contain the outer tessellation levels for the current patch.

In tessellation control shaders, the variable decorated with TessLevelOuter can be written to, controlling the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.

In tessellation evaluation shaders, the variable decorated with TessLevelOuter can read the values written by the tessellation control shader.

Valid Usage

VUID-TessLevelOuter-TessLevelOuter-04390
The TessLevelOuter decoration must be used only within the TessellationControl or TessellationEvaluation Execution Model
VUID-TessLevelOuter-TessLevelOuter-04391
The variable decorated with TessLevelOuter within the TessellationControl Execution Model must be declared using the Output Storage Class
VUID-TessLevelOuter-TessLevelOuter-04392
The variable decorated with TessLevelOuter within the TessellationEvaluation Execution Model must be declared using the Input Storage Class
VUID-TessLevelOuter-TessLevelOuter-04393
The variable decorated with TessLevelOuter must be declared as an array of size four, containing 32-bit floating-point values

TessLevelInner: Decorating a variable with the TessLevelInner built-in decoration will make that variable contain the inner tessellation levels for the current patch.

In tessellation control shaders, the variable decorated with TessLevelInner can be written to, controlling the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.

In tessellation evaluation shaders, the variable decorated with TessLevelInner can read the values written by the tessellation control shader.

Valid Usage

VUID-TessLevelInner-TessLevelInner-04394
The TessLevelInner decoration must be used only within the TessellationControl or TessellationEvaluation Execution Model
VUID-TessLevelInner-TessLevelInner-04395
The variable decorated with TessLevelInner within the TessellationControl Execution Model must be declared using the Output Storage Class
VUID-TessLevelInner-TessLevelInner-04396
The variable decorated with TessLevelInner within the TessellationEvaluation Execution Model must be declared using the Input Storage Class
VUID-TessLevelInner-TessLevelInner-04397
The variable decorated with TessLevelInner must be declared as an array of size two, containing 32-bit floating-point values

VertexIndex: Decorating a variable with the VertexIndex built-in decoration will make that variable contain the index of the vertex that is being processed by the current vertex shader invocation. For non-indexed draws, this variable begins at the firstVertex parameter to vkCmdDraw or the firstVertex member of a structure consumed by vkCmdDrawIndirect and increments by one for each vertex in the draw. For indexed draws, its value is the content of the index buffer for the vertex plus the vertexOffset parameter to vkCmdDrawIndexed or the vertexOffset member of the structure consumed by vkCmdDrawIndexedIndirect.

Note

VertexIndex starts at the same starting value for each instance.

Valid Usage

VUID-VertexIndex-VertexIndex-04398
The VertexIndex decoration must be used only within the Vertex Execution Model
VUID-VertexIndex-VertexIndex-04399
The variable decorated with VertexIndex must be declared using the Input Storage Class
VUID-VertexIndex-VertexIndex-04400
The variable decorated with VertexIndex must be declared as a scalar 32-bit integer value

ViewIndex: The ViewIndex decoration can be applied to a shader input which will be filled with the index of the view that is being processed by the current shader invocation.

If multiview is enabled in the render pass, this value will be one of the bits set in the view mask of the subpass the pipeline is compiled against. If multiview is not enabled in the render pass, this value will be zero.

Valid Usage

VUID-ViewIndex-ViewIndex-04401
The ViewIndex decoration must be used only within the MeshEXT, Vertex, Geometry, TessellationControl, TessellationEvaluation or Fragment Execution Model
VUID-ViewIndex-ViewIndex-04402
The variable decorated with ViewIndex must be declared using the Input Storage Class
VUID-ViewIndex-ViewIndex-04403
The variable decorated with ViewIndex must be declared as a scalar 32-bit integer value

ViewportIndex: Decorating a variable with the ViewportIndex built-in decoration will make that variable contain the index of the viewport.

In a vertex, tessellation evaluation, or geometry shader, the variable decorated with ViewportIndex can be written to with the viewport index to which the primitive produced by that shader will be directed.

The selected viewport index is used to select the viewport transform and scissor rectangle.

The last active pre-rasterization shader stage (in pipeline order) controls the ViewportIndex that is used. Outputs in previous shader stages are not used, even if the last stage fails to write the ViewportIndex.

If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with ViewportIndex then the first viewport is used. If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated with ViewportIndex, it must write the same value to ViewportIndex for all output vertices of a given primitive.

In a fragment shader, the variable decorated with ViewportIndex contains the viewport index of the primitive that the fragment invocation belongs to.

Valid Usage

VUID-ViewportIndex-ViewportIndex-04404
The ViewportIndex decoration must be used only within the MeshEXT, MeshNV, Vertex, TessellationEvaluation, Geometry, or Fragment Execution Model
VUID-ViewportIndex-ViewportIndex-04405
If the shaderOutputViewportIndex feature is not enabled then the ViewportIndex decoration must be used only within the Geometry or Fragment Execution Model
VUID-ViewportIndex-ViewportIndex-04406
The variable decorated with ViewportIndex within the MeshEXT, MeshNV, Vertex, TessellationEvaluation, or Geometry Execution Model must be declared using the Output Storage Class
VUID-ViewportIndex-ViewportIndex-04407
The variable decorated with ViewportIndex within the Fragment Execution Model must be declared using the Input Storage Class
VUID-ViewportIndex-ViewportIndex-04408
The variable decorated with ViewportIndex must be declared as a scalar 32-bit integer value
VUID-ViewportIndex-ViewportIndex-07060
The variable decorated with ViewportIndex within the MeshEXT Execution Model must also be decorated with the PerPrimitiveEXT decoration

WorkgroupId: Decorating a variable with the WorkgroupId built-in decoration will make that variable contain the global workgroup that the current invocation is a member of. Each component ranges from a base value to a base + count value, based on the parameters passed into the dispatching commands.

Valid Usage

VUID-WorkgroupId-WorkgroupId-04422
The WorkgroupId decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-WorkgroupId-WorkgroupId-04423
The variable decorated with WorkgroupId must be declared using the Input Storage Class
VUID-WorkgroupId-WorkgroupId-04424
The variable decorated with WorkgroupId must be declared as a three-component vector of 32-bit integer values

WorkgroupSize

Note

SPIR-V 1.6 deprecated WorkgroupSize in favor of using the LocalSizeId Execution Mode instead. Support for LocalSizeId was added with VK_KHR_maintenance4 and promoted to core in Version 1.3.

Decorating an object with the WorkgroupSize built-in decoration will make that object contain the dimensions of a local workgroup. If an object is decorated with the WorkgroupSize decoration, this takes precedence over any LocalSize or LocalSizeId execution mode.

Valid Usage

VUID-WorkgroupSize-WorkgroupSize-04425
The WorkgroupSize decoration must be used only within the GLCompute, MeshEXT, TaskEXT, MeshNV, or TaskNV Execution Model
VUID-WorkgroupSize-WorkgroupSize-04426
The variable decorated with WorkgroupSize must be a specialization constant or a constant
VUID-WorkgroupSize-WorkgroupSize-04427
The variable decorated with WorkgroupSize must be declared as a three-component vector of 32-bit integer values