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
|
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
BuiltIndecoration, -
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
, except for the mesh output interface where there must be at most one
built-in interface block decorated with the PerPrimitiveEXT decoration
and at most one built-in interface block without this decoration
.
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:
-
XfbBuffer,XfbStride,Offset, andStream -
one is not decorated with
Componentand the other is declared with aComponentof0 -
RelaxedPrecisionif 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
OpTypeArraywith anElementTypeequivalent to theOpType*declaration of the output, and neither is a structure member; or -
if the
maintenance4feature is enabled, they are declared asOpTypeVectorvariables, and the output has aComponentCountvalue higher than that of the input but the sameComponentType; or -
if the output is declared in a mesh shader as an
OpTypeArraywith anElementTypeequivalent to theOpType*declaration of the input, and neither is a structure member; or -
if the input is decorated with
PerVertexKHR, and is declared in a fragment shader as anOpTypeArraywith anElementTypeequivalent to theOpType*declaration of the output, and neither the input nor the output is a structure member; 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
|
If the pipeline is compiled as separate graphics pipeline libraries and the
graphicsPipelineLibraryIndependentInterpolationDecoration limit is
not supported, matches are not found if the
interpolation decorations differ
between the last pre-rasterization shader stage and the fragment shader stage.
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.
Matching rules for passthrough geometry shaders are slightly different and are described in the Passthrough Interface Matching section.
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.
| Shader Interface | Locations Available |
|---|---|
vertex input |
|
vertex output |
|
tessellation control input |
|
tessellation control output |
|
tessellation evaluation input |
|
tessellation evaluation output |
|
geometry input |
|
geometry output |
|
fragment input |
|
fragment output |
|
mesh output |
|
cluster culling output |
|
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. Legacy Dithering
The application can enable dithering to be applied to the color output of a
subpass, by using the
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT
or the VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT flags.
When dithering is enabled, the implementation may modify the output color value c by one ULP. This modification must only depend on the framebuffer coordinates (xf,yf) of the sample, as well as on the value of c.
The exact details of the dithering algorithm are unspecified, including the algorithm itself, the formats dithering is applied to, and the stage in which it is applied.
|
Note
This extension is intended only for use by OpenGL emulation layers, and as such the dithering algorithm applied to the subpass should be equivalent to the vendor’s OpenGL implementation, if any. |
15.5. 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
multisampled-render-to-single-sampled
is not enabled, 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.5.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.6. Ray Tracing Pipeline Interface
Ray tracing pipelines may have more stages than other pipelines with multiple instances of each stage and more dynamic interactions between the stages, but still have interface structures that obey the same general rules as interfaces between shader stages in other pipelines. The three types of inter-stage interface variables for ray tracing pipelines are:
-
Ray payloads containing data tracked for the entire lifetime of the ray.
-
Hit attributes containing data about a specific hit for the duration of its processing.
-
Callable data for passing data into and out of a callable shader.
Ray payloads and callable data are used in explicit shader call instructions, so they have an incoming variant to distinguish the parameter passed to the invocation from any other payloads or data being used by subsequent shader call instructions.
An interface structure used between stages must match between the stages using it. Specifically:
-
The hit attribute structure read in an any-hit or closest hit shader must be the same structure as the hit attribute structure written in the corresponding intersection shader in the same hit group.
-
The incoming callable data for a callable shader must be the same structure as the callable data referenced by the execute callable instruction in the calling shader.
-
The ray payload for a shader invoked by a ray tracing command must be the same structure for all shader stages using the payload for that ray.
Any shader with an incoming ray payload, incoming callable data, or hit attribute must only declare one variable of that type.
| Shader Stage | Ray Payload | Incoming Ray Payload | Hit Attribute | Callable Data | Incoming Callable Data |
|---|---|---|---|---|---|
Ray Generation |
r/w |
r/w |
|||
Intersection |
r/w |
||||
Any-Hit |
r/w |
r |
|||
Closest Hit |
r/w |
r/w |
r |
r/w |
|
Miss |
r/w |
r/w |
r/w |
||
Callable |
r/w |
r/w |
15.7. 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.7.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
Blockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations 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.7.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 theshaderStorageImageWriteWithoutFormatfeature is enabled and the shader module declares theStorageImageWriteWithoutFormatcapability. -
For
OpImageWrite, if the image format supportsVK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITand the shader module declares theStorageImageWriteWithoutFormatcapability. -
For
OpImageReadorOpImageSparseRead, if the image format is listed in the storage without format list and if theshaderStorageImageReadWithoutFormatfeature is enabled and the shader module declares theStorageImageReadWithoutFormatcapability. -
For
OpImageReadorOpImageSparseRead, if the image format supportsVK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITand the shader module declares theStorageImageReadWithoutFormatcapability. -
For
OpImageRead, ifDimisSubpassData(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
BlockorBufferBlockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations 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
Blockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations 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:
shaderStorageImageArrayDynamicIndexingandStorageImageArrayDynamicIndexing -
Non-uniform:
shaderStorageImageArrayNonUniformIndexingandStorageImageArrayNonUniformIndexing
-
-
Storage texel buffers:
-
Dynamically uniform:
shaderStorageTexelBufferArrayDynamicIndexingandStorageTexelBufferArrayDynamicIndexing -
Non-uniform:
shaderStorageTexelBufferArrayNonUniformIndexingandStorageTexelBufferArrayNonUniformIndexing
-
-
Input attachments:
-
Dynamically uniform:
shaderInputAttachmentArrayDynamicIndexingandInputAttachmentArrayDynamicIndexing -
Non-uniform:
shaderInputAttachmentArrayNonUniformIndexingandInputAttachmentArrayNonUniformIndexing
-
-
Sampled images (except uniform texel buffers), samplers and combined image samplers:
-
Dynamically uniform:
shaderSampledImageArrayDynamicIndexingandSampledImageArrayDynamicIndexing -
Non-uniform:
shaderSampledImageArrayNonUniformIndexingandSampledImageArrayNonUniformIndexing
-
-
Uniform texel buffers:
-
Dynamically uniform:
shaderUniformTexelBufferArrayDynamicIndexingandUniformTexelBufferArrayDynamicIndexing -
Non-uniform:
shaderUniformTexelBufferArrayNonUniformIndexingandUniformTexelBufferArrayNonUniformIndexing
-
-
Uniform buffers:
-
Dynamically uniform:
shaderUniformBufferArrayDynamicIndexingandUniformBufferArrayDynamicIndexing -
Non-uniform:
shaderUniformBufferArrayNonUniformIndexingandUniformBufferArrayNonUniformIndexing
-
-
Storage buffers:
-
Dynamically uniform:
shaderStorageBufferArrayDynamicIndexingandStorageBufferArrayDynamicIndexing -
Non-uniform:
shaderStorageBufferArrayNonUniformIndexingandStorageBufferArrayNonUniformIndexing
-
-
Acceleration structures:
-
Dynamically uniform: Always supported.
-
Non-uniform: Always supported.
-
-
-
Dynamically uniform: Always supported.
-
Non-uniform: Never supported.
-
-
-
Dynamically uniform: Always supported.
-
Non-uniform: Never supported.
-
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′CBCR
conversion or samples a subsampled image,
it must be indexed only by constant integral expressions when aggregated
into arrays in shader code, irrespective of the
shaderSampledImageArrayDynamicIndexing feature.
| Resource type | Descriptor Type |
|---|---|
sampler |
|
sampled image |
|
storage image |
|
combined image sampler |
|
uniform texel buffer |
|
storage texel buffer |
|
uniform buffer |
|
storage buffer |
|
input attachment |
|
inline uniform block |
|
acceleration structure |
|
weight image |
|
block matching image |
|
| Resource type | Storage Class | Type1 | Decoration(s)2 |
|---|---|---|---|
sampler |
|
|
|
sampled image |
|
|
|
storage image |
|
|
|
combined image sampler |
|
|
|
uniform texel buffer |
|
|
|
storage texel buffer |
|
|
|
uniform buffer |
|
|
|
storage buffer |
|
|
|
|
|
||
input attachment |
|
|
|
inline uniform block |
|
|
|
acceleration structure |
|
|
|
sample weight image |
|
|
|
block matching image |
|
|
|
- 1
-
Where
OpTypeImageis referenced, theDimvaluesBufferandSubpassdataare only accepted where they are specifically referenced. They do not correspond to resource types where a genericOpTypeImageis specified. - 2
-
In addition to
DescriptorSetandBinding.
15.7.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 VK_DESCRIPTOR_TYPE_MUTABLE_EXT descriptor type counts as one
individual resource and one for every unique resource limit per descriptor
set type that is present in the associated binding’s
VkMutableDescriptorTypeListEXT.
If multiple descriptor types in VkMutableDescriptorTypeListEXT map to
the same resource limit, only one descriptor is consumed for purposes of
computing resource 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 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
|
| Resources per Stage | Resource Types |
|---|---|
|
sampler |
combined image sampler |
|
|
sampled image |
combined image sampler |
|
uniform texel buffer |
|
sample weight image |
|
block matching image |
|
|
storage image |
storage texel buffer |
|
|
uniform buffer |
uniform buffer dynamic |
|
|
storage buffer |
storage buffer dynamic |
|
|
input attachment1 |
|
inline uniform block |
|
acceleration structure |
- 1
-
Input attachments can only be used in the fragment shader stage
15.7.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 |
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
StorageBufferstorage class,StorageBuffer8BitAccessorUniformAndStorageBuffer8BitAccessmust 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
Offsetdecorations 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
Offsetdecorations 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
scalarBlockLayoutfeature is enabled on the device and the storage class isUniform,StorageBuffer,PhysicalStorageBuffer,ShaderRecordBufferKHR, orPushConstantthen every member must be aligned according to its scalar alignment. -
If the
workgroupMemoryExplicitLayoutScalarBlockLayoutfeature is enabled on the device and the storage class isWorkgroupthen every member must be aligned according to its scalar alignment. -
All vectors must be aligned according to their scalar alignment.
-
If the
uniformBufferStandardLayoutfeature is not enabled on the device, then any member of anOpTypeStructwith a storage class ofUniformand a decoration ofBlockmust 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
Offsetdecoration of any member must be a multiple of its alignment. -
Any
ArrayStrideorMatrixStridedecoration 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,ShaderRecordBufferKHR, orPushConstant, and thescalarBlockLayoutfeature is not enabled on the device. -
The storage class is
Workgroup, and either the struct member is not part of aBlockor theworkgroupMemoryExplicitLayoutScalarBlockLayoutfeature 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
Offsetdecoration 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.8. 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.
BaryCoordKHR-
The
BaryCoordKHRdecoration can be used to decorate a fragment shader input variable. This variable will contain a three-component floating-point vector with barycentric weights that indicate the location of the fragment relative to the screen-space locations of vertices of its primitive, obtained using perspective interpolation.
BaryCoordNoPerspAMD-
The
BaryCoordNoPerspAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at the fragment’s center. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordNoPerspKHR-
The
BaryCoordNoPerspKHRdecoration can be used to decorate a fragment shader input variable. This variable will contain a three-component floating-point vector with barycentric weights that indicate the location of the fragment relative to the screen-space locations of vertices of its primitive, obtained using linear interpolation.
BaryCoordNoPerspCentroidAMD-
The
BaryCoordNoPerspCentroidAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at the centroid. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordNoPerspSampleAMD-
The
BaryCoordNoPerspSampleAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at each covered sample. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordPullModelAMD-
The
BaryCoordPullModelAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain (1/W, 1/I, 1/J) evaluated at the fragment center and can be used to calculate gradients and then interpolate I, J, and W at any desired sample location.
BaryCoordSmoothAMD-
The
BaryCoordSmoothAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at the fragment’s center. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordSmoothCentroidAMD-
The
BaryCoordSmoothCentroidAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at the centroid. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordSmoothSampleAMD-
The
BaryCoordSmoothSampleAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at each covered sample. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaseInstance-
Decorating a variable with the
BaseInstancebuilt-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.BaseInstanceis thefirstInstanceparameter to a direct drawing command or thefirstInstancemember of a structure consumed by an indirect drawing command.
BaseVertex-
Decorating a variable with the
BaseVertexbuilt-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 thefirstVertexparameter to a direct drawing command or thefirstVertexmember of the structure consumed by an indirect drawing command. For indexed drawing commands, this variable is thevertexOffsetparameter to a direct drawing command or thevertexOffsetmember of the structure consumed by an indirect drawing command.
ClipDistance-
Decorating a variable with the
ClipDistancebuilt-in decoration will make that variable contain the mechanism for controlling user clipping.ClipDistanceis an array such that the ith 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 |
|
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 |
ClipDistancePerViewNV-
Decorating a variable with the
ClipDistancePerViewNVbuilt-in decoration will make that variable contain the per-view clip distances. The per-view clip distances have the same semantics asClipDistance.
ClusterIDHUAWEI-
The
ClusterIDHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the id of cluster being rendered by this drawing command. When Cluster Culling Shader enable,ClusterIDHUAWEIwill replace gl_DrawID pass to vertex shader for cluster-related information fetching.
CullDistance-
Decorating a variable with the
CullDistancebuilt-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 |
|
Note
If |
CullDistancePerViewNV-
Decorating a variable with the
CullDistancePerViewNVbuilt-in decoration will make that variable contain the per-view cull distances. The per-view cull distances have the same semantics asCullDistance.
CullPrimitiveEXT-
Decorating a variable with the
CullPrimitiveEXTbuilt-in decoration will make that variable contain the culling state of output primitives. If the per-primitive boolean value istrue, the primitive will be culled, if it isfalseit will not be culled.
CullMaskKHR-
A variable decorated with the
CullMaskKHRdecoration will specify the cull mask of the ray being processed. The value is given by theCull Maskparameter passed into one of theOpTrace*instructions.
CurrentRayTimeNV-
A variable decorated with the
CurrentRayTimeNVdecoration contains the time value passed in toOpTraceRayMotionNVwhich called this shader.
DeviceIndex-
The
DeviceIndexdecoration 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 , where physicalDeviceCount is thephysicalDeviceCountmember of VkDeviceGroupDeviceCreateInfo.
DrawIndex-
Decorating a variable with the
DrawIndexbuilt-in will make that variable contain the integer value corresponding to the zero-based index of the drawing command that invoked the current task, mesh, or vertex shader invocation. For indirect drawing commands,DrawIndexbegins at zero and increments by one for each drawing command executed. The number of drawing commands is given by thedrawCountparameter. For direct drawing commands, if vkCmdDrawMultiEXT or vkCmdDrawMultiIndexedEXT is used, this variable contains the integer value corresponding to the zero-based index of the draw command. OtherwiseDrawIndexis always zero.DrawIndexis dynamically uniform.
When task or mesh shaders are used, only the first active stage will have proper access to the variable. The value read by other stages is undefined.
FirstIndexHUAWEI-
The
FirstIndexHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies the base index within the index buffer corresponding to a cluster.
FragCoord-
Decorating a variable with the
FragCoordbuilt-in decoration will make that variable contain the framebuffer coordinate 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
FragCoordreflect the location of one of the samples corresponding to the shader invocation.Otherwise, the x and y components of
FragCoordreflect the location of the center of the fragment.The z component of
FragCoordis the interpolated depth value of the primitive.The w component is the interpolated .
The
Centroidinterpolation decoration is ignored, but allowed, onFragCoord.
FragDepth-
To have a shader supply a fragment-depth value, the shader must declare the
DepthReplacingexecution mode. Such a shader’s fragment-depth value will come from the variable decorated with theFragDepthbuilt-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.
FirstInstanceHUAWEI-
The
FirstInstanceHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the instance ID of the first instance to draw.
FirstVertexHUAWEI-
The
FirstVertexHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this non-indexed mode specific variable will contain an integer value that specifies the index of the first vertex in a cluster to draw.
FragInvocationCountEXT-
Decorating a variable with the
FragInvocationCountEXTbuilt-in decoration will make that variable contain the maximum number of fragment shader invocations for the fragment, as determined byminSampleShading.If Sample Shading is not enabled,
FragInvocationCountEXTwill be filled with a value of 1.
FragSizeEXT-
Decorating a variable with the
FragSizeEXTbuilt-in decoration will make that variable contain the dimensions in pixels of the area that the fragment covers for that invocation.If fragment density map is not enabled,
FragSizeEXTwill be filled with a value of (1,1).
FragStencilRefEXT-
Decorating a variable with the
FragStencilRefEXTbuilt-in decoration will make that variable contain the new stencil reference value for all samples covered by the fragment. This value will be used as the stencil reference value used in stencil testing.To write to
FragStencilRefEXT, a shader must declare theStencilRefReplacingEXTexecution mode. If a shader declares theStencilRefReplacingEXTexecution mode and there is an execution path through the shader that does not setFragStencilRefEXT, then the fragment’s stencil reference value is undefined for executions of the shader that take that path.Only the least significant s bits of the integer value of the variable decorated with
FragStencilRefEXTare considered for stencil testing, where s is the number of bits in the stencil framebuffer attachment, and higher order bits are discarded.See fragment shader stencil reference replacement for more details.
FragmentSizeNV-
Decorating a variable with the
FragmentSizeNVbuilt-in decoration will make that variable contain the width and height of the fragment.
FrontFacing-
Decorating a variable with the
FrontFacingbuilt-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.
FullyCoveredEXT-
Decorating a variable with the
FullyCoveredEXTbuilt-in decoration will make that variable indicate whether the fragment area is fully covered by the generating primitive. This variable is non-zero if conservative rasterization is enabled and the current fragment area is fully covered by the generating primitive, and is zero if the fragment is not covered or partially covered, or conservative rasterization is disabled.
GlobalInvocationId-
Decorating a variable with the
GlobalInvocationIdbuilt-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 plusLocalInvocationId.
HelperInvocation-
Decorating a variable with the
HelperInvocationbuilt-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
|
HitKindKHR-
A variable decorated with the
HitKindKHRdecoration will describe the intersection that triggered the execution of the current shader. The values are determined by the intersection shader. For user-defined intersection shaders this is the value that was passed to the “Hit Kind” operand ofOpReportIntersectionKHR. For triangle intersection candidates, this will be one ofHitKindFrontFacingTriangleKHRorHitKindBackFacingTriangleKHR.
HitTNV-
A variable decorated with the
HitTNVdecoration is equivalent to a variable decorated with theRayTmaxKHRdecoration.
IncomingRayFlagsKHR-
A variable with the
IncomingRayFlagsKHRdecoration will contain the ray flags passed in to the trace call that invoked this particular shader. Setting pipeline flags on the raytracing pipeline must not cause any corresponding flags to be set in variables with this decoration.
IndexCountHUAWEI-
The
IndexCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies the number of indexed vertices in a cluster to draw.
InstanceCountHUAWEI-
The
InstanceCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the number of instance to draw in a cluster.
InstanceCustomIndexKHR-
A variable decorated with the
InstanceCustomIndexKHRdecoration will contain the application-defined value of the instance that intersects the current ray. This variable contains the value that was specified in VkAccelerationStructureInstanceKHR::instanceCustomIndexfor the current acceleration structure instance in the lower 24 bits and the upper 8 bits will be zero.
InstanceId-
Decorating a variable in an intersection, any-hit, or closest hit shader with the
InstanceIddecoration will make that variable contain the index of the instance that intersects the current ray.
InvocationId-
Decorating a variable with the
InvocationIdbuilt-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
InvocationIdwill be zero.
InvocationsPerPixelNV-
Decorating a variable with the
InvocationsPerPixelNVbuilt-in decoration will make that variable contain the maximum number of fragment shader invocations per pixel, as derived from the effective shading rate for the fragment. If a primitive does not fully cover a pixel, the number of fragment shader invocations for that pixel may be less than the value ofInvocationsPerPixelNV. If the shading rate indicates a fragment covering multiple pixels, thenInvocationsPerPixelNVwill be one.
InstanceIndex-
Decorating a variable in a vertex shader with the
InstanceIndexbuilt-in decoration will make that variable contain the index of the instance that is being processed by the current vertex shader invocation.InstanceIndexbegins at thefirstInstanceparameter to vkCmdDraw or vkCmdDrawIndexed or at thefirstInstancemember of a structure consumed by vkCmdDrawIndirect or vkCmdDrawIndexedIndirect.
LaunchIdKHR-
A variable decorated with the
LaunchIdKHRdecoration will specify the index of the work item being processed. One work item is generated for each of thewidth×height×depthitems dispatched by a vkCmdTraceRaysKHR command. All shader invocations inherit the same value for variables decorated withLaunchIdKHR.
LaunchSizeKHR-
A variable decorated with the
LaunchSizeKHRdecoration will contain thewidth,height, anddepthdimensions passed to the vkCmdTraceRaysKHR command that initiated this shader execution. Thewidthis in the first component, theheightis in the second component, and thedepthis in the third component.
Layer-
Decorating a variable with the
Layerbuilt-in decoration will make that variable contain the select layer of a multi-layer framebuffer attachment.In a mesh, vertex, tessellation evaluation, or geometry shader, any variable decorated with
Layercan 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
Layerthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theLayer.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 withLayer, it must write the same value toLayerfor all output vertices of a given primitive. If theLayervalue 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 mesh shader this also applies when theLayervalue is greater than or equal to themaxMeshOutputLayerslimit.If a variable with the
Layerdecoration is also decorated withViewportRelativeNV, then theViewportIndexis added to the layer that is used for rendering and that is made available in the fragment shader.If the shader writes to a variable decorated
ViewportMaskNV, then the layer selected has a different value for each viewport a primitive is rendered to.In a fragment shader, a variable decorated with
Layercontains the layer index of the primitive that the fragment invocation belongs to.
LayerPerViewNV-
Decorating a variable with the
LayerPerViewNVbuilt-in decoration will make that variable contain the per-view layer information. The per-view layer has the same semantics asLayer, for each view.
LocalInvocationId-
Decorating a variable with the
LocalInvocationIdbuilt-in decoration will make that variable contain the location of the current cluster culling, task, mesh, or 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
|
LocalInvocationIndex-
Decorating a variable with the
LocalInvocationIndexbuilt-in decoration will make that variable contain a one-dimensional representation ofLocalInvocationId. This is computed as:LocalInvocationIndex = LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y + LocalInvocationId.y * WorkgroupSize.x + LocalInvocationId.x;
MeshViewCountNV-
Decorating a variable with the
MeshViewCountNVbuilt-in decoration will make that variable contain the number of views processed by the current mesh or task shader invocations.
MeshViewIndicesNV-
Decorating a variable with the
MeshViewIndicesNVbuilt-in decoration will make that variable contain the mesh view indices. The mesh view indices is an array of values where each element holds the view number of one of the views being processed by the current mesh or task shader invocations. The values of array elements with indices greater than or equal toMeshViewCountNVare undefined. If the value ofMeshViewIndicesNV[i] is j, then any outputs decorated withPerViewNVwill take on the value of array element i when processing primitives for view index j.
NumSubgroups-
Decorating a variable with the
NumSubgroupsbuilt-in decoration will make that variable contain the number of subgroups in the local workgroup.
NumWorkgroups-
Decorating a variable with the
NumWorkgroupsbuilt-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.
ObjectRayDirectionKHR-
A variable decorated with the
ObjectRayDirectionKHRdecoration will specify the direction of the ray being processed, in object space.
ObjectRayOriginKHR-
A variable decorated with the
ObjectRayOriginKHRdecoration will specify the origin of the ray being processed, in object space.
ObjectToWorldKHR-
A variable decorated with the
ObjectToWorldKHRdecoration will contain the current object-to-world transformation matrix, which is determined by the instance of the current intersection.
PatchVertices-
Decorating a variable with the
PatchVerticesbuilt-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,PatchVerticesis 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 thePatchVerticesvariable will also differ.
PointCoord-
Decorating a variable with the
PointCoordbuilt-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 withPointCoordcontains an undefined value.
|
Note
Depending on how the point is rasterized, |
PointSize-
Decorating a variable with the
PointSizebuilt-in decoration will make that variable contain the size of point primitives . The value written to the variable decorated withPointSizeby the last pre-rasterization shader stage in the pipeline is used as the framebuffer-space size of points produced by rasterization.
|
Note
When |
Position-
Decorating a variable with the
Positionbuilt-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 withPositionis used in subsequent primitive assembly, clipping, and rasterization operations.
|
Note
When |
PositionPerViewNV-
Decorating a variable with the
PositionPerViewNVbuilt-in decoration will make that variable contain the position of the current vertex, for each view.Elements of the array correspond to views in a multiview subpass, and those elements corresponding to views in the view mask of the subpass the shader is compiled against will be used as the position value for those views. For the final pre-rasterization shader stage in the pipeline, values written to an output variable decorated with
PositionPerViewNVare used in subsequent primitive assembly, clipping, and rasterization operations, as withPosition.PositionPerViewNVoutput in an earlier pre-rasterization shader stage is available as an input in the subsequent pre-rasterization shader stage.If a shader is compiled against a subpass that has the
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVXbit set, then the position values for each view must not differ in any component other than the X component. If the values do differ, one will be chosen in an implementation-dependent manner.
PrimitiveCountNV-
Decorating a variable with the
PrimitiveCountNVdecoration will make that variable contain the primitive count. The primitive count specifies the number of primitives in the output mesh produced by the mesh shader that will be processed by subsequent pipeline stages.
PrimitiveId-
Decorating a variable with the
PrimitiveIdbuilt-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
PrimitiveIdare 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 mesh shader if a mesh shader is present, or 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.
In an intersection, any-hit, or closest hit shader, it will contain the index within the geometry of the triangle or bounding box being processed.
|
Note
When the The fragment shader using |
PrimitiveIndicesNV-
Decorating a variable with the
PrimitiveIndicesNVdecoration will make that variable contain the output array of vertex index values. Depending on the output primitive type declared using the execution mode, the indices are split into groups of one (OutputPoints), two (OutputLinesNV), or three (OutputTriangles) indices and each group generates a primitive.
PrimitivePointIndicesEXT-
Decorating a variable with the
PrimitivePointIndicesEXTdecoration will make that variable contain the output array of vertex index values for point primitives.
PrimitiveLineIndicesEXT-
Decorating a variable with the
PrimitiveLineIndicesEXTdecoration will make that variable contain the output array of vertex index values for line primitives.
PrimitiveTriangleIndicesEXT-
Decorating a variable with the
PrimitiveTriangleIndicesEXTdecoration will make that variable contain the output array of vertex index values for triangle primitives.
PrimitiveShadingRateKHR-
Decorating a variable with the
PrimitiveShadingRateKHRbuilt-in decoration will make that variable contain the primitive fragment shading rate.The value written to the variable decorated with
PrimitiveShadingRateKHRby the last pre-rasterization shader stage in the pipeline is used as the primitive fragment shading rate. Outputs in previous shader stages are ignored.If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with
PrimitiveShadingRateKHR, then it is as if the shader specified a fragment shading rate value of 0, indicating a horizontal and vertical rate of 1 pixel.If a shader has
PrimitiveShadingRateKHRin the output interface and there is an execution path through the shader that does not write to it, its value is undefined for executions of the shader that take that path.
RayGeometryIndexKHR-
A variable decorated with the
RayGeometryIndexKHRdecoration will contain the geometry index for the acceleration structure geometry currently being shaded.
RayTmaxKHR-
A variable decorated with the
RayTmaxKHRdecoration will contain the parametric tmax value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. The value is initialized to the parameter passed intoOpTraceRayKHR.The tmax value changes throughout the lifetime of the ray that produced the intersection. In the closest hit shader, the value reflects the closest distance to the intersected primitive. In the any-hit shader, it reflects the distance to the primitive currently being intersected. In the intersection shader, it reflects the distance to the closest primitive intersected so far or the initial value. The value can change in the intersection shader after calling
OpReportIntersectionKHRif the corresponding any-hit shader does not ignore the intersection. In a miss shader, the value is identical to the parameter passed intoOpTraceRayKHR.
RayTminKHR-
A variable decorated with the
RayTminKHRdecoration will contain the parametric tmin value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. The value is the parameter passed intoOpTraceRayKHR.The tmin value remains constant for the duration of the ray query.
SampleId-
Decorating a variable with the
SampleIdbuilt-in decoration will make that variable contain the coverage index for the current fragment shader invocation.SampleIdranges 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 withSampleId, Sample Shading is considered enabled with aminSampleShadingvalue of 1.0.
SampleMask-
Decorating a variable with the
SampleMaskbuilt-in decoration will make any variable contain the sample mask for the current fragment shader invocation.A variable in the
Inputstorage class decorated withSampleMaskwill 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
Outputstorage class decorated withSampleMaskis an array of integers forming a bit array in a manner similar to an input variable decorated withSampleMask, but where each bit represents coverage as computed by the shader. This computedSampleMaskis combined with the generated coverage mask in the multisample coverage operation.Variables decorated with
SampleMaskmust 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 withSampleMask, the sample mask has no effect on the processing of a fragment.
SamplePosition-
Decorating a variable with the
SamplePositionbuilt-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 the render pass has a fragment density map attachment, the variable will instead contain the sub-fragment position of the sample being shaded. The top left of the fragment is considered to be at coordinate (0,0) and the bottom right of the fragment is considered to be at coordinate (1,1) for any fragment area.
If a fragment shader entry point’s interface includes an input variable decorated with
SamplePosition, Sample Shading is considered enabled with aminSampleShadingvalue of 1.0.If the current pipeline uses custom sample locations the value of any variable decorated with the
SamplePositionbuilt-in decoration is undefined.
ShadingRateKHR-
Decorating a variable with the
ShadingRateKHRbuilt-in decoration will make that variable contain the fragment shading rate for the current fragment invocation.
SMCountNV-
Decorating a variable with the
SMCountNVbuilt-in decoration will make that variable contain the number of SMs on the device.
SMIDNV-
Decorating a variable with the
SMIDNVbuilt-in decoration will make that variable contain the ID of the SM on which the current shader invocation is running. This variable is in the range [0,SMCountNV-1].
SubgroupId-
Decorating a variable with the
SubgroupIdbuilt-in decoration will make that variable contain the index of the subgroup within the local workgroup. This variable is in range [0,NumSubgroups-1].
SubgroupEqMask-
Decorating a variable with the
SubgroupEqMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bit corresponding to theSubgroupLocalInvocationIdis set in the variable decorated withSubgroupEqMask. All other bits are set to zero.SubgroupEqMaskKHRis an alias ofSubgroupEqMask.
SubgroupGeMask-
Decorating a variable with the
SubgroupGeMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater than or equal toSubgroupLocalInvocationIdthroughSubgroupSize-1 are set in the variable decorated withSubgroupGeMask. All other bits are set to zero.SubgroupGeMaskKHRis an alias ofSubgroupGeMask.
SubgroupGtMask-
Decorating a variable with the
SubgroupGtMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater thanSubgroupLocalInvocationIdthroughSubgroupSize-1 are set in the variable decorated withSubgroupGtMask. All other bits are set to zero.SubgroupGtMaskKHRis an alias ofSubgroupGtMask.
SubgroupLeMask-
Decorating a variable with the
SubgroupLeMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less than or equal toSubgroupLocalInvocationIdare set in the variable decorated withSubgroupLeMask. All other bits are set to zero.SubgroupLeMaskKHRis an alias ofSubgroupLeMask.
SubgroupLtMask-
Decorating a variable with the
SubgroupLtMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less thanSubgroupLocalInvocationIdare set in the variable decorated withSubgroupLtMask. All other bits are set to zero.SubgroupLtMaskKHRis an alias ofSubgroupLtMask.
SubgroupLocalInvocationId-
Decorating a variable with the
SubgroupLocalInvocationIdbuiltin 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_BITis specified, or ifmoduledeclares SPIR-V version 1.6 or higher, and the local workgroup size in the X dimension of thestageis a multiple ofSubgroupSize, 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 withSubgroupLocalInvocationIdfor each value in range [0,SubgroupSize-1].
|
Note
There is no direct relationship between index = 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
|
SubgroupSize-
Decorating a variable with the
SubgroupSizebuiltin 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_BITflag set, or the SPIR-Vmoduleis at least version 1.6, theSubgroupSizedecorated variable will contain the subgroup size for each subgroup that gets dispatched. This value must be betweenminSubgroupSizeandmaxSubgroupSizeand 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,SubgroupSizemust be uniform with command scope.If the pipeline was created with a chained VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure, the
SubgroupSizedecorated variable will matchrequiredSubgroupSize.If SPIR-V
moduleis less than version 1.6 and the pipeline was not created with theVK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure was chained, the variable decorated withSubgroupSizewill matchsubgroupSize.The maximum number of invocations that an implementation can support per subgroup is 128.
|
Note
The old behavior for |
TaskCountNV-
Decorating a variable with the
TaskCountNVdecoration will make that variable contain the task count. The task count specifies the number of subsequent mesh shader workgroups that get generated upon completion of the task shader.
TessCoord-
Decorating a variable with the
TessCoordbuilt-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 ofQuadsorIsoLines, the third component is always zero.
TessLevelOuter-
Decorating a variable with the
TessLevelOuterbuilt-in decoration will make that variable contain the outer tessellation levels for the current patch.In tessellation control shaders, the variable decorated with
TessLevelOutercan 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
TessLevelOutercan read the values written by the tessellation control shader.
TessLevelInner-
Decorating a variable with the
TessLevelInnerbuilt-in decoration will make that variable contain the inner tessellation levels for the current patch.In tessellation control shaders, the variable decorated with
TessLevelInnercan 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
TessLevelInnercan read the values written by the tessellation control shader.
VertexCountHUAWEI-
The
VertexCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this non-indexed mode specific variable will contain an integer value that specifies the number of vertices in a cluster to draw.
VertexIndex-
Decorating a variable with the
VertexIndexbuilt-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 thefirstVertexparameter to vkCmdDraw or thefirstVertexmember 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 thevertexOffsetparameter to vkCmdDrawIndexed or thevertexOffsetmember of the structure consumed by vkCmdDrawIndexedIndirect.
|
Note
|
VertexOffsetHUAWEI-
The
VertexOffsetHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies a offset value added to the vertex index of a cluster before indexing into the vertex buffer.
ViewIndex-
The
ViewIndexdecoration 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.
ViewportIndex-
Decorating a variable with the
ViewportIndexbuilt-in decoration will make that variable contain the index of the viewport.In a mesh, vertex, tessellation evaluation, or geometry shader, the variable decorated with
ViewportIndexcan 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, scissor rectangle, and exclusive scissor rectangle.
The last active pre-rasterization shader stage (in pipeline order) controls the
ViewportIndexthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theViewportIndex.If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with
ViewportIndex, and if multiviewPerViewViewports is not enabled, then the first viewport is used. If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated withViewportIndex, it must write the same value toViewportIndexfor all output vertices of a given primitive.In a fragment shader, the variable decorated with
ViewportIndexcontains the viewport index of the primitive that the fragment invocation belongs to.If
multiviewPerViewViewportsis enabled, and if the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated withViewportIndex, then the value ofViewIndexis used as an index to select the viewport transform and scissor rectangle, and the value ofViewportIndexin the fragment shader is undefined:.
ViewportMaskNV-
Decorating a variable with the
ViewportMaskNVbuilt-in decoration will make that variable contain the viewport mask.In a mesh, vertex, tessellation evaluation, or geometry shader, the variable decorated with
ViewportMaskNVcan be written to with the mask of which viewports the primitive produced by that shader will directed.The
ViewportMaskNVvariable must be an array that has ⌈(VkPhysicalDeviceLimits::maxViewports/ 32)⌉ elements. When a shader writes to this variable, bit B of element M controls whether a primitive is emitted to viewport 32 × M + B. The viewports indicated by the mask are used to select the viewport transform, scissor rectangle, and exclusive scissor rectangle that a primitive will be transformed by.The last active pre-rasterization shader stage (in pipeline order) controls the
ViewportMaskNVthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theViewportMaskNV. WhenViewportMaskNVis written by the final pre-rasterization shader stage, any variable decorated withViewportIndexin the fragment shader will have the index of the viewport that was used in generating that fragment.If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated with
ViewportMaskNV, it must write the same value toViewportMaskNVfor all output vertices of a given primitive.
ViewportMaskPerViewNV-
Decorating a variable with the
ViewportMaskPerViewNVbuilt-in decoration will make that variable contain the mask of viewports primitives are broadcast to, for each view.The value written to an element of
ViewportMaskPerViewNVin the last pre-rasterization shader stage is a bitmask indicating which viewports the primitive will be directed to. The primitive will be broadcast to the viewport corresponding to each non-zero bit of the bitmask, and that viewport index is used to select the viewport transform, scissor rectangle, and exclusive scissor rectangle, for each view. The same values must be written to all vertices in a given primitive, or else the set of viewports used for that primitive is undefined.Elements of the array correspond to views in a multiview subpass, and those elements corresponding to views in the view mask of the subpass the shader is compiled against will be used as the viewport mask value for those views.
ViewportMaskPerViewNVoutput in an earlier pre-rasterization shader stage is not available as an input in the subsequent pre-rasterization shader stage.Although
ViewportMaskNVis an array,ViewportMaskPerViewNVis not a two-dimensional array. Instead,ViewportMaskPerViewNVis limited to 32 viewports.
WarpsPerSMNV-
Decorating a variable with the
WarpsPerSMNVbuilt-in decoration will make that variable contain the maximum number of warps executing on a SM.
WarpIDNV-
Decorating a variable with the
WarpIDNVbuilt-in decoration will make that variable contain the ID of the warp on a SM on which the current shader invocation is running. This variable is in the range [0,WarpsPerSMNV-1].
WorkgroupId-
Decorating a variable with the
WorkgroupIdbuilt-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.
WorkgroupSize
|
Note
SPIR-V 1.6 deprecated |
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.
WorldRayDirectionKHR-
A variable decorated with the
WorldRayDirectionKHRdecoration will specify the direction of the ray being processed, in world space. The value is the parameter passed intoOpTraceRayKHR.
WorldRayOriginKHR-
A variable decorated with the
WorldRayOriginKHRdecoration will specify the origin of the ray being processed, in world space. The value is the parameter passed intoOpTraceRayKHR.
WorldToObjectKHR-
A variable decorated with the
WorldToObjectKHRdecoration will contain the current world-to-object transformation matrix, which is determined by the instance of the current intersection.
CoreCountARM-
Decorating a variable with the
CoreCountARMbuilt-in decoration will make that variable contain the number of cores on the device.
CoreMaxIDARM-
Decorating a variable with the
CoreMaxIDARMbuilt-in decoration will make that variable contain the max ID of any shader core on the device on which the current shader invocation is running.
CoreIDARM-
Decorating a variable with the
CoreIDARMbuilt-in decoration will make that variable contain the ID of the core on which the current shader invocation is running. This variable is in the range [0,CoreMaxIDARM].
WarpMaxIDARM-
Decorating a variable with the
WarpMaxIDARMbuilt-in decoration will make that variable contain the maximum warp ID for the core on which the current invocation is running.
WarpIDARM-
Decorating a variable with the
WarpIDARMbuilt-in decoration will make that variable contain the ID of the warp on a core on which the current shader invocation is running. This variable is in the range [0,WarpMaxIDARM].