Google Git
Sign in
android / platform / hardware / google / gfxstream / 21aecd177abcd24856862f51245dc2d3f1d02d3a / . / codegen / vulkan / vulkan-docs-next / chapters / interfaces.adoc
blob: 495afd8988d7f8da9560c61bffba5a192ed92e7c [file] [log] [blame]
// Copyright 2015-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0
[[interfaces]]
= Shader Interfaces
When a pipeline is created, the set of shaders specified in the
corresponding stext:VkPipelineCreateInfo structure are implicitly linked at
a number of different interfaces.
* <<interfaces-iointerfaces,Shader Input and Output Interface>>
* <<interfaces-vertexinput,Vertex Input Interface>>
* <<interfaces-fragmentoutput,Fragment Output Interface>>
ifdef::VK_EXT_shader_tile_image[]
* <<interfaces-fragmenttileimage,Fragment Tile Image Interface>>
endif::VK_EXT_shader_tile_image[]
* <<interfaces-inputattachment,Fragment Input Attachment Interface>>
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
* <<interfaces-raypipeline, Ray Tracing Pipeline Interface>>
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
* <<interfaces-resources,Shader Resource Interface>>
ifdef::VK_NV_geometry_shader_passthrough[]
* <<geometry-passthrough-passthrough,Geometry Shader Passthrough>>
endif::VK_NV_geometry_shader_passthrough[]
ifdef::VKSC_VERSION_1_0[]
In Vulkan SC, the pipeline compilation process occurs
<<pipelines-offline-compilation,offline>> using the implementation-provided
pipeline cache compiler.
The set of shaders being used to create a pipeline can: be specified using
the pipeline JSON schema.
endif::VKSC_VERSION_1_0[]
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: code:Block,
code:BufferBlock, code:Offset, code:ArrayStride, and code:MatrixStride can
also decorate types and type members used by variables in the code:Private
and code:Function storage classes.
[NOTE]
.Note
====
In this chapter, there are references to SPIR-V terms such as the
code: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.
====
[[interfaces-iointerfaces]]
== 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 code:OpEntryPoint instruction and are declared
with the code:Input or code: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.
code:Output variables of a shader stage have undefined: values until the
shader writes to them or uses the code:Initializer operand when declaring
the variable.
[[interfaces-iointerfaces-builtin]]
=== Built-in Interface Block
Shader <<interfaces-builtin-variables,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 code:BuiltIn decoration,
* form object types as described in the
<<interfaces-builtin-variables,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
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
, except for the mesh output interface where there must: be at most one
built-in interface block decorated with the code:PerPrimitiveEXT decoration
and at most one built-in interface block without this decoration
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
.
Built-ins must: not have any code:Location or code:Component decorations.
[[interfaces-iointerfaces-user]]
=== User-defined Variable Interface
The non-built-in variables listed by code:OpEntryPoint with the code:Input
or code:Output storage class form the _user-defined variable interface_.
These must: have <<formats-numericformat, numeric type>> or, recursively,
composite types of such types.
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
If an implementation supports <<features-storageInputOutput16,
pname:storageInputOutput16>>, components can: have a width of 16 bits.
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
These variables must: be identified with a code:Location decoration and can:
also be identified with a code:Component decoration.
[[interfaces-iointerfaces-matching]]
=== 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:
ifdef::VK_EXT_transform_feedback[]
** code:XfbBuffer, code:XfbStride, code:Offset, and code:Stream
endif::VK_EXT_transform_feedback[]
** one is not decorated with code:Component and the other is declared with
a code:Component of `0`
** <<shaders-interpolation-decorations,Interpolation decorations>>
** code: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 code:OpTypeArray with an code:Element code:Type equivalent to the
code:OpType* declaration of the output, and neither is a structure
member; or
ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[]
** if the <<features-maintenance4, pname:maintenance4>> feature is
enabled, they are declared as code:OpTypeVector variables, and the
output has a code:Component code:Count value higher than that of the
input but the same code:Component code:Type; or
endif::VK_VERSION_1_3,VK_KHR_maintenance4[]
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
** if the output is declared in a mesh shader as an code:OpTypeArray with
an code:Element code:Type equivalent to the code:OpType* declaration of
the input, and neither is a structure member; or
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
** if the input is decorated with code:PerVertexKHR, and is declared in a
fragment shader as an code:OpTypeArray with an code:Element code:Type
equivalent to the code:OpType* declaration of the output, and neither
the input nor the output is a structure member; or
endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
** if in any other case they are declared with an equivalent code:OpType*
declaration.
* If both are structures and every member has an interface match.
[NOTE]
.Note
====
The word "`structure`" above refers to both variables that have an
code:OpTypeStruct type and interface blocks (which are also declared as
code:OpTypeStruct).
====
ifdef::VK_EXT_graphics_pipeline_library[]
If the pipeline is compiled as separate graphics pipeline libraries and the
<<limits-graphicsPipelineLibraryIndependentInterpolationDecoration,
pname:graphicsPipelineLibraryIndependentInterpolationDecoration>> limit is
not supported, matches are not found if the
<<shaders-interpolation-decorations, interpolation decorations>> differ
between the last <<pipelines-graphics-subsets-pre-rasterization,
pre-rasterization shader stage>> and the fragment shader stage.
endif::VK_EXT_graphics_pipeline_library[]
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.
ifdef::VK_NV_geometry_shader_passthrough[]
Matching rules for _passthrough geometry shaders_ are slightly different and
are described in the <<geometry-passthrough-interface,Passthrough Interface
Matching>> section.
endif::VK_NV_geometry_shader_passthrough[]
The value of an input variable is undefined: if the preceding stage does not
write to a matching output variable, as described above.
[[interfaces-iointerfaces-locations]]
=== Location Assignment
This section describes code:Location assignments for user-defined variables
and how many code:Location slots are consumed by a given user-variable type.
<<interfaces-iointerfaces-matching, 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
code:Location slots the type consumes.
The code:Location value specifies an interface slot comprised of a 32-bit
four-component vector conveyed between stages.
The code:Component specifies <<interfaces-iointerfaces-components, word
components>> within these vector code:Location slots.
Only types with widths of
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
16,
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
32 or 64 are supported in shader interfaces.
Inputs and outputs of the following types consume a single interface
code:Location:
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
* 16-bit scalar and vector types, and
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
* 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
code:Location slots.
If a declared input or output is an array of size _n_ and each element takes
_m_ code:Location slots, it will be assigned _m_ {times} _n_ consecutive
code:Location slots starting with the specified code:Location.
If the declared input or output is an _n_ {times} _m_
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
16-,
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
32- or 64-bit matrix, it will be assigned multiple code:Location slots
starting with the specified code:Location.
The number of code:Location slots assigned for each matrix will be the same
as for an _n_-element array of _m_-component vectors.
An code:OpVariable with a structure type that is not a block must: be
decorated with a code:Location.
When an code:OpVariable with a structure type (either block or non-block) is
decorated with a code:Location, the members in the structure type must: not
be decorated with a code:Location.
The code:OpVariable's members are assigned consecutive code:Location slots
in declaration order, starting from the first member, which is assigned the
code:Location decoration from the code:OpVariable.
When a block-type code:OpVariable is declared without a code:Location
decoration, each member in its structure type must: be decorated with a
code:Location.
Types nested deeper than the top-level members must: not have code:Location
decorations.
The code: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 code:OpEntryPoint must: not be
assigned the same code:Location slot and code:Component word, either
explicitly or implicitly.
Any two outputs listed as operands on the same code:OpEntryPoint must: not
be assigned the same code:Location slot and code:Component word, either
explicitly or implicitly.
The number of input and output code:Location slots available for a shader
input or output interface is limited, and dependent on the shader stage as
described in <<interfaces-iointerfaces-limits>>.
All variables in both the <<interfaces-builtin-variables,built-in interface
block>> and the <<interfaces-iointerfaces-user,user-defined variable
interface>> count against these limits.
Each effective code:Location must: have a value less than the number of
code:Location slots available for the given interface, as specified in the
"`Locations Available`" column in <<interfaces-iointerfaces-limits>>.
[[interfaces-iointerfaces-limits]]
.Shader Input and Output Locations
[width="90%",cols="<6,<13",options="header"]
|====
| Shader Interface | Locations Available
| vertex input | pname:maxVertexInputAttributes
| vertex output | pname:maxVertexOutputComponents / 4
| tessellation control input | pname:maxTessellationControlPerVertexInputComponents / 4
| tessellation control output | pname:maxTessellationControlPerVertexOutputComponents / 4
| tessellation evaluation input | pname:maxTessellationEvaluationInputComponents / 4
| tessellation evaluation output| pname:maxTessellationEvaluationOutputComponents / 4
| geometry input | pname:maxGeometryInputComponents / 4
| geometry output | pname:maxGeometryOutputComponents / 4
| fragment input | pname:maxFragmentInputComponents / 4
| fragment output | pname:maxFragmentOutputAttachments
ifdef::VK_EXT_mesh_shader[]
| mesh output | pname:maxMeshOutputComponents / 4
endif::VK_EXT_mesh_shader[]
ifndef::VK_EXT_mesh_shader[]
ifdef::VK_NV_mesh_shader[]
// we forgot to add maxMeshOutputComponents
| mesh output | pname:maxFragmentInputComponents / 4
endif::VK_NV_mesh_shader[]
endif::VK_EXT_mesh_shader[]
ifdef::VK_HUAWEI_cluster_culling_shader[]
| cluster culling output | pname:maxOutputClusterCount
endif::VK_HUAWEI_cluster_culling_shader[]
|====
[[interfaces-iointerfaces-components]]
=== Component Assignment
The code:Component decoration allows the code:Location to be more finely
specified for scalars and vectors, down to the individual code:Component
word within a code:Location slot that are consumed.
The code:Component word within a code:Location are 0, 1, 2, and 3.
A variable or block member starting at code:Component N will consume
code:Component words N, N+1, N+2, ...
up through its size.
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
For 16-, and 32-bit types,
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
ifndef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
For single precision types,
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
it is invalid if this sequence of code:Component words gets larger than 3.
A scalar 64-bit type will consume two of these code:Component words in
sequence, and a two-component 64-bit vector type will consume all four
code:Component words available within a code:Location.
A three- or four-component 64-bit vector type must: not specify a non-zero
code:Component decoration.
A three-component 64-bit vector type will consume all four code:Component
words of the first code:Location and code:Component 0 and 1 of the second
code:Location.
This leaves code:Component 2 and 3 available for other component-qualified
declarations.
A scalar or two-component 64-bit data type must: not specify a
code:Component decoration of 1 or 3.
A code: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 code:Component words
of the first code:Location and all four code:Component words of the second
code:Location.
[[interfaces-vertexinput]]
== 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 code:Location and
code:Component decorations to the vertex input attributes specified in the
pname:pVertexInputState member of the slink:VkGraphicsPipelineCreateInfo
structure.
The vertex shader input variables listed by code:OpEntryPoint with the
code:Input storage class form the _vertex input interface_.
These variables must: be identified with a code:Location decoration and can:
also be identified with a code:Component decoration.
For the purposes of interface matching: variables declared without a
code:Component decoration are considered to have a code:Component decoration
of zero.
The number of available vertex input code:Location slots is given by the
pname:maxVertexInputAttributes member of the sname:VkPhysicalDeviceLimits
structure.
See <<fxvertex-attrib-location>> for details.
All vertex shader inputs declared as above must: have a corresponding
attribute and binding in the pipeline.
[[interfaces-fragmentoutput]]
== 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
<<renderpass, render pass instance>>.
The fragment shader output variables are matched by the code:Location and
code:Component decorations to specified color attachments.
The fragment shader output variables listed by code:OpEntryPoint with the
code:Output storage class form the _fragment output interface_.
These variables must: be identified with a code:Location decoration.
They can: also be identified with a code:Component decoration and/or an
code:Index decoration.
For the purposes of interface matching: variables declared without a
code:Component decoration are considered to have a code:Component decoration
of zero, and variables declared without an code:Index decoration are
considered to have an code:Index decoration of zero.
A fragment shader output variable identified with a code:Location decoration
of _i_ is associated with
ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
the color attachment indicated by
slink:VkRenderingInfo::pname:pColorAttachments[_i_].
When using render pass objects, it is associated with
endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
the color attachment indicated by
slink:VkSubpassDescription::pname:pColorAttachments[_i_].
Values are written to those attachments after passing through the blending
unit as described in <<framebuffer-blending>>, if enabled.
Locations are consumed as described in
<<interfaces-iointerfaces-locations,Location Assignment>>.
The number of available fragment output code:Location slots is given by the
pname:maxFragmentOutputAttachments member of the
sname: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
<<interfaces-iointerfaces-components,Component Assignment>>.
Output code: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 code:Location, they must: have
the same underlying type (floating-point or integer).
code: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 code:Index of zero are directed to the
first input of the blending unit associated with the corresponding
code:Location.
Outputs identified with an code:Index of one are directed to the second
input of the corresponding blending unit.
There must: be no output variable which has the same code:Location,
code:Component, and code:Index as any other, either explicitly declared or
implied.
Output values written by a fragment shader must: be declared with either
code:OpTypeFloat or code:OpTypeInt, and a code:Width of 32.
ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[]
If pname:storageInputOutput16 is supported, output values written by a
fragment shader can: be also declared with either code:OpTypeFloat or
code:OpTypeInt and a code:Width of 16.
endif::VK_VERSION_1_1,VK_KHR_16bit_storage[]
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 <<fundamentals-fpfixedconv>>; 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.
ifdef::VK_EXT_legacy_dithering[]
[[interfaces-legacy-dithering]]
== Legacy Dithering
The application can: enable dithering to be applied to the color output of a
subpass, by using the
ename:VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT
ifndef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
flag.
endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
or the ename:VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT flags.
endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[]
When dithering is enabled, the implementation may: modify the output color
value [eq]#c# by one ULP.
This modification must: only depend on the framebuffer coordinates
[eq]#(x~f~,y~f~)# of the sample, as well as on the value of [eq]#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]
.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.
====
endif::VK_EXT_legacy_dithering[]
ifdef::VK_EXT_shader_tile_image[]
[[interfaces-fragmenttileimage]]
== Fragment Tile Image Interface
When a fragment stage is present in a pipeline, the fragment shader tile
image variables decorated with code:Location form an interface with the
color attachments defined by the render pass instance.
The fragment shader tile image variables are matched by code:Location
decorations to the color attachments specified in the
pname:pColorAttachments array of the slink:VkRenderingInfoKHR structure
describing the render pass instance the fragment shader is executed in.
The fragment shader variables listed by code:OpEntryPoint with the
code:TileImageEXT storage class and a decoration of code:Location form the
_fragment tile image interface_.
These variables must: be declared with a type of code:OpTypeImage, and a
code:Dim operand of code:TileImageDataEXT.
The code:Component decoration is not supported for these variables.
Reading from a tile image variable with a code:Location decoration of _i_
reads from the color attachment identified by the element of
slink:VkRenderingInfoKHR::pname:pColorAttachments with a pname:location
equal to _i_.
If the tile image variable is declared as an array of size N, it consumes N
consecutive tile image locations, starting with the index specified.
There must: not be more than one tile image variable with the same
code:Location whether explicitly declared or implied by an array
declaration.
The number of available tile image locations is the same as the number of
available fragment output locations as given by the
pname:maxFragmentOutputAttachments member of the
sname:VkPhysicalDeviceLimits structure.
The basic data type (floating-point, integer, unsigned integer) of the tile
image variable must: match the basic format of the corresponding color
attachment, or the values read from the tile image variables are undefined:.
endif::VK_EXT_shader_tile_image[]
[[interfaces-inputattachment]]
== 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
code:InputAttachmentIndex decorations to the input attachments specified in
the pname:pInputAttachments array of the slink:VkSubpassDescription
structure describing the subpass that the fragment shader is executed in.
The fragment shader subpass input variables with the code:UniformConstant
storage class and a decoration of code:InputAttachmentIndex that are
statically used by code:OpEntryPoint form the _fragment input attachment
interface_.
These variables must: be declared with a type of code:OpTypeImage, a
code:Dim operand of code:SubpassData, an code:Arrayed operand of 0, and a
code:Sampled operand of 2.
The code:MS operand of the code:OpTypeImage must: be 0 if the pname:samples
field of the corresponding slink:VkAttachmentDescription is
ename:VK_SAMPLE_COUNT_1_BIT and
ifdef::VK_EXT_multisampled_render_to_single_sampled[]
<<subpass-multisampledrendertosinglesampled,multisampled-render-to-single-sampled>>
is not enabled, and
endif::VK_EXT_multisampled_render_to_single_sampled[]
1 otherwise.
A subpass input variable identified with an code:InputAttachmentIndex
decoration of _i_ reads from the input attachment indicated by
pname:pInputAttachments[_i_] member of sname: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
code: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
pname:maxPerStageDescriptorInputAttachments member of the
sname:VkPhysicalDeviceLimits structure.
Variables identified with the code:InputAttachmentIndex must: only be used
by a fragment stage.
The <<formats-numericformat, 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 <<descriptorsets-inputattachment>> for more details.
[[compatibility-inputattachment]]
=== 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 slink:VkImageView in the
slink:VkFramebuffer, except for pname:subresourceRange.aspectMask.
The pname:aspectMask must: be equal to the aspect accessed by the shader.
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-raypipeline]]
== 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.
.Ray Pipeline Shader Interface
[width="90%",options="header"]
|====
| 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
|====
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-resources]]
== Shader Resource Interface
When a shader stage accesses buffer or image resources, as described in the
<<descriptorsets,Resource Descriptors>> section, the shader resource
variables must: be matched with the <<descriptorsets-pipelinelayout,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 code:OpEntryPoint
with a storage class of code:Uniform, code:UniformConstant,
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
code:StorageBuffer,
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
or code:PushConstant.
For the fragment shader, this includes the <<interfaces-inputattachment,
fragment input attachment interface>>.
The shader resource interface consists of two sub-interfaces: the push
constant interface and the descriptor set interface.
[[interfaces-resources-pushconst]]
=== Push Constant Interface
The shader variables defined with a storage class of code:PushConstant that
are statically used by the shader entry points for the pipeline define the
_push constant interface_.
They must: be:
* typed as code:OpTypeStruct,
* identified with a code:Block decoration, and
* laid out explicitly using the code:Offset, code:ArrayStride, and
code:MatrixStride decorations as specified in
<<interfaces-resources-layout,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
code:Offset such that the entire member is entirely contained within the
slink:VkPushConstantRange for each code:OpEntryPoint that uses it, and the
pname:stageFlags for that range must: specify the appropriate
elink:VkShaderStageFlagBits for that stage.
The code:Offset decoration for any member of a push constant block must: not
cause the space required for that member to extend outside the range
[eq]#[0, pname:maxPushConstantsSize)#.
Any member of a push constant block that is declared as an array must: only
be accessed with _dynamically uniform_ indices.
[[interfaces-resources-descset]]
=== Descriptor Set Interface
The _descriptor set interface_ is comprised of the shader variables with the
storage class of
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
code:StorageBuffer,
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
code:Uniform or code:UniformConstant (including the variables in the
<<interfaces-inputattachment,fragment input attachment interface>>) that are
statically used by the shader entry points for the pipeline.
These variables must: have code:DescriptorSet and code:Binding decorations
specified, which are assigned and matched with the
sname:VkDescriptorSetLayout objects in the pipeline layout as described in
<<interfaces-resources-setandbinding,DescriptorSet and Binding Assignment>>.
The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpImageRead,
code:OpImageSparseRead, or code:OpImageWrite operations, except under the
following conditions:
* For code:OpImageWrite, if the image format is listed in the
<<formats-without-shader-storage-format,storage without format>> list
and if the pname:shaderStorageImageWriteWithoutFormat feature is enabled
and the shader module declares the code:StorageImageWriteWithoutFormat
capability.
ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[]
* For code:OpImageWrite, if the image format supports
ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT and the
shader module declares the code:StorageImageWriteWithoutFormat
capability.
endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[]
* For code:OpImageRead or code:OpImageSparseRead, if the image format is
listed in the <<formats-without-shader-storage-format,storage without
format>> list and if the pname:shaderStorageImageReadWithoutFormat
feature is enabled and the shader module declares the
code:StorageImageReadWithoutFormat capability.
ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[]
* For code:OpImageRead or code:OpImageSparseRead, if the image format
supports ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT and
the shader module declares the code:StorageImageReadWithoutFormat
capability.
endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[]
* For code:OpImageRead, if code:Dim is code:SubpassData (indicating a read
from an input attachment).
The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpAtomic* operations.
Variables identified with the code:Uniform storage class are used to access
transparent buffer backed resources.
Such variables must: be:
* typed as code:OpTypeStruct, or an array of this type,
* identified with a code:Block or code:BufferBlock decoration, and
* laid out explicitly using the code:Offset, code:ArrayStride, and
code:MatrixStride decorations as specified in
<<interfaces-resources-layout,Offset and Stride Assignment>>.
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
Variables identified with the code:StorageBuffer storage class are used to
access transparent buffer backed resources.
Such variables must: be:
* typed as code:OpTypeStruct, or an array of this type,
* identified with a code:Block decoration, and
* laid out explicitly using the code:Offset, code:ArrayStride, and
code:MatrixStride decorations as specified in
<<interfaces-resources-layout,Offset and Stride Assignment>>.
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any variable in a code:Block must: not cause
the space required for that variable to extend outside the range [eq]#[0,
pname:maxUniformBufferRange)#.
The code:Offset decoration for any variable in a code:BufferBlock must: not
cause the space required for that variable to extend outside the range
[eq]#[0, pname:maxStorageBufferRange)#.
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
The code:Offset decoration for any member of a code:Block-decorated variable
in the code:Uniform storage class must: not cause the space required for
that variable to extend outside the range [eq]#[0,
pname:maxUniformBufferRange)#.
The code:Offset decoration for any member of a code:Block-decorated variable
in the code:StorageBuffer storage class must: not cause the space required
for that variable to extend outside the range [eq]#[0,
pname:maxStorageBufferRange)#.
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
Variables identified with the code: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 pname:descriptorType of
ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK.
In this case the variable must: be typed as code:OpTypeStruct and cannot: be
aggregated into arrays of that type.
Further, the code:Offset decoration for any member of such a variable must:
not cause the space required for that variable to extend outside the range
[eq]#[0,pname:maxInlineUniformBlockSize)#.
endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
Variables identified with a storage class of code:UniformConstant and a
decoration of code:InputAttachmentIndex must: be declared as described in
<<interfaces-inputattachment,Fragment Input Attachment Interface>>.
SPIR-V variables decorated with a descriptor set and binding that identify a
<<descriptorsets-combinedimagesampler, combined image sampler descriptor>>
can: have a type of code:OpTypeImage, code:OpTypeSampler (code:Sampled=1),
or code: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: pname:shaderStorageImageArrayDynamicIndexing and
code:StorageImageArrayDynamicIndexing
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
** Non-uniform: pname:shaderStorageImageArrayNonUniformIndexing and
code:StorageImageArrayNonUniformIndexing
* Storage texel buffers:
** Dynamically uniform: pname:shaderStorageTexelBufferArrayDynamicIndexing
and code:StorageTexelBufferArrayDynamicIndexing
** Non-uniform: pname:shaderStorageTexelBufferArrayNonUniformIndexing and
code:StorageTexelBufferArrayNonUniformIndexing
* Input attachments:
** Dynamically uniform: pname:shaderInputAttachmentArrayDynamicIndexing
and code:InputAttachmentArrayDynamicIndexing
** Non-uniform: pname:shaderInputAttachmentArrayNonUniformIndexing and
code:InputAttachmentArrayNonUniformIndexing
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
* Sampled images (except uniform texel buffers), samplers and combined
image samplers:
** Dynamically uniform: pname:shaderSampledImageArrayDynamicIndexing and
code:SampledImageArrayDynamicIndexing
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
** Non-uniform: pname:shaderSampledImageArrayNonUniformIndexing and
code:SampledImageArrayNonUniformIndexing
* Uniform texel buffers:
** Dynamically uniform: pname:shaderUniformTexelBufferArrayDynamicIndexing
and code:UniformTexelBufferArrayDynamicIndexing
** Non-uniform: pname:shaderUniformTexelBufferArrayNonUniformIndexing and
code:UniformTexelBufferArrayNonUniformIndexing
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
* Uniform buffers:
** Dynamically uniform: pname:shaderUniformBufferArrayDynamicIndexing and
code:UniformBufferArrayDynamicIndexing
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
** Non-uniform: pname:shaderUniformBufferArrayNonUniformIndexing and
code:UniformBufferArrayNonUniformIndexing
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
* Storage buffers:
** Dynamically uniform: pname:shaderStorageBufferArrayDynamicIndexing and
code:StorageBufferArrayDynamicIndexing
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
** Non-uniform: pname:shaderStorageBufferArrayNonUniformIndexing and
code:StorageBufferArrayNonUniformIndexing
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
* Acceleration structures:
** Dynamically uniform: Always supported.
** Non-uniform: Always supported.
endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
ifdef::VK_QCOM_image_processing[]
* <<descriptorsets-weightimage,weight image>>:
** Dynamically uniform: Always supported.
** Non-uniform: Never supported.
* <<descriptorsets-blockmatch, Block matching image>>:
** Dynamically uniform: Always supported.
** Non-uniform: Never supported.
endif::VK_QCOM_image_processing[]
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
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.
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
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
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or non-uniform
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
indexing feature must: be enabled and the capability must: be declared.
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If the combined image sampler enables sampler {YCbCr}
ifndef::VK_EXT_fragment_density_map[]
conversion,
endif::VK_EXT_fragment_density_map[]
ifdef::VK_EXT_fragment_density_map[]
conversion or samples a <<samplers-subsamplesampler,subsampled image>>,
endif::VK_EXT_fragment_density_map[]
it must: be indexed only by constant integral expressions when aggregated
into arrays in shader code, irrespective of the
pname:shaderSampledImageArrayDynamicIndexing feature.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_EXT_fragment_density_map[]
If the combined image sampler samples a
<<samplers-subsamplesampler,subsampled image>>, it must: be indexed only by
constant integral expressions when aggregated into arrays in shader code,
irrespective of the pname:shaderSampledImageArrayDynamicIndexing feature.
endif::VK_EXT_fragment_density_map[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[interfaces-resources-correspondence]]
.Shader Resource and Descriptor Type Correspondence
[width="90%",cols="<1,<2",options="header"]
|====
| Resource type | Descriptor Type
| sampler | ename:VK_DESCRIPTOR_TYPE_SAMPLER or
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| sampled image | ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| storage image | ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE
| combined image sampler | ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
| uniform texel buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
| storage texel buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
| uniform buffer | ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or
ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
| storage buffer | ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
| input attachment | ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT
ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
| inline uniform block | ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
| acceleration structure |
ifdef::VK_KHR_acceleration_structure[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR]
ifdef::VK_NV_ray_tracing+VK_KHR_acceleration_structure[or]
ifdef::VK_NV_ray_tracing[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV]
endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
ifdef::VK_QCOM_image_processing[]
| weight image | ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM
| block matching image | ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM
endif::VK_QCOM_image_processing[]
|====
[[interfaces-resources-storage-class-correspondence]]
.Shader Resource and Storage Class Correspondence
[width="100%",cols="<21%,<22%,<27%,<30%",options="header"]
|====
| Resource type | Storage Class | Type^1^ | Decoration(s)^2^
| sampler
| code:UniformConstant | code:OpTypeSampler |
| sampled image
| code:UniformConstant | code:OpTypeImage (code:Sampled=1)|
| storage image
| code:UniformConstant | code:OpTypeImage (code:Sampled=2) |
| combined image sampler
| code:UniformConstant | code:OpTypeSampledImage +
code:OpTypeImage (code:Sampled=1) +
code:OpTypeSampler |
| uniform texel buffer
| code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=1) |
| storage texel buffer
| code:UniformConstant | code:OpTypeImage (code:Dim=code:Buffer, code:Sampled=2) |
| uniform buffer
| code:Uniform | code:OpTypeStruct
| code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
ifndef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
| storage buffer
| code:Uniform | code:OpTypeStruct
| code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
.2+<.^| storage buffer
| code:Uniform .2+<.^| code:OpTypeStruct
| code:BufferBlock, code:Offset, (code:ArrayStride), (code:MatrixStride)
| code:StorageBuffer | code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[]
| input attachment
| code:UniformConstant | code:OpTypeImage (code:Dim=code:SubpassData, code:Sampled=2)
| code:InputAttachmentIndex
ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
| inline uniform block
| code:Uniform | code:OpTypeStruct
| code:Block, code:Offset, (code:ArrayStride), (code:MatrixStride)
endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
| acceleration structure
| code:UniformConstant | code:OpTypeAccelerationStructureKHR |
endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
ifdef::VK_QCOM_image_processing[]
| sample weight image
| code:UniformConstant | code:OpTypeImage (code:Depth=0, code:Dim=code:2D, +
code:Arrayed=1, code:MS=0, code:Sampled=1)
| code:WeightTextureQCOM
| block matching image
| code:UniformConstant | code:OpTypeImage (code:Depth=0, code:Dim=code:2D, +
code:Arrayed=0, code:MS=0, code:Sampled=1)
| code:BlockMatchTextureQCOM
endif::VK_QCOM_image_processing[]
|====
1::
Where code:OpTypeImage is referenced, the code:Dim values code:Buffer
and code:Subpassdata are only accepted where they are specifically
referenced.
They do not correspond to resource types where a generic
code:OpTypeImage is specified.
2::
In addition to code:DescriptorSet and code:Binding.
[[interfaces-resources-setandbinding]]
=== DescriptorSet and Binding Assignment
A variable decorated with a code:DescriptorSet decoration of [eq]#s# and a
code:Binding decoration of [eq]#b# indicates that this variable is
associated with the slink:VkDescriptorSetLayoutBinding that has a
pname:binding equal to [eq]#b# in pname:pSetLayouts[_s_] that was specified
in slink:VkPipelineLayoutCreateInfo.
code:DescriptorSet decoration values must: be between zero and
pname:maxBoundDescriptorSets minus one, inclusive.
code:Binding decoration values can: be any 32-bit unsigned integer value, as
described in <<descriptorsets-setlayout>>.
Each descriptor set has its own binding name space.
If the code: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.
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
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 pname:runtimeDescriptorArray feature
must: be enabled and the code:RuntimeDescriptorArray capability must: be
declared.
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
The array must: not be runtime-sized.
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
The index of each element of the array is referred to as the _arrayElement_.
For the purposes of interface matching and descriptor set
<<descriptorsets-updates,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
<<interfaces-resources-limits,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.
ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[]
The ename: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
slink:VkMutableDescriptorTypeListEXT.
If multiple descriptor types in slink:VkMutableDescriptorTypeListEXT map to
the same resource limit, only one descriptor is consumed for purposes of
computing resource limits.
endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[]
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 pname:stageFlags.
However, if a variable assigned to a given code:DescriptorSet and
code: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
pname:stageFlags must: include the appropriate elink: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
<<interfaces-resources-storage-class-correspondence,Shader Resource and
Storage Class Correspondence>>.
The descriptor set layout binding must: be of a corresponding descriptor
type, as defined in <<interfaces-resources-correspondence,Shader Resource
and Descriptor Type Correspondence>>.
[NOTE]
.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
<<shaders-staticuse,statically used>> has an impact.
If any shader variable identifying a resource is
<<shaders-staticuse,statically used>> in a shader, then the underlying
descriptor bound at the declared set and binding must
<<interfaces-resources-correspondence,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 code:Aliased
decorations should be used to avoid data hazards (see
https://registry.khronos.org/spir-v/specs/unified1/SPIRV.html#_a_id_aliasingsection_a_aliasing[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
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER that has multiple
corresponding shader variables in the code:UniformConstant storage class,
where some could be code:OpTypeImage (code:Sampled=1), some could be
code:OpTypeSampler, and some could be code:OpTypeSampledImage.
====
[[interfaces-resources-limits]]
.Shader Resource Limits
[width="80%",cols="<35,<23",options="header"]
|====
| Resources per Stage | Resource Types
.2+<.^| pname:maxPerStageDescriptorSamplers
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindSamplers
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| sampler | combined image sampler
ifndef::VK_QCOM_image_processing[]
.3+<.^| pname:maxPerStageDescriptorSampledImages
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindSampledImages
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| sampled image | combined image sampler | uniform texel buffer
endif::VK_QCOM_image_processing[]
ifdef::VK_QCOM_image_processing[]
.5+<.^| pname:maxPerStageDescriptorSampledImages
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindSampledImages
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| sampled image | combined image sampler | uniform texel buffer +
| sample weight image | block matching image
endif::VK_QCOM_image_processing[]
.2+<.^| pname:maxPerStageDescriptorStorageImages
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindStorageImages
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| storage image | storage texel buffer
.2+<.^| pname:maxPerStageDescriptorUniformBuffers
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| uniform buffer | uniform buffer dynamic
.2+<.^| pname:maxPerStageDescriptorStorageBuffers
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| storage buffer | storage buffer dynamic
| pname:maxPerStageDescriptorInputAttachments
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindInputAttachments
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| input attachment^1^
ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
| pname:maxPerStageDescriptorInlineUniformBlocks
ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
or pname:maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks
endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[]
| inline uniform block
endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[]
ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
|
ifdef::VK_NV_ray_tracing[sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxDescriptorSetAccelerationStructures]
ifdef::VK_NV_ray_tracing+VK_KHR_acceleration_structure[or]
ifdef::VK_KHR_acceleration_structure[]
pname:maxPerStageDescriptorAccelerationStructures or
pname:maxPerStageDescriptorUpdateAfterBindAccelerationStructures
endif::VK_KHR_acceleration_structure[]
| acceleration structure
endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[]
|====
1::
Input attachments can: only be used in the fragment shader stage
[[interfaces-resources-layout]]
=== Offset and Stride Assignment
Certain objects must: be explicitly laid out using the code:Offset,
code:ArrayStride, and code:MatrixStride, as described in
https://registry.khronos.org/spir-v/specs/unified1/SPIRV.html#ShaderValidation[SPIR-V
explicit layout validation rules].
All such layouts also must: conform to the following requirements.
[NOTE]
.Note
====
The numeric order of code:Offset decorations does not need to follow member
declaration order.
====
[[interfaces-alignment-requirements]]
*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 [eq]#C# columns and [eq]#R# rows is
equivalent to a [eq]#C# element array of vectors with [eq]#R#
components.
* A row-major matrix with [eq]#C# columns and [eq]#R# rows is equivalent
to an [eq]#R# element array of vectors with [eq]#C# components.
The _scalar alignment_ of the type of an code:OpTypeStruct member is defined
recursively as follows:
* A scalar of size [eq]#N# has a scalar alignment of [eq]#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 code: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 code:StorageBuffer
storage class, code:StorageBuffer8BitAccess or
code: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 code: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.
ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
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
code:Offset decorations placing its first byte at [eq]#F# and its last
byte at [eq]#L#, where [eq]#floor(F / 16) != floor(L / 16)#.
* It is a vector with total size greater than 16 bytes and has its
code:Offset decorations placing its first byte at a non-integer multiple
of 16.
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
[[interfaces-resources-standard-layout]]
*Standard Buffer Layout*
Every member of an code: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.
ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
. If the code:scalarBlockLayout feature is enabled on the device and the
storage class is code:Uniform, code:StorageBuffer,
ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[]
code:PhysicalStorageBuffer,
endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[]
ifdef::VK_KHR_ray_tracing_pipeline[]
code:ShaderRecordBufferKHR,
endif::VK_KHR_ray_tracing_pipeline[]
or code:PushConstant then every member must: be aligned according to its
scalar alignment.
endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
ifdef::VK_KHR_workgroup_memory_explicit_layout[]
. If the code:workgroupMemoryExplicitLayoutScalarBlockLayout feature is
enabled on the device and the storage class is code:Workgroup then every
member must: be aligned according to its scalar alignment.
endif::VK_KHR_workgroup_memory_explicit_layout[]
ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
. All vectors must: be aligned according to their scalar alignment.
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
ifdef::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[]
. If the pname:uniformBufferStandardLayout feature is not enabled on the
device, then any
endif::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[]
ifndef::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[]
. Any
endif::VK_VERSION_1_2,VK_KHR_uniform_buffer_standard_layout[]
member of an code:OpTypeStruct with a storage class of code:Uniform and
a decoration of code:Block must: be aligned according to its extended
alignment.
. Every other member must: be aligned according to its base alignment.
ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
[NOTE]
.Note
====
Even if scalar alignment is supported, it is generally more performant to
use the _base alignment_.
====
endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
The memory layout must: obey the following rules:
* The code:Offset decoration of any member must: be a multiple of its
alignment.
* Any code:ArrayStride or code:MatrixStride decoration must: be a multiple
of the alignment of the array or matrix as defined above.
ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout,VK_KHR_workgroup_memory_explicit_layout[]
If one of the conditions below applies
ifdef::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
* The storage class is code:Uniform, code:StorageBuffer,
ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[]
code:PhysicalStorageBuffer,
endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[]
ifdef::VK_KHR_ray_tracing_pipeline[]
code:ShaderRecordBufferKHR,
endif::VK_KHR_ray_tracing_pipeline[]
or code:PushConstant, and the code:scalarBlockLayout feature is not
enabled on the device.
endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout[]
ifdef::VK_KHR_workgroup_memory_explicit_layout[]
* The storage class is code:Workgroup, and either the struct member is not
part of a code:Block or the
code:workgroupMemoryExplicitLayoutScalarBlockLayout feature is not
enabled on the device.
endif::VK_KHR_workgroup_memory_explicit_layout[]
* The storage class is any other storage class.
the memory layout must: also obey the following rules:
endif::VK_VERSION_1_2,VK_EXT_scalar_block_layout,VK_KHR_workgroup_memory_explicit_layout[]
ifdef::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
* Vectors must: not improperly straddle, as defined above.
endif::VK_VERSION_1_1,VK_KHR_relaxed_block_layout[]
* The code: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]
.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.
====
[[interfaces-builtin-variables]]
== Built-In Variables
Built-in variables are accessed in shaders by declaring a variable decorated
with a code:BuiltIn SPIR-V decoration.
The meaning of each code: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.
<<interfaces-iointerfaces-matching, 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.
ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
[[interfaces-builtin-variables-barycoordkhr]]
[open,refpage='BaryCoordKHR',desc='Barycentric coordinates of a fragment',type='builtins']
--
:refpage: BaryCoordKHR
code:BaryCoordKHR::
The code:BaryCoordKHR decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordKHR-04154]]
The code:BaryCoordKHR decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordKHR-04155]]
The variable decorated with code:BaryCoordKHR must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordKHR-04156]]
The variable decorated with code:BaryCoordKHR must: be declared as a
three-component vector of 32-bit floating-point values
****
--
endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
ifdef::VK_AMD_shader_explicit_vertex_parameter[]
[open,refpage='BaryCoordNoPerspAMD',desc='Barycentric coordinates of a fragment center in screen-space',type='builtins']
--
:refpage: BaryCoordNoPerspAMD
code:BaryCoordNoPerspAMD::
The code:BaryCoordNoPerspAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordNoPerspAMD-04157]]
The code:BaryCoordNoPerspAMD decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordNoPerspAMD-04158]]
The variable decorated with code:BaryCoordNoPerspAMD must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordNoPerspAMD-04159]]
The variable decorated with code:BaryCoordNoPerspAMD must: be declared
as a two-component vector of 32-bit floating-point values
****
--
endif::VK_AMD_shader_explicit_vertex_parameter[]
ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
[[interfaces-builtin-variables-barycoordnoperspkhr]]
[open,refpage='BaryCoordNoPerspKHR',desc='Barycentric coordinates of a fragment in screen-space',type='builtins']
--
:refpage: BaryCoordNoPerspKHR
code:BaryCoordNoPerspKHR::
The code:BaryCoordNoPerspKHR decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordNoPerspKHR-04160]]
The code:BaryCoordNoPerspKHR decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordNoPerspKHR-04161]]
The variable decorated with code:BaryCoordNoPerspKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordNoPerspKHR-04162]]
The variable decorated with code:BaryCoordNoPerspKHR must: be declared
as a three-component vector of 32-bit floating-point values
****
--
endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
ifdef::VK_AMD_shader_explicit_vertex_parameter[]
[open,refpage='BaryCoordNoPerspCentroidAMD',desc='Barycentric coordinates of a fragment centroid in screen-space',type='builtins']
--
:refpage: BaryCoordNoPerspCentroidAMD
code:BaryCoordNoPerspCentroidAMD::
The code:BaryCoordNoPerspCentroidAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04163]]
The code:BaryCoordNoPerspCentroidAMD decoration must: be used only
within the code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04164]]
The variable decorated with code:BaryCoordNoPerspCentroidAMD must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordNoPerspCentroidAMD-04165]]
The variable decorated with code:BaryCoordNoPerspCentroidAMD must: be
declared as a three-component vector of 32-bit floating-point values
****
--
[open,refpage='BaryCoordNoPerspSampleAMD',desc='Barycentric coordinates of a sample center in screen-space',type='builtins']
--
:refpage: BaryCoordNoPerspSampleAMD
code:BaryCoordNoPerspSampleAMD::
The code:BaryCoordNoPerspSampleAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04166]]
The code:BaryCoordNoPerspSampleAMD decoration must: be used only within
the code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04167]]
The variable decorated with code:BaryCoordNoPerspSampleAMD must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordNoPerspSampleAMD-04168]]
The variable decorated with code:BaryCoordNoPerspSampleAMD must: be
declared as a two-component vector of 32-bit floating-point values
****
--
[open,refpage='BaryCoordPullModelAMD',desc='Inverse barycentric coordinates of a fragment center',type='builtins']
--
:refpage: BaryCoordPullModelAMD
code:BaryCoordPullModelAMD::
The code:BaryCoordPullModelAMD decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordPullModelAMD-04169]]
The code:BaryCoordPullModelAMD decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordPullModelAMD-04170]]
The variable decorated with code:BaryCoordPullModelAMD must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordPullModelAMD-04171]]
The variable decorated with code:BaryCoordPullModelAMD must: be declared
as a three-component vector of 32-bit floating-point values
****
--
[open,refpage='BaryCoordSmoothAMD',desc='Barycentric coordinates of a fragment center',type='builtins']
--
:refpage: BaryCoordSmoothAMD
code:BaryCoordSmoothAMD::
The code:BaryCoordSmoothAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordSmoothAMD-04172]]
The code:BaryCoordSmoothAMD decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordSmoothAMD-04173]]
The variable decorated with code:BaryCoordSmoothAMD must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordSmoothAMD-04174]]
The variable decorated with code:BaryCoordSmoothAMD must: be declared as
a two-component vector of 32-bit floating-point values
****
--
[open,refpage='BaryCoordSmoothCentroidAMD',desc='Barycentric coordinates of a fragment centroid',type='builtins']
--
:refpage: BaryCoordSmoothCentroidAMD
code:BaryCoordSmoothCentroidAMD::
The code:BaryCoordSmoothCentroidAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04175]]
The code:BaryCoordSmoothCentroidAMD decoration must: be used only within
the code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04176]]
The variable decorated with code:BaryCoordSmoothCentroidAMD must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordSmoothCentroidAMD-04177]]
The variable decorated with code:BaryCoordSmoothCentroidAMD must: be
declared as a two-component vector of 32-bit floating-point values
****
--
[open,refpage='BaryCoordSmoothSampleAMD',desc='Barycentric coordinates of a sample center',type='builtins']
--
:refpage: BaryCoordSmoothSampleAMD
code:BaryCoordSmoothSampleAMD::
The code:BaryCoordSmoothSampleAMD decoration 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 {plus} J {plus} K = 1.0.
.Valid Usage
****
* [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04178]]
The code:BaryCoordSmoothSampleAMD decoration must: be used only within
the code:Fragment {ExecutionModel}
* [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04179]]
The variable decorated with code:BaryCoordSmoothSampleAMD must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-BaryCoordSmoothSampleAMD-04180]]
The variable decorated with code:BaryCoordSmoothSampleAMD must: be
declared as a two-component vector of 32-bit floating-point values
****
--
endif::VK_AMD_shader_explicit_vertex_parameter[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-baseinstance]]
[open,refpage='BaseInstance',desc='First instance being rendered',type='builtins']
--
:refpage: BaseInstance
code:BaseInstance::
Decorating a variable with the code: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.
code:BaseInstance is the pname:firstInstance parameter to a _direct drawing
command_ or the pname:firstInstance member of a structure consumed by an
_indirect drawing command_.
.Valid Usage
****
* [[VUID-{refpage}-BaseInstance-04181]]
The code:BaseInstance decoration must: be used only within the
code:Vertex {ExecutionModel}
* [[VUID-{refpage}-BaseInstance-04182]]
The variable decorated with code:BaseInstance must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-BaseInstance-04183]]
The variable decorated with code:BaseInstance must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-basevertex]]
[open,refpage='BaseVertex',desc='First vertex being rendered',type='builtins']
--
:refpage: BaseVertex
code:BaseVertex::
Decorating a variable with the code: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 pname:firstVertex
parameter to a _direct drawing command_ or the pname:firstVertex member of
the structure consumed by an _indirect drawing command_.
For _indexed drawing commands_, this variable is the pname:vertexOffset
parameter to a _direct drawing command_ or the pname:vertexOffset member of
the structure consumed by an _indirect drawing command_.
.Valid Usage
****
* [[VUID-{refpage}-BaseVertex-04184]]
The code:BaseVertex decoration must: be used only within the code:Vertex
{ExecutionModel}
* [[VUID-{refpage}-BaseVertex-04185]]
The variable decorated with code:BaseVertex must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-BaseVertex-04186]]
The variable decorated with code:BaseVertex must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-clipdistance]]
[open,refpage='ClipDistance',desc='Application-specified clip distances',type='builtins']
--
:refpage: ClipDistance
code:ClipDistance::
Decorating a variable with the code:ClipDistance built-in decoration will
make that variable contain the mechanism for controlling user clipping.
code: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]
.Note
====
The array variable decorated with code:ClipDistance is explicitly sized by
the shader.
====
[NOTE]
.Note
====
In the last <<pipelines-graphics-subsets-pre-rasterization,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 code:ClipDistance is then used by a fragment shader, code:ClipDistance
contains these linearly interpolated values.
====
.Valid Usage
****
* [[VUID-{refpage}-ClipDistance-04187]]
The code:ClipDistance decoration must: be used only within the
code:MeshEXT, code:MeshNV, code:Vertex, code:Fragment,
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel}
* [[VUID-{refpage}-ClipDistance-04188]]
The variable decorated with code:ClipDistance within the code:MeshEXT,
code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-ClipDistance-04189]]
The variable decorated with code:ClipDistance within the code:Fragment
{ExecutionModel} must: be declared using the code:Input {StorageClass}
* [[VUID-{refpage}-ClipDistance-04190]]
The variable decorated with code:ClipDistance within the
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: not be declared in a {StorageClass} other than
code:Input or code:Output
* [[VUID-{refpage}-ClipDistance-04191]]
The variable decorated with code:ClipDistance must: be declared as an
array of 32-bit floating-point values
****
--
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-clipdistancepv]]
[open,refpage='ClipDistancePerViewNV',desc='Application-specified clip distances per view',type='builtins']
--
:refpage: ClipDistancePerViewNV
code:ClipDistancePerViewNV::
Decorating a variable with the code:ClipDistancePerViewNV built-in
decoration will make that variable contain the per-view clip distances.
The per-view clip distances have the same semantics as code:ClipDistance.
.Valid Usage
****
* [[VUID-{refpage}-ClipDistancePerViewNV-04192]]
The code:ClipDistancePerViewNV decoration must: be used only within the
code:MeshNV {ExecutionModel}
* [[VUID-{refpage}-ClipDistancePerViewNV-04193]]
The variable decorated with code:ClipDistancePerViewNV must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-ClipDistancePerViewNV-04194]]
The variable decorated with code:ClipDistancePerViewNV must: also be
decorated with the code:PerViewNV decoration
* [[VUID-{refpage}-ClipDistancePerViewNV-04195]]
The variable decorated with code:ClipDistancePerViewNV must: be declared
as a two-dimensional array of 32-bit floating-point values
****
--
endif::VK_NV_mesh_shader[]
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-clusteridhuawei]]
[open,refpage='ClusterIDHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: ClusterIDHUAWEI
code:ClusterIDHUAWEI::
The code:ClusterIDHUAWEI decoration 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, code:ClusterIDHUAWEI will replace
gl_DrawID pass to vertex shader for cluster-related information fetching.
.Valid Usage
****
* [[VUID-{refpage}-ClusterIDHUAWEI-07797]]
The code:ClusterIDHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-ClusterIDHUAWEI-07798]]
The variable decorated with code:ClusterIDHUAWEI must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-culldistance]]
[open,refpage='CullDistance',desc='Application-specified cull distances',type='builtins']
--
:refpage: CullDistance
code:CullDistance::
Decorating a variable with the code: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]
.Note
====
In fragment shaders, the values of the code:CullDistance array are linearly
interpolated across each primitive.
====
[NOTE]
.Note
====
If code:CullDistance decorates an input variable, that variable will contain
the corresponding value from the code:CullDistance decorated output variable
from the previous shader stage.
====
.Valid Usage
****
* [[VUID-{refpage}-CullDistance-04196]]
The code:CullDistance decoration must: be used only within the
code:MeshEXT, code:MeshNV, code:Vertex, code:Fragment,
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel}
* [[VUID-{refpage}-CullDistance-04197]]
The variable decorated with code:CullDistance within the code:MeshEXT,
code:MeshNV or code:Vertex {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-CullDistance-04198]]
The variable decorated with code:CullDistance within the code:Fragment
{ExecutionModel} must: be declared using the code:Input {StorageClass}
* [[VUID-{refpage}-CullDistance-04199]]
The variable decorated with code:CullDistance within the
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: not be declared using a {StorageClass} other than
code:Input or code:Output
* [[VUID-{refpage}-CullDistance-04200]]
The variable decorated with code:CullDistance must: be declared as an
array of 32-bit floating-point values
****
--
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-culldistancepv]]
[open,refpage='CullDistancePerViewNV',desc='Application-specified cull distances per view',type='builtins']
--
:refpage: CullDistancePerViewNV
code:CullDistancePerViewNV::
Decorating a variable with the code:CullDistancePerViewNV built-in
decoration will make that variable contain the per-view cull distances.
The per-view cull distances have the same semantics as code:CullDistance.
.Valid Usage
****
* [[VUID-{refpage}-CullDistancePerViewNV-04201]]
The code:CullDistancePerViewNV decoration must: be used only within the
code:MeshNV {ExecutionModel}
* [[VUID-{refpage}-CullDistancePerViewNV-04202]]
The variable decorated with code:CullDistancePerViewNV must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-CullDistancePerViewNV-04203]]
The variable decorated with code:CullDistancePerViewNV must: also be
decorated with the code:PerViewNV decoration
* [[VUID-{refpage}-CullDistancePerViewNV-04204]]
The variable decorated with code:CullDistancePerViewNV must: be declared
as a two-dimensional array of 32-bit floating-point values
****
--
endif::VK_NV_mesh_shader[]
ifdef::VK_EXT_mesh_shader[]
[[interfaces-builtin-variables-cullprimitive]]
[open,refpage='CullPrimitiveEXT',desc='Application-specified culling state per primitive',type='builtins']
--
:refpage: CullPrimitiveEXT
code:CullPrimitiveEXT::
Decorating a variable with the code:CullPrimitiveEXT built-in decoration
will make that variable contain the culling state of output primitives.
If the per-primitive boolean value is code:true, the primitive will be
culled, if it is code:false it will not be culled.
.Valid Usage
****
* [[VUID-{refpage}-CullPrimitiveEXT-07034]]
The code:CullPrimitiveEXT decoration must: be used only within the
code:MeshEXT {ExecutionModel}
* [[VUID-{refpage}-CullPrimitiveEXT-07035]]
The variable decorated with code:CullPrimitiveEXT must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-CullPrimitiveEXT-07036]]
The variable decorated with code:CullPrimitiveEXT must: be declared as
an array of boolean values
* [[VUID-{refpage}-CullPrimitiveEXT-07037]]
The size of the array decorated with code:CullPrimitiveEXT must: match
the value specified by code:OutputPrimitivesEXT
* [[VUID-{refpage}-CullPrimitiveEXT-07038]]
The variable decorated with code:CullPrimitiveEXT within the
code:MeshEXT {ExecutionModel} must: also be decorated with the
code:PerPrimitiveEXT decoration
****
--
endif::VK_EXT_mesh_shader[]
ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_tracing_maintenance1[]
[[interfaces-builtin-variables-cullmask]]
[open,refpage='CullMaskKHR',desc='OpTrace specified ray cull mask',type='builtins']
--
:refpage: CullMaskKHR
code:CullMaskKHR::
A variable decorated with the code:CullMaskKHR decoration will specify the
cull mask of the ray being processed.
The value is given by the `Cull Mask` parameter passed into one of the
code:OpTrace* instructions.
.Valid Usage
****
* [[VUID-{refpage}-CullMaskKHR-06735]]
The code:CullMaskKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-CullMaskKHR-06736]]
The variable decorated with code:CullMaskKHR must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-CullMaskKHR-06737]]
The variable decorated with code:CullMaskKHR must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_tracing_maintenance1[]
ifdef::VK_NV_ray_tracing_motion_blur[]
[[interfaces-builtin-variables-currentraytime]]
[open,refpage='CurrentRayTimeNV',desc='Time value of a ray intersection',type='builtins']
--
:refpage: CurrentRayTimeNV
code:CurrentRayTimeNV::
A variable decorated with the code:CurrentRayTimeNV decoration contains the
time value passed in to code:OpTraceRayMotionNV which called this shader.
.Valid Usage
****
* [[VUID-{refpage}-CurrentRayTimeNV-04942]]
The code:CurrentRayTimeNV decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-CurrentRayTimeNV-04943]]
The variable decorated with code:CurrentRayTimeNV must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-CurrentRayTimeNV-04944]]
The variable decorated with code:CurrentRayTimeNV must: be declared as a
scalar 32-bit floating-point value
****
--
endif::VK_NV_ray_tracing_motion_blur[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[[interfaces-builtin-variables-deviceindex]]
[open,refpage='DeviceIndex',desc='Index of the device executing the shader',type='builtins']
--
:refpage: DeviceIndex
code:DeviceIndex::
The code: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 latexmath:[[0,max(1,physicalDeviceCount))],
where physicalDeviceCount is the pname:physicalDeviceCount member of
slink:VkDeviceGroupDeviceCreateInfo.
.Valid Usage
****
* [[VUID-{refpage}-DeviceIndex-04205]]
The variable decorated with code:DeviceIndex must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-DeviceIndex-04206]]
The variable decorated with code:DeviceIndex must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
[[interfaces-builtin-variables-drawindex]]
[open,refpage='DrawIndex',desc='Index of the current draw',type='builtins']
--
:refpage: DrawIndex
code:DrawIndex::
Decorating a variable with the code:DrawIndex built-in will make that
variable contain the integer value corresponding to the zero-based index of
the draw that invoked the current
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh, or]
vertex shader invocation.
For _indirect drawing commands_, code:DrawIndex begins at zero and
increments by one for each draw executed.
The number of draws is given by the pname:drawCount parameter.
For _direct drawing commands_,
ifdef::VK_EXT_multi_draw[]
if flink:vkCmdDrawMultiEXT or flink:vkCmdDrawMultiIndexedEXT is used, this
variable contains the integer value corresponding to the zero-based index of
the draw.
Otherwise
endif::VK_EXT_multi_draw[]
code:DrawIndex is always zero.
code:DrawIndex is dynamically uniform.
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
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:.
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
.Valid Usage
****
* [[VUID-{refpage}-DrawIndex-04207]]
The code:DrawIndex decoration must: be used only within the code:Vertex,
code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV {ExecutionModel}
* [[VUID-{refpage}-DrawIndex-04208]]
The variable decorated with code:DrawIndex must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-DrawIndex-04209]]
The variable decorated with code:DrawIndex must: be declared as a scalar
32-bit integer value
****
--
endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[]
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-firstindexhuawei]]
[open,refpage='FirstIndexHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: FirstIndexHUAWEI
code:FirstIndexHUAWEI::
The code:FirstIndexHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-FirstIndexHUAWEI-07799]]
The code:FirstIndexHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-FirstIndexHUAWEI-07800]]
The variable decorated with code:FirstIndexHUAWEI must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-fragcoord]]
[open,refpage='FragCoord',desc='Screen-space coordinate of the fragment center',type='builtins']
--
:refpage: FragCoord
code:FragCoord::
Decorating a variable with the code:FragCoord built-in decoration will make
that variable contain the framebuffer coordinate
latexmath:[(x,y,z,\frac{1}{w})] of the fragment being processed.
The [eq]#(x,y)# coordinate [eq]#(0,0)# is the upper left corner of the upper
left pixel in the framebuffer.
+
When <<primsrast-sampleshading,Sample Shading>> is enabled, the [eq]#x# and
[eq]#y# components of code:FragCoord reflect the location of one of the
samples corresponding to the shader invocation.
+
Otherwise, the [eq]#x# and [eq]#y# components of code:FragCoord reflect the
location of the center of the fragment.
+
The [eq]#z# component of code:FragCoord is the interpolated depth value of
the primitive.
+
The [eq]#w# component is the interpolated latexmath:[\frac{1}{w}].
+
The code:Centroid interpolation decoration is ignored, but allowed, on
code:FragCoord.
.Valid Usage
****
* [[VUID-{refpage}-FragCoord-04210]]
The code:FragCoord decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragCoord-04211]]
The variable decorated with code:FragCoord must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-FragCoord-04212]]
The variable decorated with code:FragCoord must: be declared as a
four-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-fragdepth]]
[open,refpage='FragDepth',desc='Application-specified depth for depth testing',type='builtins']
--
:refpage: FragDepth
code:FragDepth::
To have a shader supply a fragment-depth value, the shader must: declare the
code:DepthReplacing execution mode.
Such a shader's fragment-depth value will come from the variable decorated
with the code: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 <<fragops-shader-depthreplacement, fragment shader depth replacement>>
for details.
.Valid Usage
****
* [[VUID-{refpage}-FragDepth-04213]]
The code:FragDepth decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragDepth-04214]]
The variable decorated with code:FragDepth must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-FragDepth-04215]]
The variable decorated with code:FragDepth must: be declared as a scalar
32-bit floating-point value
* [[VUID-{refpage}-FragDepth-04216]]
If the shader dynamically writes to the variable decorated with
code:FragDepth, the code:DepthReplacing {ExecutionMode} must: be
declared
****
--
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-firstinstancehuawei]]
[open,refpage='FirstInstanceHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: FirstInstanceHUAWEI
code:FirstInstanceHUAWEI::
The code:FirstInstanceHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-FirstInstanceHUAWEI-07801]]
The code:FirstInstanceHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-FirstInstanceHUAWEI-07802]]
The variable decorated with code:FirstInstanceHUAWEI must: be declared
as a scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-firstvertexhuawei]]
[open,refpage='FirstVertexHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: FirstVertexHUAWEI
code:FirstVertexHUAWEI::
The code:FirstVertexHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-FirstVertexHUAWEI-07803]]
The code:FirstVertexHUAWEI decoration must: be used only within the
code:FirstVertexHUAWEI {ExecutionModel}
* [[VUID-{refpage}-FirstVertexHUAWEI-07804]]
The variable decorated with code:FirstVertexHUAWEI must: be declared as
a scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
ifdef::VK_EXT_fragment_density_map[]
[[interfaces-builtin-variables-fraginvocationcount]]
[open,refpage='FragInvocationCountEXT',desc='Number of fragment shader invocations for a fragment',type='builtins']
--
:refpage: FragInvocationCountEXT
code:FragInvocationCountEXT::
Decorating a variable with the code:FragInvocationCountEXT built-in
decoration will make that variable contain the maximum number of fragment
shader invocations for the fragment, as determined by
pname:minSampleShading.
+
If <<primsrast-sampleshading,Sample Shading>> is not enabled,
code:FragInvocationCountEXT will be filled with a value of 1.
.Valid Usage
****
* [[VUID-{refpage}-FragInvocationCountEXT-04217]]
The code:FragInvocationCountEXT decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragInvocationCountEXT-04218]]
The variable decorated with code:FragInvocationCountEXT must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-FragInvocationCountEXT-04219]]
The variable decorated with code:FragInvocationCountEXT must: be
declared as a scalar 32-bit integer value
****
--
endif::VK_EXT_fragment_density_map[]
ifdef::VK_EXT_fragment_density_map[]
[[interfaces-builtin-variables-fragsize]]
[open,refpage='FragSizeEXT',desc='Size of the screen-space area covered by the fragment',type='builtins']
--
:refpage: FragSizeEXT
code:FragSizeEXT::
Decorating a variable with the code:FragSizeEXT built-in decoration will
make that variable contain the dimensions in pixels of the
<<glossary-fragment-area,area>> that the fragment covers for that
invocation.
+
If fragment density map is not enabled, code:FragSizeEXT will be filled with
a value of [eq]#(1,1)#.
.Valid Usage
****
* [[VUID-{refpage}-FragSizeEXT-04220]]
The code:FragSizeEXT decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragSizeEXT-04221]]
The variable decorated with code:FragSizeEXT must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-FragSizeEXT-04222]]
The variable decorated with code:FragSizeEXT must: be declared as a
two-component vector of 32-bit integer values
****
--
endif::VK_EXT_fragment_density_map[]
ifdef::VK_EXT_shader_stencil_export[]
[[interfaces-builtin-variables-fragstencilref]]
[open,refpage='FragStencilRefEXT',desc='Application-specified stencil reference value used in stencil tests',type='builtins']
--
:refpage: FragStencilRefEXT
code:FragStencilRefEXT::
Decorating a variable with the code:FragStencilRefEXT built-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 code:FragStencilRefEXT, a shader must: declare the
code:StencilRefReplacingEXT execution mode.
If a shader declares the code:StencilRefReplacingEXT execution mode and
there is an execution path through the shader that does not set
code:FragStencilRefEXT, 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 code:FragStencilRefEXT are considered for stencil testing,
where *s* is the number of bits in the stencil framebuffer attachment, and
higher order bits are discarded.
+
See <<fragops-shader-stencilrefreplacement, fragment shader stencil
reference replacement>> for more details.
.Valid Usage
****
* [[VUID-{refpage}-FragStencilRefEXT-04223]]
The code:FragStencilRefEXT decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragStencilRefEXT-04224]]
The variable decorated with code:FragStencilRefEXT must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-FragStencilRefEXT-04225]]
The variable decorated with code:FragStencilRefEXT must: be declared as
a scalar integer value
****
--
endif::VK_EXT_shader_stencil_export[]
ifdef::VK_NV_shading_rate_image[]
[open,refpage='FragmentSizeNV',desc='Size of the screen-space area covered by the fragment',type='builtins']
--
:refpage: FragmentSizeNV
code:FragmentSizeNV::
Decorating a variable with the code:FragmentSizeNV built-in decoration will
make that variable contain the width and height of the fragment.
.Valid Usage
****
* [[VUID-{refpage}-FragmentSizeNV-04226]]
The code:FragmentSizeNV decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FragmentSizeNV-04227]]
The variable decorated with code:FragmentSizeNV must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-FragmentSizeNV-04228]]
The variable decorated with code:FragmentSizeNV must: be declared as a
two-component vector of 32-bit integer values
****
--
endif::VK_NV_shading_rate_image[]
[[interfaces-builtin-variables-frontfacing]]
[open,refpage='FrontFacing',desc='Front face determination of a fragment',type='builtins']
--
:refpage: FrontFacing
code:FrontFacing::
Decorating a variable with the code: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 <<primsrast-polygons-basic,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-{refpage}-FrontFacing-04229]]
The code:FrontFacing decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FrontFacing-04230]]
The variable decorated with code:FrontFacing must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-FrontFacing-04231]]
The variable decorated with code:FrontFacing must: be declared as a
boolean value
****
--
ifdef::VK_EXT_conservative_rasterization[]
[[interfaces-builtin-variables-fullycoveredext]]
[open,refpage='FullyCoveredEXT',desc='Indication of whether a fragment is fully covered',type='builtins']
--
:refpage: FullyCoveredEXT
code:FullyCoveredEXT::
Decorating a variable with the code:FullyCoveredEXT built-in decoration will
make that variable indicate whether the <<glossary-fragment-area,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.
.Valid Usage
****
* [[VUID-{refpage}-FullyCoveredEXT-04232]]
The code:FullyCoveredEXT decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-FullyCoveredEXT-04233]]
The variable decorated with code:FullyCoveredEXT must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-FullyCoveredEXT-04234]]
The variable decorated with code:FullyCoveredEXT must: be declared as a
boolean value
ifdef::VK_EXT_post_depth_coverage[]
* [[VUID-{refpage}-conservativeRasterizationPostDepthCoverage-04235]]
If
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativeRasterizationPostDepthCoverage
is not supported the code:PostDepthCoverage {ExecutionMode} must: not be
declared, when a variable with the code:FullyCoveredEXT decoration is
declared
endif::VK_EXT_post_depth_coverage[]
****
--
endif::VK_EXT_conservative_rasterization[]
[[interfaces-builtin-variables-globalinvocationid]]
[open,refpage='GlobalInvocationId',desc='Global invocation ID',type='builtins']
--
:refpage: GlobalInvocationId
code:GlobalInvocationId::
Decorating a variable with the code: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 code:LocalInvocationId.
.Valid Usage
****
* [[VUID-{refpage}-GlobalInvocationId-04236]]
The code:GlobalInvocationId decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-GlobalInvocationId-04237]]
The variable decorated with code:GlobalInvocationId must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-GlobalInvocationId-04238]]
The variable decorated with code:GlobalInvocationId must: be declared as
a three-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-helperinvocation]]
[open,refpage='HelperInvocation',desc='Indication of whether a fragment shader is a helper invocation',type='builtins']
--
:refpage: HelperInvocation
code:HelperInvocation::
Decorating a variable with the code: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]
.Note
====
It is very likely that a helper invocation will have a value of
code:SampleMask fragment shader input value that is zero.
====
.Valid Usage
****
* [[VUID-{refpage}-HelperInvocation-04239]]
The code:HelperInvocation decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-HelperInvocation-04240]]
The variable decorated with code:HelperInvocation must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-HelperInvocation-04241]]
The variable decorated with code:HelperInvocation must: be declared as a
boolean value
****
--
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-hitkind]]
[open,refpage='HitKindKHR',desc='Kind of hit that triggered an any-hit or closest hit ray shader',type='builtins']
--
:refpage: HitKindKHR
code:HitKindKHR::
A variable decorated with the code:HitKindKHR decoration 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 of code:OpReportIntersectionKHR.
For triangle intersection candidates, this will be one of
code:HitKindFrontFacingTriangleKHR or code:HitKindBackFacingTriangleKHR.
.Valid Usage
****
* [[VUID-{refpage}-HitKindKHR-04242]]
The code:HitKindKHR decoration must: be used only within the
code:AnyHitKHR or code:ClosestHitKHR {ExecutionModel}
* [[VUID-{refpage}-HitKindKHR-04243]]
The variable decorated with code:HitKindKHR must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-HitKindKHR-04244]]
The variable decorated with code:HitKindKHR must: be declared as a
scalar 32-bit integer value
****
--
ifdef::VK_NV_ray_tracing[]
[[interfaces-builtin-variables-hitt]]
[open,refpage='HitTNV',desc='T value of a ray intersection',type='builtins']
--
:refpage: HitTNV
code:HitTNV::
A variable decorated with the code:HitTNV decoration is equivalent to a
variable decorated with the code:RayTmaxKHR decoration.
.Valid Usage
****
* [[VUID-{refpage}-HitTNV-04245]]
The code:HitTNV decoration must: be used only within the code:AnyHitNV
or code:ClosestHitNV {ExecutionModel}
* [[VUID-{refpage}-HitTNV-04246]]
The variable decorated with code:HitTNV must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-HitTNV-04247]]
The variable decorated with code:HitTNV must: be declared as a scalar
32-bit floating-point value
****
--
endif::VK_NV_ray_tracing[]
ifdef::VK_KHR_ray_tracing_position_fetch[]
[[interfaces-builtin-variables-hittrianglevertexpositions]]
[open,refpage='HitTriangleVertexPositionsKHR',desc='Vertices of an intersected triangle',type='builtins']
--
:refpage: HitTriangleVertexPositionsKHR
code:HitTriangleVertexPositionsKHR::
A variable decorated with the code:HitTriangleVertexPositionsKHR decoration
will specify the object space vertices of the triangle at the current
intersection in application-provided order.
The positions returned are transformed by the geometry transform, which is
performed at standard <<fundamentals-floatingpoint, floating point>>
precision, but without a specifically defined order of floating point
operations to perform the matrix multiplication.
.Valid Usage
****
* [[VUID-{refpage}-HitTriangleVertexPositionsKHR-08747]]
The code:HitTriangleVertexPositionsKHR decoration must: be used only
within the code:AnyHitKHR or code:ClosestHitKHR {ExecutionModel}
* [[VUID-{refpage}-HitTriangleVertexPositionsKHR-08748]]
The variable decorated with code:HitTriangleVertexPositionsKHR must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-HitTriangleVertexPositionsKHR-08749]]
The variable decorated with code:HitTriangleVertexPositionsKHR must: be
declared as an array of three vectors of three 32-bit float values
* [[VUID-{refpage}-HitTriangleVertexPositionsKHR-08750]]
The variable decorated with code:HitTriangleVertexPositionsKHR must: be
used only if the value of code:HitKindKHR is
code:HitKindFrontFacingTriangleKHR or code:HitKindBackFacingTriangleKHR
* [[VUID-{refpage}-None-08751]]
The acceleration structure corresponding to the current intersection
must: have been built with
ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR
****
--
endif::VK_KHR_ray_tracing_position_fetch[]
[[interfaces-builtin-variables-incomingrayflags]]
[open,refpage='IncomingRayFlagsKHR',desc='Flags used to trace a ray',type='builtins']
--
:refpage: IncomingRayFlagsKHR
code:IncomingRayFlagsKHR::
A variable with the code:IncomingRayFlagsKHR decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-IncomingRayFlagsKHR-04248]]
The code:IncomingRayFlagsKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-IncomingRayFlagsKHR-04249]]
The variable decorated with code:IncomingRayFlagsKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-IncomingRayFlagsKHR-04250]]
The variable decorated with code:IncomingRayFlagsKHR must: be declared
as a scalar 32-bit integer value
****
--
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-indexcounthuawei]]
[open,refpage='IndexCountHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: IndexCountHUAWEI
code:IndexCountHUAWEI::
The code:IndexCountHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-IndexCountHUAWEI-07805]]
The code:IndexCountHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-IndexCountHUAWEI-07806]]
The variable decorated with code:IndexCountHUAWEI must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-instancecounthuawei]]
[open,refpage='InstanceCountHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: InstanceCountHUAWEI
code:InstanceCountHUAWEI::
The code:InstanceCountHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-InstanceCountHUAWEI-07807]]
The code:InstanceCountHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-InstanceCountHUAWEI-07808]]
The variable decorated with code:InstanceCountHUAWEI must: be declared
as a scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-instancecustomindex]]
[open,refpage='InstanceCustomIndexKHR',desc='Custom index associated with an intersected instance',type='builtins']
--
:refpage: InstanceCustomIndexKHR
code:InstanceCustomIndexKHR::
A variable decorated with the code:InstanceCustomIndexKHR decoration will
contain the application-defined value of the instance that intersects the
current ray.
This variable contains the value that was specified in
slink:VkAccelerationStructureInstanceKHR::pname:instanceCustomIndex for the
current acceleration structure instance in the lower 24 bits and the upper 8
bits will be zero.
.Valid Usage
****
* [[VUID-{refpage}-InstanceCustomIndexKHR-04251]]
The code:InstanceCustomIndexKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-InstanceCustomIndexKHR-04252]]
The variable decorated with code:InstanceCustomIndexKHR must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-InstanceCustomIndexKHR-04253]]
The variable decorated with code:InstanceCustomIndexKHR must: be
declared as a scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-instanceid]]
[open,refpage='InstanceId',desc='Id associated with an intersected instance',type='builtins']
--
:refpage: InstanceId
code:InstanceId::
Decorating a variable in an intersection, any-hit, or closest hit shader
with the code:InstanceId decoration will make that variable contain the
index of the instance that intersects the current ray.
.Valid Usage
****
* [[VUID-{refpage}-InstanceId-04254]]
The code:InstanceId decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-InstanceId-04255]]
The variable decorated with code:InstanceId must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-InstanceId-04256]]
The variable decorated with code:InstanceId must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-invocationid]]
[open,refpage='InvocationId',desc='Invocation ID in a geometry or tessellation control shader',type='builtins']
--
:refpage: InvocationId
code:InvocationId::
Decorating a variable with the code: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 <<geometry-invocations,instances>> declared in the
shader minus one.
If the instance count of the geometry shader is one or is not specified,
then code:InvocationId will be zero.
.Valid Usage
****
* [[VUID-{refpage}-InvocationId-04257]]
The code:InvocationId decoration must: be used only within the
code:TessellationControl or code:Geometry {ExecutionModel}
* [[VUID-{refpage}-InvocationId-04258]]
The variable decorated with code:InvocationId must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-InvocationId-04259]]
The variable decorated with code:InvocationId must: be declared as a
scalar 32-bit integer value
****
--
ifdef::VK_NV_shading_rate_image[]
[open,refpage='InvocationsPerPixelNV',desc='Number of fragment shader invocations for the current pixel',type='builtins']
--
:refpage: InvocationsPerPixelNV
code:InvocationsPerPixelNV::
Decorating a variable with the code:InvocationsPerPixelNV built-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 of
code:InvocationsPerPixelNV.
If the shading rate indicates a fragment covering multiple pixels, then
code:InvocationsPerPixelNV will be one.
.Valid Usage
****
* [[VUID-{refpage}-InvocationsPerPixelNV-04260]]
The code:InvocationsPerPixelNV decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-InvocationsPerPixelNV-04261]]
The variable decorated with code:InvocationsPerPixelNV must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-InvocationsPerPixelNV-04262]]
The variable decorated with code:InvocationsPerPixelNV must: be declared
as a scalar 32-bit integer value
****
--
endif::VK_NV_shading_rate_image[]
[[interfaces-builtin-variables-instanceindex]]
[open,refpage='InstanceIndex',desc='Index of an instance',type='builtins']
--
:refpage: InstanceIndex
code:InstanceIndex::
Decorating a variable in a vertex shader with the code:InstanceIndex
built-in decoration will make that variable contain the index of the
instance that is being processed by the current vertex shader invocation.
code:InstanceIndex begins at the pname:firstInstance parameter to
flink:vkCmdDraw or flink:vkCmdDrawIndexed or at the pname:firstInstance
member of a structure consumed by flink:vkCmdDrawIndirect or
flink:vkCmdDrawIndexedIndirect.
.Valid Usage
****
* [[VUID-{refpage}-InstanceIndex-04263]]
The code:InstanceIndex decoration must: be used only within the
code:Vertex {ExecutionModel}
* [[VUID-{refpage}-InstanceIndex-04264]]
The variable decorated with code:InstanceIndex must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-InstanceIndex-04265]]
The variable decorated with code:InstanceIndex must: be declared as a
scalar 32-bit integer value
****
--
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-launchid]]
[open,refpage='LaunchIdKHR',desc='Launch Id for ray shaders',type='builtins']
--
:refpage: LaunchIdKHR
code:LaunchIdKHR::
A variable decorated with the code:LaunchIdKHR decoration will specify the
index of the work item being processed.
One work item is generated for each of the pname:width {times} pname:height
{times} pname:depth items dispatched by a flink:vkCmdTraceRaysKHR command.
All shader invocations inherit the same value for variables decorated with
code:LaunchIdKHR.
.Valid Usage
****
* [[VUID-{refpage}-LaunchIdKHR-04266]]
The code:LaunchIdKHR decoration must: be used only within the
code:RayGenerationKHR, code:IntersectionKHR, code:AnyHitKHR,
code:ClosestHitKHR, code:MissKHR, or code:CallableKHR {ExecutionModel}
* [[VUID-{refpage}-LaunchIdKHR-04267]]
The variable decorated with code:LaunchIdKHR must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-LaunchIdKHR-04268]]
The variable decorated with code:LaunchIdKHR must: be declared as a
three-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-launchsize]]
[open,refpage='LaunchSizeKHR',desc='Launch dimensions for ray shaders',type='builtins']
--
:refpage: LaunchSizeKHR
code:LaunchSizeKHR::
A variable decorated with the code:LaunchSizeKHR decoration will contain the
pname:width, pname:height, and pname:depth dimensions passed to the
flink:vkCmdTraceRaysKHR command that initiated this shader execution.
The pname:width is in the first component, the pname:height is in the second
component, and the pname:depth is in the third component.
.Valid Usage
****
* [[VUID-{refpage}-LaunchSizeKHR-04269]]
The code:LaunchSizeKHR decoration must: be used only within the
code:RayGenerationKHR, code:IntersectionKHR, code:AnyHitKHR,
code:ClosestHitKHR, code:MissKHR, or code:CallableKHR {ExecutionModel}
* [[VUID-{refpage}-LaunchSizeKHR-04270]]
The variable decorated with code:LaunchSizeKHR must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-LaunchSizeKHR-04271]]
The variable decorated with code:LaunchSizeKHR must: be declared as a
three-component vector of 32-bit integer values
****
--
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-layer]]
[open,refpage='Layer',desc='Layer index for layered rendering',type='builtins']
--
:refpage: Layer
code:Layer::
+
[open]
----
Decorating a variable with the code:Layer built-in decoration will make that
variable contain the select layer of a multi-layer framebuffer attachment.
In a
ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,]
vertex, tessellation evaluation, or
endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
geometry shader, any variable decorated with code:Layer can be written with
the framebuffer layer index to which the primitive produced by that shader
will be directed.
ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
The last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> (in pipeline order) controls the code:Layer that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:Layer.
endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
If the last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface does not include a variable decorated
with code:Layer, then the first layer is used.
If a <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface includes a variable decorated with
code:Layer, it must: write the same value to code:Layer for all output
vertices of a given primitive.
If the code: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:.
ifdef::VK_EXT_mesh_shader[]
In a mesh shader this also applies when the code:Layer value is greater than
or equal to the pname:maxMeshOutputLayers limit.
endif::VK_EXT_mesh_shader[]
ifdef::VK_NV_viewport_array2[]
If a variable with the code:Layer decoration is also decorated with
code:ViewportRelativeNV, then the code:ViewportIndex is 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 code:ViewportMaskNV, then the
layer selected has a different value for each viewport a primitive is
rendered to.
endif::VK_NV_viewport_array2[]
In a fragment shader, a variable decorated with code:Layer contains the
layer index of the primitive that the fragment invocation belongs to.
----
.Valid Usage
****
* [[VUID-{refpage}-Layer-04272]]
The code:Layer decoration must: be used only within the code:MeshEXT,
code:MeshNV, code:Vertex, code:TessellationEvaluation, code:Geometry, or
code:Fragment {ExecutionModel}
ifdef::VK_VERSION_1_2[]
* [[VUID-{refpage}-Layer-04273]]
If the <<features-shaderOutputLayer, pname:shaderOutputLayer>> feature
is not enabled then the code:Layer decoration must: be used only within
the code:Geometry or code:Fragment {ExecutionModel}
endif::VK_VERSION_1_2[]
* [[VUID-{refpage}-Layer-04274]]
The variable decorated with code:Layer within the code:MeshEXT,
code:MeshNV, code:Vertex, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: be declared using the code:Output {StorageClass}
* [[VUID-{refpage}-Layer-04275]]
The variable decorated with code:Layer within the code:Fragment
{ExecutionModel} must: be declared using the code:Input {StorageClass}
* [[VUID-{refpage}-Layer-04276]]
The variable decorated with code:Layer must: be declared as a scalar
32-bit integer value
* [[VUID-{refpage}-Layer-07039]]
The variable decorated with code:Layer within the code:MeshEXT
{ExecutionModel} must: also be decorated with the code:PerPrimitiveEXT
decoration
****
--
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-layerpv]]
[open,refpage='LayerPerViewNV',desc='Layer index per view for layered rendering',type='builtins']
--
:refpage: LayerPerViewNV
code:LayerPerViewNV::
Decorating a variable with the code:LayerPerViewNV built-in decoration will
make that variable contain the per-view layer information.
The per-view layer has the same semantics as code:Layer, for each view.
.Valid Usage
****
* [[VUID-{refpage}-LayerPerViewNV-04277]]
The code:LayerPerViewNV decoration must: be used only within the
code:MeshNV {ExecutionModel}
* [[VUID-{refpage}-LayerPerViewNV-04278]]
The variable decorated with code:LayerPerViewNV must: be declared using
the code:Output {StorageClass}
* [[VUID-{refpage}-LayerPerViewNV-04279]]
The variable decorated with code:LayerPerViewNV must: also be decorated
with the code:PerViewNV decoration
* [[VUID-{refpage}-LayerPerViewNV-04280]]
The variable decorated with code:LayerPerViewNV must: be declared as an
array of scalar 32-bit integer values
****
--
endif::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-localinvocationid]]
[open,refpage='LocalInvocationId',desc='Local invocation ID',type='builtins']
--
:refpage: LocalInvocationId
code:LocalInvocationId::
Decorating a variable with the code:LocalInvocationId built-in decoration
will make that variable contain the location of the current
ifdef::VK_HUAWEI_cluster_culling_shader[cluster culling, ]
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[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]
.Note
====
If the size of the workgroup in a particular dimension is one, then the
code:LocalInvocationId in that dimension will be zero.
If the workgroup is effectively two-dimensional, then
code:LocalInvocationId.z will be zero.
If the workgroup is effectively one-dimensional, then both
code:LocalInvocationId.y and code:LocalInvocationId.z will be zero.
====
.Valid Usage
****
* [[VUID-{refpage}-LocalInvocationId-04281]]
The code:LocalInvocationId decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-LocalInvocationId-04282]]
The variable decorated with code:LocalInvocationId must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-LocalInvocationId-04283]]
The variable decorated with code:LocalInvocationId must: be declared as
a three-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-localinvocationindex]]
[open,refpage='LocalInvocationIndex',desc='Linear local invocation index',type='builtins']
--
:refpage: LocalInvocationIndex
code:LocalInvocationIndex::
Decorating a variable with the code:LocalInvocationIndex built-in decoration
will make that variable contain a one-dimensional representation of
code:LocalInvocationId.
This is computed as:
+
[source,c++]
----
LocalInvocationIndex =
LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y +
LocalInvocationId.y * WorkgroupSize.x +
LocalInvocationId.x;
----
.Valid Usage
****
* [[VUID-{refpage}-LocalInvocationIndex-04284]]
The code:LocalInvocationIndex decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-LocalInvocationIndex-04285]]
The variable decorated with code:LocalInvocationIndex must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-LocalInvocationIndex-04286]]
The variable decorated with code:LocalInvocationIndex must: be declared
as a scalar 32-bit integer value
****
--
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-meshviewcount]]
[open,refpage='MeshViewCountNV',desc='Number of views processed by a mesh or task shader',type='builtins']
--
:refpage: MeshViewCountNV
code:MeshViewCountNV::
Decorating a variable with the code:MeshViewCountNV built-in decoration will
make that variable contain the number of views processed by the current mesh
or task shader invocations.
.Valid Usage
****
* [[VUID-{refpage}-MeshViewCountNV-04287]]
The code:MeshViewCountNV decoration must: be used only within the
code:MeshNV or code:TaskNV {ExecutionModel}
* [[VUID-{refpage}-MeshViewCountNV-04288]]
The variable decorated with code:MeshViewCountNV must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-MeshViewCountNV-04289]]
The variable decorated with code:MeshViewCountNV must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-meshviewindices]]
[open,refpage='MeshViewIndicesNV',desc='Indices of views processed by a mesh or task shader',type='builtins']
--
:refpage: MeshViewIndicesNV
code:MeshViewIndicesNV::
Decorating a variable with the code:MeshViewIndicesNV built-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 to
code:MeshViewCountNV are undefined:.
If the value of code:MeshViewIndicesNV[i] is [eq]#j#, then any outputs
decorated with code:PerViewNV will take on the value of array element
[eq]#i# when processing primitives for view index [eq]#j#.
.Valid Usage
****
* [[VUID-{refpage}-MeshViewIndicesNV-04290]]
The code:MeshViewIndicesNV decoration must: be used only within the
code:MeshNV or code:TaskNV {ExecutionModel}
* [[VUID-{refpage}-MeshViewIndicesNV-04291]]
The variable decorated with code:MeshViewIndicesNV must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-MeshViewIndicesNV-04292]]
The variable decorated with code:MeshViewIndicesNV must: be declared as
an array of scalar 32-bit integer values
****
--
endif::VK_NV_mesh_shader[]
ifdef::VK_VERSION_1_1[]
[[interfaces-builtin-variables-numsubgroups]]
[open,refpage='NumSubgroups',desc='Number of subgroups in a workgroup',type='builtins']
--
:refpage: NumSubgroups
code:NumSubgroups::
Decorating a variable with the code:NumSubgroups built-in decoration will
make that variable contain the number of subgroups in the local workgroup.
.Valid Usage
****
* [[VUID-{refpage}-NumSubgroups-04293]]
The code:NumSubgroups decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-NumSubgroups-04294]]
The variable decorated with code:NumSubgroups must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-NumSubgroups-04295]]
The variable decorated with code:NumSubgroups must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_VERSION_1_1[]
[[interfaces-builtin-variables-numworkgroups]]
[open,refpage='NumWorkgroups',desc='Number of workgroups in a dispatch',type='builtins']
--
:refpage: NumWorkgroups
code:NumWorkgroups::
Decorating a variable with the code: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-{refpage}-NumWorkgroups-04296]]
The code:NumWorkgroups decoration must: be used only within the
code:GLCompute, code:MeshEXT, or code:TaskEXT {ExecutionModel}
* [[VUID-{refpage}-NumWorkgroups-04297]]
The variable decorated with code:NumWorkgroups must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-NumWorkgroups-04298]]
The variable decorated with code:NumWorkgroups must: be declared as a
three-component vector of 32-bit integer values
****
--
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-objectraydirection]]
[open,refpage='ObjectRayDirectionKHR',desc='Ray direction in object space',type='builtins']
--
:refpage: ObjectRayDirectionKHR
code:ObjectRayDirectionKHR::
A variable decorated with the code:ObjectRayDirectionKHR decoration will
specify the direction of the ray being processed, in object space.
.Valid Usage
****
* [[VUID-{refpage}-ObjectRayDirectionKHR-04299]]
The code:ObjectRayDirectionKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-ObjectRayDirectionKHR-04300]]
The variable decorated with code:ObjectRayDirectionKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-ObjectRayDirectionKHR-04301]]
The variable decorated with code:ObjectRayDirectionKHR must: be declared
as a three-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-objectrayorigin]]
[open,refpage='ObjectRayOriginKHR',desc='Ray origin in object space',type='builtins']
--
:refpage: ObjectRayOriginKHR
code:ObjectRayOriginKHR::
A variable decorated with the code:ObjectRayOriginKHR decoration will
specify the origin of the ray being processed, in object space.
.Valid Usage
****
* [[VUID-{refpage}-ObjectRayOriginKHR-04302]]
The code:ObjectRayOriginKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-ObjectRayOriginKHR-04303]]
The variable decorated with code:ObjectRayOriginKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-ObjectRayOriginKHR-04304]]
The variable decorated with code:ObjectRayOriginKHR must: be declared as
a three-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-objecttoworld]]
[open,refpage='ObjectToWorldKHR',desc='Transformation matrix from object to world space',type='builtins']
--
:refpage: ObjectToWorldKHR
code:ObjectToWorldKHR::
A variable decorated with the code:ObjectToWorldKHR decoration will contain
the current object-to-world transformation matrix, which is determined by
the instance of the current intersection.
.Valid Usage
****
* [[VUID-{refpage}-ObjectToWorldKHR-04305]]
The code:ObjectToWorldKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-ObjectToWorldKHR-04306]]
The variable decorated with code:ObjectToWorldKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-ObjectToWorldKHR-04307]]
The variable decorated with code:ObjectToWorldKHR must: be declared as a
matrix with four columns of three-component vectors of 32-bit
floating-point values
****
--
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-patchvertices]]
[open,refpage='PatchVertices',desc='Number of vertices in an input patch',type='builtins']
--
:refpage: PatchVertices
code:PatchVertices::
Decorating a variable with the code: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
slink:VkPipelineTessellationStateCreateInfo.
In a Tessellation Evaluation Shader, code: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 code:PatchVertices variable
will also differ.
.Valid Usage
****
* [[VUID-{refpage}-PatchVertices-04308]]
The code:PatchVertices decoration must: be used only within the
code:TessellationControl or code:TessellationEvaluation {ExecutionModel}
* [[VUID-{refpage}-PatchVertices-04309]]
The variable decorated with code:PatchVertices must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-PatchVertices-04310]]
The variable decorated with code:PatchVertices must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-pointcoord]]
[open,refpage='PointCoord',desc='Fragment coordinates in screen-space within a point primitive',type='builtins']
--
:refpage: PointCoord
code:PointCoord::
Decorating a variable with the code: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
<<primsrast-points-basic,Basic Point Rasterization>>.
If the primitive the fragment shader invocation belongs to is not a point,
then the variable decorated with code:PointCoord contains an undefined:
value.
[NOTE]
.Note
====
Depending on how the point is rasterized, code:PointCoord may: never reach
[eq]#(0,0)# or [eq]#(1,1)#.
====
.Valid Usage
****
* [[VUID-{refpage}-PointCoord-04311]]
The code:PointCoord decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-PointCoord-04312]]
The variable decorated with code:PointCoord must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-PointCoord-04313]]
The variable decorated with code:PointCoord must: be declared as a
two-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-pointsize]]
[open,refpage='PointSize',desc='Size of a point primitive',type='builtins']
--
:refpage: PointSize
code:PointSize::
Decorating a variable with the code:PointSize built-in decoration will make
that variable contain the size of point primitives
ifdef::VK_KHR_maintenance5[]
or the final rasterization of polygons if <<primsrast-polygonmode, polygon
mode>> is ename:VK_POLYGON_MODE_POINT when
sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:polygonModePointSize
is set to ename:VK_TRUE
endif::VK_KHR_maintenance5[]
.
The value written to the variable decorated with code:PointSize by the last
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> in the pipeline is used as the framebuffer-space size of points
produced by rasterization.
ifdef::VK_KHR_maintenance5[]
If <<features-maintenance5, pname:maintenance5>> is enabled and a value is
not written to a variable decorated with code:PointSize, a value of 1.0 is
used as the size of points.
endif::VK_KHR_maintenance5[]
[NOTE]
.Note
====
When code:PointSize decorates a variable in the code:Input {StorageClass},
it contains the data written to the output variable decorated with
code:PointSize from the previous shader stage.
====
.Valid Usage
****
* [[VUID-{refpage}-PointSize-04314]]
The code:PointSize decoration must: be used only within the
code:MeshEXT, code:MeshNV, code:Vertex, code:TessellationControl,
code:TessellationEvaluation, or code:Geometry {ExecutionModel}
* [[VUID-{refpage}-PointSize-04315]]
The variable decorated with code:PointSize within the code:MeshEXT,
code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-PointSize-04316]]
The variable decorated with code:PointSize within the
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: not be declared using a {StorageClass} other than
code:Input or code:Output
* [[VUID-{refpage}-PointSize-04317]]
The variable decorated with code:PointSize must: be declared as a scalar
32-bit floating-point value
****
--
[[interfaces-builtin-variables-position]]
[open,refpage='Position',desc='Vertex position',type='builtins']
--
:refpage: Position
code:Position::
Decorating a variable with the code:Position built-in decoration will make
that variable contain the position of the current vertex.
In the last <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization
shader stage>>, the value of the variable decorated with code:Position is
used in subsequent primitive assembly, clipping, and rasterization
operations.
[NOTE]
.Note
====
When code:Position decorates a variable in the code:Input {StorageClass}, it
contains the data written to the output variable decorated with
code:Position from the previous shader stage.
====
.Valid Usage
****
* [[VUID-{refpage}-Position-04318]]
The code:Position decoration must: be used only within the code:MeshEXT,
code:MeshNV, code:Vertex, code:TessellationControl,
code:TessellationEvaluation, or code:Geometry {ExecutionModel}
* [[VUID-{refpage}-Position-04319]]
The variable decorated with code:Position within the code:MeshEXT,
code:MeshNV, or code:Vertex {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-Position-04320]]
The variable decorated with code:Position within the
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: not be declared using a {StorageClass} other than
code:Input or code:Output
* [[VUID-{refpage}-Position-04321]]
The variable decorated with code:Position must: be declared as a
four-component vector of 32-bit floating-point values
****
--
ifdef::VK_NVX_multiview_per_view_attributes[]
[[interfaces-builtin-variables-positionperview]]
[open,refpage='PositionPerViewNV',desc='Vertex position per view',type='builtins']
--
:refpage: PositionPerViewNV
code:PositionPerViewNV::
Decorating a variable with the code:PositionPerViewNV built-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
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> in the pipeline, values written to an output variable decorated with
code:PositionPerViewNV are used in subsequent primitive assembly, clipping,
and rasterization operations, as with code:Position.
code:PositionPerViewNV output in an earlier
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> is available as an input in the subsequent
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>.
+
If a shader is compiled against a subpass that has the
ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX bit 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.
.Valid Usage
****
* [[VUID-{refpage}-PositionPerViewNV-04322]]
The code:PositionPerViewNV decoration must: be used only within the
code:MeshNV, code:Vertex, code:TessellationControl,
code:TessellationEvaluation, or code:Geometry {ExecutionModel}
* [[VUID-{refpage}-PositionPerViewNV-04323]]
The variable decorated with code:PositionPerViewNV within the
code:Vertex, or code:MeshNV {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-PositionPerViewNV-04324]]
The variable decorated with code:PositionPerViewNV within the
code:TessellationControl, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: not be declared using a {StorageClass} other than
code:Input or code:Output
* [[VUID-{refpage}-PositionPerViewNV-04325]]
The variable decorated with code:PositionPerViewNV must: be declared as
an array of four-component vector of 32-bit floating-point values with
at least as many elements as the maximum view in the subpass's view mask
plus one
* [[VUID-{refpage}-PositionPerViewNV-04326]]
The array variable decorated with code:PositionPerViewNV must: only be
indexed by a constant or specialization constant
****
--
endif::VK_NVX_multiview_per_view_attributes[]
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-primitivecount]]
[open,refpage='PrimitiveCountNV',desc='Number of primitives output by a mesh shader',type='builtins']
--
:refpage: PrimitiveCountNV
code:PrimitiveCountNV::
+
Decorating a variable with the code:PrimitiveCountNV decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveCountNV-04327]]
The code:PrimitiveCountNV decoration must: be used only within the
code:MeshNV {ExecutionModel}
* [[VUID-{refpage}-PrimitiveCountNV-04328]]
The variable decorated with code:PrimitiveCountNV must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitiveCountNV-04329]]
The variable decorated with code:PrimitiveCountNV must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-primitiveid]]
[open,refpage='PrimitiveId',desc='Primitive ID',type='builtins']
--
:refpage: PrimitiveId
code:PrimitiveId::
Decorating a variable with the code: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 <<primsrast-polygonmode,
Polygon Mode>>), the primitive index is incremented only once, even if
multiple points or lines are eventually drawn.
+
Variables decorated with code: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 code: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
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
mesh shader if a mesh shader is present, or the primitive index written by
the
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
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.
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
+
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.
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[NOTE]
.Note
====
When the code:PrimitiveId decoration is applied to an output variable in the
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh shader or]
geometry shader, the resulting value is seen through the code:PrimitiveId
decorated input variable in the fragment shader.
The fragment shader using code:PrimitiveId will need to declare either the
ifdef::VK_NV_mesh_shader[code:MeshShadingNV,]
ifdef::VK_EXT_mesh_shader[code:MeshShadingEXT,]
code:Geometry or code:Tessellation capability to satisfy the requirement
SPIR-V has to use code:PrimitiveId.
====
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveId-04330]]
The code:PrimitiveId decoration must: be used only within the
code:MeshEXT, code:MeshNV, code:IntersectionKHR, code:AnyHitKHR,
code:ClosestHitKHR, code:TessellationControl,
code:TessellationEvaluation, code:Geometry, or code:Fragment
{ExecutionModel}
* [[VUID-{refpage}-Fragment-04331]]
If pipeline contains both the code:Fragment and code:Geometry
{ExecutionModel} and a variable decorated with code:PrimitiveId is read
from code:Fragment shader, then the code:Geometry shader must: write to
the output variables decorated with code:PrimitiveId in all execution
paths
* [[VUID-{refpage}-Fragment-04332]]
If pipeline contains both the code:Fragment and code:MeshEXT or
code:MeshNV {ExecutionModel} and a variable decorated with
code:PrimitiveId is read from code:Fragment shader, then the
code:MeshEXT or code:MeshNV shader must: write to the output variables
decorated with code:PrimitiveId in all execution paths
* [[VUID-{refpage}-Fragment-04333]]
If code:Fragment {ExecutionModel} contains a variable decorated with
code:PrimitiveId, then either the code:MeshShadingEXT,
code:MeshShadingNV, code:Geometry or code:Tessellation capability must:
also be declared
* [[VUID-{refpage}-PrimitiveId-04334]]
The variable decorated with code:PrimitiveId within the
code:TessellationControl, code:TessellationEvaluation, code:Fragment,
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel} must: be declared using the code:Input {StorageClass}
* [[VUID-{refpage}-PrimitiveId-04335]]
The variable decorated with code:PrimitiveId within the code:Geometry
{ExecutionModel} must: be declared using the code:Input or code:Output
{StorageClass}
* [[VUID-{refpage}-PrimitiveId-04336]]
The variable decorated with code:PrimitiveId within the code:MeshEXT or
code:MeshNV {ExecutionModel} must: be declared using the code:Output
{StorageClass}
* [[VUID-{refpage}-PrimitiveId-04337]]
The variable decorated with code:PrimitiveId must: be declared as a
scalar 32-bit integer value
* [[VUID-{refpage}-PrimitiveId-07040]]
The variable decorated with code:PrimitiveId within the code:MeshEXT
{ExecutionModel} must: also be decorated with the code:PerPrimitiveEXT
decoration
****
--
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-primitiveindices]]
[open,refpage='PrimitiveIndicesNV',desc='Indices of primitives in a mesh shader',type='builtins']
--
:refpage: PrimitiveIndicesNV
code:PrimitiveIndicesNV::
+
Decorating a variable with the code:PrimitiveIndicesNV decoration 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 (code:OutputPoints), two
(code:OutputLinesNV), or three (code:OutputTriangles) indices and each group
generates a primitive.
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveIndicesNV-04338]]
The code:PrimitiveIndicesNV decoration must: be used only within the
code:MeshNV {ExecutionModel}
* [[VUID-{refpage}-PrimitiveIndicesNV-04339]]
The variable decorated with code:PrimitiveIndicesNV must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitiveIndicesNV-04340]]
The variable decorated with code:PrimitiveIndicesNV must: be declared as
an array of scalar 32-bit integer values
* [[VUID-{refpage}-PrimitiveIndicesNV-04341]]
All index values of the array decorated with code:PrimitiveIndicesNV
must: be in the range [eq]#[0, N-1]#, where [eq]#N# is the value
specified by the code:OutputVertices {ExecutionMode}
* [[VUID-{refpage}-OutputPoints-04342]]
If the {ExecutionMode} is code:OutputPoints, then the array decorated
with code:PrimitiveIndicesNV must be the size of the value specified by
code:OutputPrimitivesNV
* [[VUID-{refpage}-OutputLinesNV-04343]]
If the {ExecutionMode} is code:OutputLinesNV, then the array decorated
with code:PrimitiveIndicesNV must be the size of two times the value
specified by code:OutputPrimitivesNV
* [[VUID-{refpage}-OutputTrianglesNV-04344]]
If the {ExecutionMode} is code:OutputTrianglesNV, then the array
decorated with code:PrimitiveIndicesNV must be the size of three times
the value specified by code:OutputPrimitivesNV
****
--
endif::VK_NV_mesh_shader[]
ifdef::VK_EXT_mesh_shader[]
[[interfaces-builtin-variables-primitivepointindices]]
[open,refpage='PrimitivePointIndicesEXT',desc='Indices of point primitives in a mesh shader',type='builtins']
--
:refpage: PrimitivePointIndicesEXT
code:PrimitivePointIndicesEXT::
+
Decorating a variable with the code:PrimitivePointIndicesEXT decoration will
make that variable contain the output array of vertex index values for point
primitives.
.Valid Usage
****
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07041]]
The code:PrimitivePointIndicesEXT decoration must: be used only within
the code:MeshEXT {ExecutionModel}
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07042]]
The code:PrimitivePointIndicesEXT decoration must: be used with the
code:OutputPoints {ExecutionMode}
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07043]]
The variable decorated with code:PrimitivePointIndicesEXT must: be
declared using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07044]]
The variable decorated with code:PrimitivePointIndicesEXT must: be
declared as an array of scalar 32-bit integer values
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07045]]
All index values of the array decorated with
code:PrimitivePointIndicesEXT must: be in the range [eq]#[0, N-1]#,
where [eq]#N# is the value specified by the code:OutputVertices
{ExecutionMode}
* [[VUID-{refpage}-PrimitivePointIndicesEXT-07046]]
The size of the array decorated with code:PrimitivePointIndicesEXT must:
match the value specified by code:OutputPrimitivesEXT
****
--
[[interfaces-builtin-variables-primitivelineindices]]
[open,refpage='PrimitiveLineIndicesEXT',desc='Indices of line primitives in a mesh shader',type='builtins']
--
:refpage: PrimitiveLineIndicesEXT
code:PrimitiveLineIndicesEXT::
+
Decorating a variable with the code:PrimitiveLineIndicesEXT decoration will
make that variable contain the output array of vertex index values for line
primitives.
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07047]]
The code:PrimitiveLineIndicesEXT decoration must: be used only within
the code:MeshEXT {ExecutionModel}
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07048]]
The code:PrimitiveLineIndicesEXT decoration must: be used with the
code:OutputLinesEXT {ExecutionMode}
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07049]]
The variable decorated with code:PrimitiveLineIndicesEXT must: be
declared using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07050]]
The variable decorated with code:PrimitiveLineIndicesEXT must: be
declared as an array of two component vector 32-bit integer values
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07051]]
All index values of the array decorated with
code:PrimitiveLineIndicesEXT must: be in the range [eq]#[0, N-1]#, where
[eq]#N# is the value specified by the code:OutputVertices
{ExecutionMode}
* [[VUID-{refpage}-PrimitiveLineIndicesEXT-07052]]
The size of the array decorated with code:PrimitiveLineIndicesEXT must:
match the value specified by code:OutputPrimitivesEXT
****
--
[[interfaces-builtin-variables-primitivetriangleindices]]
[open,refpage='PrimitiveTriangleIndicesEXT',desc='Indices of triangle primitives in a mesh shader',type='builtins']
--
:refpage: PrimitiveTriangleIndicesEXT
code:PrimitiveTriangleIndicesEXT::
+
Decorating a variable with the code:PrimitiveTriangleIndicesEXT decoration
will make that variable contain the output array of vertex index values for
triangle primitives.
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07053]]
The code:PrimitiveTriangleIndicesEXT decoration must: be used only
within the code:MeshEXT {ExecutionModel}
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07054]]
The code:PrimitiveTriangleIndicesEXT decoration must: be used with the
code:OutputTrianglesEXT {ExecutionMode}
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07055]]
The variable decorated with code:PrimitiveTriangleIndicesEXT must: be
declared using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07056]]
The variable decorated with code:PrimitiveTriangleIndicesEXT must: be
declared as an array of three component vector 32-bit integer values
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07057]]
All index values of the array decorated with
code:PrimitiveTriangleIndicesEXT must: be in the range [eq]#[0, N-1]#,
where [eq]#N# is the value specified by the code:OutputVertices
{ExecutionMode}
* [[VUID-{refpage}-PrimitiveTriangleIndicesEXT-07058]]
The size of the array decorated with code:PrimitiveTriangleIndicesEXT
must: match the value specified by code:OutputPrimitivesEXT
****
--
endif::VK_EXT_mesh_shader[]
ifdef::VK_KHR_fragment_shading_rate[]
[[interfaces-builtin-variables-primitiveshadingrate]]
[open,refpage='PrimitiveShadingRateKHR',desc='Primitive contribution to fragment shading rate',type='builtins']
--
:refpage: PrimitiveShadingRateKHR
code:PrimitiveShadingRateKHR::
Decorating a variable with the code:PrimitiveShadingRateKHR built-in
decoration will make that variable contain the
<<primsrast-fragment-shading-rate-primitive, primitive fragment shading
rate>>.
+
The value written to the variable decorated with
code:PrimitiveShadingRateKHR by the last
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> in the pipeline is used as the
<<primsrast-fragment-shading-rate-primitive, primitive fragment shading
rate>>.
Outputs in previous shader stages are ignored.
+
If the last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface does not include a variable decorated
with code: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 code:PrimitiveShadingRateKHR in 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.
.Valid Usage
****
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04484]]
The code:PrimitiveShadingRateKHR decoration must: be used only within
the code:MeshEXT, code:MeshNV, code:Vertex, or code:Geometry
{ExecutionModel}
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04485]]
The variable decorated with code:PrimitiveShadingRateKHR must: be
declared using the code:Output {StorageClass}
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04486]]
The variable decorated with code:PrimitiveShadingRateKHR must: be
declared as a scalar 32-bit integer value
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04487]]
The value written to code:PrimitiveShadingRateKHR must: include no more
than one of code:Vertical2Pixels and code:Vertical4Pixels
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04488]]
The value written to code:PrimitiveShadingRateKHR must: include no more
than one of code:Horizontal2Pixels and code:Horizontal4Pixels
* [[VUID-{refpage}-PrimitiveShadingRateKHR-04489]]
The value written to code:PrimitiveShadingRateKHR must: not have any
bits set other than those defined by *Fragment Shading Rate Flags*
enumerants in the SPIR-V specification
* [[VUID-{refpage}-PrimitiveShadingRateKHR-07059]]
The variable decorated with code:PrimitiveShadingRateKHR within the
code:MeshEXT {ExecutionModel} must: also be decorated with the
code:PerPrimitiveEXT decoration
****
--
endif::VK_KHR_fragment_shading_rate[]
ifdef::VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-raygeometryindex]]
[open,refpage='RayGeometryIndexKHR',desc='Geometry index in a ray shader',type='builtins']
--
:refpage: RayGeometryIndexKHR
code:RayGeometryIndexKHR::
A variable decorated with the code:RayGeometryIndexKHR decoration will
contain the <<acceleration-structure-geometry-index, geometry index>> for
the acceleration structure geometry currently being shaded.
.Valid Usage
****
* [[VUID-{refpage}-RayGeometryIndexKHR-04345]]
The code:RayGeometryIndexKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-RayGeometryIndexKHR-04346]]
The variable decorated with code:RayGeometryIndexKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-RayGeometryIndexKHR-04347]]
The variable decorated with code:RayGeometryIndexKHR must: be declared
as a scalar 32-bit integer value
****
--
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-raytmax]]
[open,refpage='RayTmaxKHR',desc='Maximum T value of a ray',type='builtins']
--
:refpage: RayTmaxKHR
code:RayTmaxKHR::
A variable decorated with the code:RayTmaxKHR decoration will contain the
parametric [eq]#t~max~# 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 into code:OpTraceRayKHR.
+
The [eq]#t~max~# 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
code:OpReportIntersectionKHR if the corresponding any-hit shader does not
ignore the intersection.
In a miss shader, the value is identical to the parameter passed into
code:OpTraceRayKHR.
.Valid Usage
****
* [[VUID-{refpage}-RayTmaxKHR-04348]]
The code:RayTmaxKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-RayTmaxKHR-04349]]
The variable decorated with code:RayTmaxKHR must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-RayTmaxKHR-04350]]
The variable decorated with code:RayTmaxKHR must: be declared as a
scalar 32-bit floating-point value
****
--
[[interfaces-builtin-variables-raytmin]]
[open,refpage='RayTminKHR',desc='Minimum T value of a ray',type='builtins']
--
:refpage: RayTminKHR
code:RayTminKHR::
A variable decorated with the code:RayTminKHR decoration will contain the
parametric [eq]#t~min~# 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 into code:OpTraceRayKHR.
+
The [eq]#t~min~# value remains constant for the duration of the ray query.
.Valid Usage
****
* [[VUID-{refpage}-RayTminKHR-04351]]
The code:RayTminKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-RayTminKHR-04352]]
The variable decorated with code:RayTminKHR must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-RayTminKHR-04353]]
The variable decorated with code:RayTminKHR must: be declared as a
scalar 32-bit floating-point value
****
--
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-sampleid]]
[open,refpage='SampleId',desc='Sample ID within a fragment',type='builtins']
--
:refpage: SampleId
code:SampleId::
Decorating a variable with the code:SampleId built-in decoration will make
that variable contain the <<primsrast-multisampling-coverage-mask, coverage
index>> for the current fragment shader invocation.
code: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 code:SampleId, <<primsrast-sampleshading,Sample Shading>> is
considered enabled with a pname:minSampleShading value of 1.0.
.Valid Usage
****
* [[VUID-{refpage}-SampleId-04354]]
The code:SampleId decoration must: be used only within the code:Fragment
{ExecutionModel}
* [[VUID-{refpage}-SampleId-04355]]
The variable decorated with code:SampleId must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-SampleId-04356]]
The variable decorated with code:SampleId must: be declared as a scalar
32-bit integer value
****
--
[[interfaces-builtin-variables-samplemask]]
[open,refpage='SampleMask',desc='Coverage mask for a fragment shader invocation',type='builtins']
--
:refpage: SampleMask
code:SampleMask::
Decorating a variable with the code:SampleMask built-in decoration will make
any variable contain the <<fragops-shader-samplemask, sample mask>> for the
current fragment shader invocation.
+
A variable in the code:Input storage class decorated with code: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.
code: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 [eq]#32 {times} M {plus} B#.
+
A variable in the code:Output storage class decorated with code:SampleMask
is an array of integers forming a bit array in a manner similar to an input
variable decorated with code:SampleMask, but where each bit represents
coverage as computed by the shader.
This computed code:SampleMask is combined with the generated coverage mask
in the <<fragops-covg, multisample coverage>> operation.
+
Variables decorated with code: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 code: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 code:SampleMask, the sample mask has no effect on
the processing of a fragment.
.Valid Usage
****
* [[VUID-{refpage}-SampleMask-04357]]
The code:SampleMask decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-SampleMask-04358]]
The variable decorated with code:SampleMask must: be declared using the
code:Input or code:Output {StorageClass}
* [[VUID-{refpage}-SampleMask-04359]]
The variable decorated with code:SampleMask must: be declared as an
array of 32-bit integer values
****
--
[[interfaces-builtin-variables-sampleposition]]
[open,refpage='SamplePosition',desc='Position of a shaded sample',type='builtins']
--
:refpage: SamplePosition
code:SamplePosition::
Decorating a variable with the code: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 [eq]#(0,0)# and
the bottom right of the pixel is considered to be at coordinate [eq]#(1,1)#.
ifdef::VK_EXT_fragment_density_map[]
// Markup here is weird. To get all these paragraphs indented properly for
// the keyword, the '+' connector must be *inside* ifdefs w/o blank lines.
+
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 [eq]#(0,0)#
and the bottom right of the fragment is considered to be at coordinate
[eq]#(1,1)# for any fragment area.
endif::VK_EXT_fragment_density_map[]
+
If a fragment shader entry point's interface includes an input variable
decorated with code:SamplePosition, <<primsrast-sampleshading,Sample
Shading>> is considered enabled with a pname:minSampleShading value of 1.0.
ifdef::VK_EXT_sample_locations[]
+
If the current pipeline uses <<primsrast-samplelocations, custom sample
locations>> the value of any variable decorated with the code:SamplePosition
built-in decoration is undefined:.
endif::VK_EXT_sample_locations[]
.Valid Usage
****
* [[VUID-{refpage}-SamplePosition-04360]]
The code:SamplePosition decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-SamplePosition-04361]]
The variable decorated with code:SamplePosition must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SamplePosition-04362]]
The variable decorated with code:SamplePosition must: be declared as a
two-component vector of 32-bit floating-point values
****
--
ifdef::VK_KHR_fragment_shading_rate[]
[[interfaces-builtin-variables-shadingratekhr]]
[open,refpage='ShadingRateKHR',desc='Shading rate of a fragment',type='builtins']
--
:refpage: ShadingRateKHR
code:ShadingRateKHR::
Decorating a variable with the code:ShadingRateKHR built-in decoration will
make that variable contain the <<primsrast-fragment-shading-rate, fragment
shading rate>> for the current fragment invocation.
.Valid Usage
****
* [[VUID-{refpage}-ShadingRateKHR-04490]]
The code:ShadingRateKHR decoration must: be used only within the
code:Fragment {ExecutionModel}
* [[VUID-{refpage}-ShadingRateKHR-04491]]
The variable decorated with code:ShadingRateKHR must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-ShadingRateKHR-04492]]
The variable decorated with code:ShadingRateKHR must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_KHR_fragment_shading_rate[]
ifdef::VK_NV_shader_sm_builtins[]
[[interfaces-builtin-variables-smcountnv]]
[open,refpage='SMCountNV',desc='Number of SMs on the device',type='builtins']
--
:refpage: SMCountNV
code:SMCountNV::
Decorating a variable with the code:SMCountNV built-in decoration will make
that variable contain the number of SMs on the device.
.Valid Usage
****
* [[VUID-{refpage}-SMCountNV-04363]]
The variable decorated with code:SMCountNV must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-SMCountNV-04364]]
The variable decorated with code:SMCountNV must: be declared as a scalar
32-bit integer value
****
--
[[interfaces-builtin-variables-smidnv]]
[open,refpage='SMIDNV',desc='SM ID on which a shader invocation is running',type='builtins']
--
:refpage: SMIDNV
code:SMIDNV::
Decorating a variable with the code:SMIDNV built-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 [eq]#[0, code:SMCountNV-1]#.
.Valid Usage
****
* [[VUID-{refpage}-SMIDNV-04365]]
The variable decorated with code:SMIDNV must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-SMIDNV-04366]]
The variable decorated with code:SMIDNV must: be declared as a scalar
32-bit integer value
****
--
endif::VK_NV_shader_sm_builtins[]
ifdef::VK_VERSION_1_1[]
[[interfaces-builtin-variables-subgroupid]]
[open,refpage='SubgroupId',desc='Subgroup ID ',type='builtins']
--
:refpage: SubgroupId
code:SubgroupId::
+
Decorating a variable with the code:SubgroupId built-in decoration will make
that variable contain the index of the subgroup within the local workgroup.
This variable is in range [0, code:NumSubgroups-1].
.Valid Usage
****
* [[VUID-{refpage}-SubgroupId-04367]]
The code:SubgroupId decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-SubgroupId-04368]]
The variable decorated with code:SubgroupId must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupId-04369]]
The variable decorated with code:SubgroupId must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[]
[[interfaces-builtin-variables-sgeq]]
[open,refpage='SubgroupEqMask',desc='Mask of shader invocations in a subgroup with the same subgroup local invocation ID',type='builtins']
--
:refpage: SubgroupEqMask
code:SubgroupEqMask::
+
Decorating a variable with the code:SubgroupEqMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bit corresponding to the code:SubgroupLocalInvocationId is set in the
variable decorated with code:SubgroupEqMask.
All other bits are set to zero.
+
code:SubgroupEqMaskKHR is an alias of code:SubgroupEqMask.
.Valid Usage
****
* [[VUID-{refpage}-SubgroupEqMask-04370]]
The variable decorated with code:SubgroupEqMask must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupEqMask-04371]]
The variable decorated with code:SubgroupEqMask must: be declared as a
four-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-sgge]]
[open,refpage='SubgroupGeMask',desc='Mask of shader invocations in a subgroup with the same or higher subgroup local invocation ID',type='builtins']
--
:refpage: SubgroupGeMask
code:SubgroupGeMask::
+
Decorating a variable with the code: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
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGeMask.
All other bits are set to zero.
+
code:SubgroupGeMaskKHR is an alias of code:SubgroupGeMask.
.Valid Usage
****
* [[VUID-{refpage}-SubgroupGeMask-04372]]
The variable decorated with code:SubgroupGeMask must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupGeMask-04373]]
The variable decorated with code:SubgroupGeMask must: be declared as a
four-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-sggt]]
[open,refpage='SubgroupGtMask',desc='Mask of shader invocations in a subgroup with a higher subgroup local invocation ID',type='builtins']
--
:refpage: SubgroupGtMask
code:SubgroupGtMask::
+
Decorating a variable with the code:SubgroupGtMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations greater than
code:SubgroupLocalInvocationId through code:SubgroupSize-1 are set in the
variable decorated with code:SubgroupGtMask.
All other bits are set to zero.
+
code:SubgroupGtMaskKHR is an alias of code:SubgroupGtMask.
.Valid Usage
****
* [[VUID-{refpage}-SubgroupGtMask-04374]]
The variable decorated with code:SubgroupGtMask must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupGtMask-04375]]
The variable decorated with code:SubgroupGtMask must: be declared as a
four-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-sgle]]
[open,refpage='SubgroupLeMask',desc='Mask of shader invocations in a subgroup with the same or lower subgroup local invocation ID',type='builtins']
--
:refpage: SubgroupLeMask
code:SubgroupLeMask::
+
Decorating a variable with the code: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
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLeMask.
All other bits are set to zero.
+
code:SubgroupLeMaskKHR is an alias of code:SubgroupLeMask.
.Valid Usage
****
* [[VUID-{refpage}-SubgroupLeMask-04376]]
The variable decorated with code:SubgroupLeMask must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupLeMask-04377]]
The variable decorated with code:SubgroupLeMask must: be declared as a
four-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-sglt]]
[open,refpage='SubgroupLtMask',desc='Mask of shader invocations in a subgroup with a lower subgroup local invocation ID',type='builtins']
--
:refpage: SubgroupLtMask
code:SubgroupLtMask::
+
Decorating a variable with the code:SubgroupLtMask builtin decoration will
make that variable contain the _subgroup mask_ of the current subgroup
invocation.
The bits corresponding to the invocations less than
code:SubgroupLocalInvocationId are set in the variable decorated with
code:SubgroupLtMask.
All other bits are set to zero.
+
code:SubgroupLtMaskKHR is an alias of code:SubgroupLtMask.
.Valid Usage
****
* [[VUID-{refpage}-SubgroupLtMask-04378]]
The variable decorated with code:SubgroupLtMask must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupLtMask-04379]]
The variable decorated with code:SubgroupLtMask must: be declared as a
four-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-sgli]]
[open,refpage='SubgroupLocalInvocationId',desc='ID of the invocation within a subgroup',type='builtins']
--
:refpage: SubgroupLocalInvocationId
code:SubgroupLocalInvocationId::
+
Decorating a variable with the code:SubgroupLocalInvocationId builtin
decoration will make that variable contain the index of the invocation
within the subgroup.
This variable is in range [0,code:SubgroupSize-1].
ifdef::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
+
If ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT is
specified,
ifdef::VK_VERSION_1_3[]
or if pname:module declares SPIR-V version 1.6 or higher, and the local
workgroup size in the X dimension of the pname:stage is a multiple of
<<interfaces-builtin-variables-sgs,code:SubgroupSize>>,
endif::VK_VERSION_1_3[]
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
code:SubgroupLocalInvocationId for each value in range
[0,code:SubgroupSize-1].
endif::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
[NOTE]
.Note
====
There is no direct relationship between code:SubgroupLocalInvocationId and
code:LocalInvocationId or code:LocalInvocationIndex.
ifdef::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
If the pipeline
ifdef::VK_EXT_shader_object[]
or shader object
endif::VK_EXT_shader_object[]
was created with full subgroups applications can compute their own local
invocation index to serve the same purpose:
[eq]#index = code:SubgroupLocalInvocationId + code:SubgroupId {times}
code: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 [eq]#index# unreliable.
endif::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
====
ifdef::VK_VERSION_1_3[]
[NOTE]
.Note
====
ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT
ifndef::VK_EXT_shader_object[]
is
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_shader_object[]
and ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are
endif::VK_EXT_shader_object[]
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.
====
endif::VK_VERSION_1_3[]
.Valid Usage
****
* [[VUID-{refpage}-SubgroupLocalInvocationId-04380]]
The variable decorated with code:SubgroupLocalInvocationId must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupLocalInvocationId-04381]]
The variable decorated with code:SubgroupLocalInvocationId must: be
declared as a scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-sgs]]
[open,refpage='SubgroupSize',desc='Size of a subgroup',type='builtins']
--
:refpage: SubgroupSize
code:SubgroupSize::
+
Decorating a variable with the code:SubgroupSize builtin decoration will
make that variable contain the implementation-dependent
<<limits-subgroup-size, number of invocations in a subgroup>>.
This value must: be a power-of-two integer.
+
ifdef::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
If the pipeline was created with the
ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag
set,
ifdef::VK_EXT_shader_object[]
or the shader object was created with the
ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT flag set,
endif::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3[]
or the SPIR-V pname:module is at least version 1.6,
endif::VK_VERSION_1_3[]
the code:SubgroupSize decorated variable will contain the subgroup size for
each subgroup that gets dispatched.
This value must: be between <<limits-minSubgroupSize,
pname:minSubgroupSize>> and <<limits-maxSubgroupSize,
pname:maxSubgroupSize>> and must: be uniform with <<shaders-scope-subgroup,
subgroup scope>>.
The value may: vary across a single draw call, and for fragment shaders may:
vary across a single primitive.
In compute dispatches, code:SubgroupSize must: be uniform with
<<shaders-scope-command, command scope>>.
+
If the pipeline was created with a chained
slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure,
ifdef::VK_EXT_shader_object[]
or the shader object was created with a chained
slink:VkShaderRequiredSubgroupSizeCreateInfoEXT structure,
endif::VK_EXT_shader_object[]
the code:SubgroupSize decorated variable will match
<<pipelines-required-subgroup-size, pname:requiredSubgroupSize>>.
+
If
ifdef::VK_VERSION_1_3[]
SPIR-V pname:module is less than version 1.6 and
endif::VK_VERSION_1_3[]
the pipeline was not created with the
ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag
set and no slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfo
structure was chained,
ifdef::VK_EXT_shader_object[]
and the shader was not created with the
ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT flag set and no
slink:VkShaderRequiredSubgroupSizeCreateInfoEXT structure was chained,
endif::VK_EXT_shader_object[]
the
endif::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
ifndef::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
The
endif::VK_VERSION_1_3,VK_EXT_subgroup_size_control[]
variable decorated with code:SubgroupSize will match <<limits-subgroup-size,
pname:subgroupSize>>.
+
The maximum number of invocations that an implementation can support per
subgroup is 128.
ifdef::VK_VERSION_1_3[]
[NOTE]
.Note
====
The old behavior for code:SubgroupSize is considered deprecated as certain
compute algorithms cannot be easily implemented without the guarantees of
ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT and
ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT.
====
endif::VK_VERSION_1_3[]
.Valid Usage
****
* [[VUID-{refpage}-SubgroupSize-04382]]
The variable decorated with code:SubgroupSize must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-SubgroupSize-04383]]
The variable decorated with code:SubgroupSize must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_VERSION_1_1,VK_EXT_shader_subgroup_ballot[]
ifdef::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-taskcount]]
[open,refpage='TaskCountNV',desc='Number of mesh shader workgroups that will be generated',type='builtins']
--
:refpage: TaskCountNV
code:TaskCountNV::
+
Decorating a variable with the code:TaskCountNV decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-TaskCountNV-04384]]
The code:TaskCountNV decoration must: be used only within the
code:TaskNV {ExecutionModel}
* [[VUID-{refpage}-TaskCountNV-04385]]
The variable decorated with code:TaskCountNV must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-TaskCountNV-04386]]
The variable decorated with code:TaskCountNV must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_NV_mesh_shader[]
[[interfaces-builtin-variables-tesscoord]]
[open,refpage='TessCoord',desc='Barycentric coordinate of a tessellated vertex within a patch',type='builtins']
--
:refpage: TessCoord
code:TessCoord::
Decorating a variable with the code:TessCoord built-in decoration will make
that variable contain the three-dimensional [eq]#(u,v,w)# barycentric
coordinate of the tessellated vertex within the patch.
[eq]#u#, [eq]#v#, and [eq]#w# are in the range [eq]#[0,1]# and vary linearly
across the primitive being subdivided.
For the tessellation modes of code:Quads or code:IsoLines, the third
component is always zero.
.Valid Usage
****
* [[VUID-{refpage}-TessCoord-04387]]
The code:TessCoord decoration must: be used only within the
code:TessellationEvaluation {ExecutionModel}
* [[VUID-{refpage}-TessCoord-04388]]
The variable decorated with code:TessCoord must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-TessCoord-04389]]
The variable decorated with code:TessCoord must: be declared as a
three-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-tesslevelouter]]
[open,refpage='TessLevelOuter',desc='Outer tessellation levels',type='builtins']
--
:refpage: TessLevelOuter
code:TessLevelOuter::
Decorating a variable with the code: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
code: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
code:TessLevelOuter can: read the values written by the tessellation control
shader.
.Valid Usage
****
* [[VUID-{refpage}-TessLevelOuter-04390]]
The code:TessLevelOuter decoration must: be used only within the
code:TessellationControl or code:TessellationEvaluation {ExecutionModel}
* [[VUID-{refpage}-TessLevelOuter-04391]]
The variable decorated with code:TessLevelOuter within the
code:TessellationControl {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-TessLevelOuter-04392]]
The variable decorated with code:TessLevelOuter within the
code:TessellationEvaluation {ExecutionModel} must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-TessLevelOuter-04393]]
The variable decorated with code:TessLevelOuter must: be declared as an
array of size four, containing 32-bit floating-point values
****
--
[[interfaces-builtin-variables-tesslevelinner]]
[open,refpage='TessLevelInner',desc='Inner tessellation levels',type='builtins']
--
:refpage: TessLevelInner
code:TessLevelInner::
Decorating a variable with the code: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
code: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
code:TessLevelInner can: read the values written by the tessellation control
shader.
.Valid Usage
****
* [[VUID-{refpage}-TessLevelInner-04394]]
The code:TessLevelInner decoration must: be used only within the
code:TessellationControl or code:TessellationEvaluation {ExecutionModel}
* [[VUID-{refpage}-TessLevelInner-04395]]
The variable decorated with code:TessLevelInner within the
code:TessellationControl {ExecutionModel} must: be declared using the
code:Output {StorageClass}
* [[VUID-{refpage}-TessLevelInner-04396]]
The variable decorated with code:TessLevelInner within the
code:TessellationEvaluation {ExecutionModel} must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-TessLevelInner-04397]]
The variable decorated with code:TessLevelInner must: be declared as an
array of size two, containing 32-bit floating-point values
****
--
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-vertexcounthuawei]]
[open,refpage='VertexCountHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: VertexCountHUAWEI
code:VertexCountHUAWEI::
The code:VertexCountHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-VertexCountHUAWEI-07809]]
The code:VertexCountHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-VertexCountHUAWEI-07810]]
The variable decorated with code:VertexCountHUAWEI must: be declared as
a scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-vertexindex]]
[open,refpage='VertexIndex',desc='Vertex index of a shader invocation',type='builtins']
--
:refpage: VertexIndex
code:VertexIndex::
Decorating a variable with the code: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 pname:firstVertex
parameter to flink:vkCmdDraw or the pname:firstVertex member of a structure
consumed by flink: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 pname:vertexOffset parameter to flink:vkCmdDrawIndexed or
the pname:vertexOffset member of the structure consumed by
flink:vkCmdDrawIndexedIndirect.
[NOTE]
.Note
====
code:VertexIndex starts at the same starting value for each instance.
====
.Valid Usage
****
* [[VUID-{refpage}-VertexIndex-04398]]
The code:VertexIndex decoration must: be used only within the
code:Vertex {ExecutionModel}
* [[VUID-{refpage}-VertexIndex-04399]]
The variable decorated with code:VertexIndex must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-VertexIndex-04400]]
The variable decorated with code:VertexIndex must: be declared as a
scalar 32-bit integer value
****
--
ifdef::VK_HUAWEI_cluster_culling_shader[]
[[interfaces-builtin-variables-vertexoffsethuawei]]
[open,refpage='VertexOffsetHUAWEI',desc='cluster culling shader output variable',type='builtins']
--
:refpage: VertexOffsetHUAWEI
code:VertexOffsetHUAWEI::
The code:VertexOffsetHUAWEI decoration 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.
.Valid Usage
****
* [[VUID-{refpage}-VertexOffsetHUAWEI-07811]]
The code:VertexOffsetHUAWEI decoration must: be used only within the
code:ClusterCullingHUAWEI {ExecutionModel}
* [[VUID-{refpage}-VertexOffsetHUAWEI-07812]]
The variable decorated with code:VertexOffsetHUAWEI must: be declared as
a scalar 32-bit integer value
****
--
endif::VK_HUAWEI_cluster_culling_shader[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
[[interfaces-builtin-variables-viewindex]]
[open,refpage='ViewIndex',desc='View index of a shader invocation',type='builtins']
--
:refpage: ViewIndex
code:ViewIndex::
The code: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-{refpage}-ViewIndex-04401]]
The code:ViewIndex decoration must: be used only within the
code:MeshEXT, code:Vertex, code:Geometry, code:TessellationControl,
code:TessellationEvaluation or code:Fragment {ExecutionModel}
* [[VUID-{refpage}-ViewIndex-04402]]
The variable decorated with code:ViewIndex must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-ViewIndex-04403]]
The variable decorated with code:ViewIndex must: be declared as a scalar
32-bit integer value
****
--
endif::VK_VERSION_1_1,VK_KHR_multiview[]
[[interfaces-builtin-variables-viewportindex]]
[open,refpage='ViewportIndex',desc='Viewport index used',type='builtins']
--
:refpage: ViewportIndex
code:ViewportIndex::
Decorating a variable with the code:ViewportIndex built-in decoration will
make that variable contain the index of the viewport.
+
In a
ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[mesh,]
vertex, tessellation evaluation, or
endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
geometry shader, the variable decorated with code: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
ifndef::VK_NV_scissor_exclusive[]
viewport transform and
endif::VK_NV_scissor_exclusive[]
ifdef::VK_NV_scissor_exclusive[]
viewport transform, scissor rectangle, and exclusive
endif::VK_NV_scissor_exclusive[]
scissor rectangle.
ifdef::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
+
The last active
_<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>_ (in pipeline order) controls the code:ViewportIndex that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:ViewportIndex.
endif::VK_VERSION_1_2,VK_EXT_shader_viewport_index_layer,VK_NV_viewport_array2[]
+
If the last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface does not include a variable decorated
with code:ViewportIndex
ifdef::VK_QCOM_multiview_per_view_viewports[]
, and if <<features-multiview-per-view-viewports,
multiviewPerViewViewports>> is not enabled,
endif::VK_QCOM_multiview_per_view_viewports[]
then the first viewport is used.
If a <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface includes a variable decorated with
code:ViewportIndex, it must: write the same value to code:ViewportIndex for
all output vertices of a given primitive.
+
In a fragment shader, the variable decorated with code:ViewportIndex
contains the viewport index of the primitive that the fragment invocation
belongs to.
ifdef::VK_QCOM_multiview_per_view_viewports[]
+
If <<features-multiview-per-view-viewports,
pname:multiviewPerViewViewports>> is enabled, and if the last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface does not include a variable decorated
with code:ViewportIndex, then the value of code:ViewIndex is used as an
index to select the viewport transform and scissor rectangle, and the value
of code:ViewportIndex in the fragment shader is undefined::.
endif::VK_QCOM_multiview_per_view_viewports[]
.Valid Usage
****
* [[VUID-{refpage}-ViewportIndex-04404]]
The code:ViewportIndex decoration must: be used only within the
code:MeshEXT, code:MeshNV, code:Vertex, code:TessellationEvaluation,
code:Geometry, or code:Fragment {ExecutionModel}
ifdef::VK_VERSION_1_2[]
* [[VUID-{refpage}-ViewportIndex-04405]]
If the <<features-shaderOutputViewportIndex,
pname:shaderOutputViewportIndex>> feature is not enabled then the
code:ViewportIndex decoration must: be used only within the
code:Geometry or code:Fragment {ExecutionModel}
endif::VK_VERSION_1_2[]
* [[VUID-{refpage}-ViewportIndex-04406]]
The variable decorated with code:ViewportIndex within the code:MeshEXT,
code:MeshNV, code:Vertex, code:TessellationEvaluation, or code:Geometry
{ExecutionModel} must: be declared using the code:Output {StorageClass}
* [[VUID-{refpage}-ViewportIndex-04407]]
The variable decorated with code:ViewportIndex within the code:Fragment
{ExecutionModel} must: be declared using the code:Input {StorageClass}
* [[VUID-{refpage}-ViewportIndex-04408]]
The variable decorated with code:ViewportIndex must: be declared as a
scalar 32-bit integer value
* [[VUID-{refpage}-ViewportIndex-07060]]
The variable decorated with code:ViewportIndex within the code:MeshEXT
{ExecutionModel} must: also be decorated with the code:PerPrimitiveEXT
decoration
****
--
ifdef::VK_NV_viewport_array2[]
[[interfaces-builtin-variables-viewportmask]]
[open,refpage='ViewportMaskNV',desc='Mask of the viewports used',type='builtins']
--
:refpage: ViewportMaskNV
code:ViewportMaskNV::
Decorating a variable with the code:ViewportMaskNV built-in decoration will
make that variable contain the viewport mask.
+
In a
ifdef::VK_NV_mesh_shader[]
mesh,
endif::VK_NV_mesh_shader[]
vertex, tessellation evaluation, or geometry shader, the variable decorated
with code:ViewportMaskNV can be written to with the mask of which viewports
the primitive produced by that shader will directed.
+
The code:ViewportMaskNV variable must: be an array that has
[eq]#{lceil}(sname:VkPhysicalDeviceLimits::pname:maxViewports / 32){rceil}#
elements.
When a shader writes to this variable, bit B of element M controls whether a
primitive is emitted to viewport [eq]#32 {times} M {plus} B#.
The viewports indicated by the mask are used to select the
ifndef::VK_NV_scissor_exclusive[]
viewport transform and
endif::VK_NV_scissor_exclusive[]
ifdef::VK_NV_scissor_exclusive[]
viewport transform, scissor rectangle, and exclusive
endif::VK_NV_scissor_exclusive[]
scissor rectangle that a primitive will be transformed by.
+
The last active
_<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>_ (in pipeline order) controls the code:ViewportMaskNV that is used.
Outputs in previous shader stages are not used, even if the last stage fails
to write the code:ViewportMaskNV.
When code:ViewportMaskNV is written by the final
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>, any variable decorated with code:ViewportIndex in the fragment
shader will have the index of the viewport that was used in generating that
fragment.
+
If a <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader entry point's interface includes a variable decorated with
code:ViewportMaskNV, it must: write the same value to code:ViewportMaskNV
for all output vertices of a given primitive.
.Valid Usage
****
* [[VUID-{refpage}-ViewportMaskNV-04409]]
The code:ViewportMaskNV decoration must: be used only within the
code:Vertex, code:MeshNV, code:TessellationEvaluation, or code:Geometry
{ExecutionModel}
* [[VUID-{refpage}-ViewportMaskNV-04410]]
The variable decorated with code:ViewportMaskNV must: be declared using
the code:Output {StorageClass}
* [[VUID-{refpage}-ViewportMaskNV-04411]]
The variable decorated with code:ViewportMaskNV must: be declared as an
array of 32-bit integer values
****
--
endif::VK_NV_viewport_array2[]
ifdef::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[]
[[interfaces-builtin-variables-viewportmaskperview]]
[open,refpage='ViewportMaskPerViewNV',desc='Mask of viewports broadcast to per view',type='builtins']
--
:refpage: ViewportMaskPerViewNV
code:ViewportMaskPerViewNV::
Decorating a variable with the code:ViewportMaskPerViewNV built-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 code:ViewportMaskPerViewNV in the last
<<pipelines-graphics-subsets-pre-rasterization,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
ifndef::VK_NV_scissor_exclusive[]
viewport transform and
endif::VK_NV_scissor_exclusive[]
ifdef::VK_NV_scissor_exclusive[]
viewport transform, scissor rectangle, and exclusive
endif::VK_NV_scissor_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.
code:ViewportMaskPerViewNV output in an earlier
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> is not available as an input in the subsequent
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>.
+
Although code:ViewportMaskNV is an array, code:ViewportMaskPerViewNV is not
a two-dimensional array.
Instead, code:ViewportMaskPerViewNV is limited to 32 viewports.
.Valid Usage
****
* [[VUID-{refpage}-ViewportMaskPerViewNV-04412]]
The code:ViewportMaskPerViewNV decoration must: be used only within the
code:Vertex, code:MeshNV, code:TessellationControl,
code:TessellationEvaluation, or code:Geometry {ExecutionModel}
* [[VUID-{refpage}-ViewportMaskPerViewNV-04413]]
The variable decorated with code:ViewportMaskPerViewNV must: be declared
using the code:Output {StorageClass}
* [[VUID-{refpage}-ViewportMaskPerViewNV-04414]]
The variable decorated with code:ViewportMaskPerViewNV must: be declared
as an array of 32-bit integer values
* [[VUID-{refpage}-ViewportMaskPerViewNV-04415]]
The array decorated with code:ViewportMaskPerViewNV must: be a size less
than or equal to 32
* [[VUID-{refpage}-ViewportMaskPerViewNV-04416]]
The array decorated with code:ViewportMaskPerViewNV must: be a size
greater than the maximum view in the subpass's view mask
* [[VUID-{refpage}-ViewportMaskPerViewNV-04417]]
The array variable decorated with code:ViewportMaskPerViewNV must: only
be indexed by a constant or specialization constant
****
--
endif::VK_NVX_multiview_per_view_attributes+VK_NV_viewport_array2[]
ifdef::VK_NV_shader_sm_builtins[]
[[interfaces-builtin-variables-warpspersmnv]]
[open,refpage='WarpsPerSMNV',desc='Number of warps per SM',type='builtins']
--
:refpage: WarpsPerSMNV
code:WarpsPerSMNV::
Decorating a variable with the code:WarpsPerSMNV built-in decoration will
make that variable contain the maximum number of warps executing on a SM.
.Valid Usage
****
* [[VUID-{refpage}-WarpsPerSMNV-04418]]
The variable decorated with code:WarpsPerSMNV must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-WarpsPerSMNV-04419]]
The variable decorated with code:WarpsPerSMNV must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-warpidnv]]
[open,refpage='WarpIDNV',desc='Warp ID within an SM of a shader invocation',type='builtins']
--
:refpage: WarpIDNV
code:WarpIDNV::
Decorating a variable with the code:WarpIDNV built-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 [eq]#[0, code:WarpsPerSMNV-1]#.
.Valid Usage
****
* [[VUID-{refpage}-WarpIDNV-04420]]
The variable decorated with code:WarpIDNV must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-WarpIDNV-04421]]
The variable decorated with code:WarpIDNV must: be declared as a scalar
32-bit integer value
****
--
endif::VK_NV_shader_sm_builtins[]
[[interfaces-builtin-variables-workgroupid]]
[open,refpage='WorkgroupId',desc='Workgroup ID of a shader',type='builtins']
--
:refpage: WorkgroupId
code:WorkgroupId::
Decorating a variable with the code: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 [eq]#base {plus} count# value,
based on the parameters passed into the dispatching commands.
.Valid Usage
****
* [[VUID-{refpage}-WorkgroupId-04422]]
The code:WorkgroupId decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-WorkgroupId-04423]]
The variable decorated with code:WorkgroupId must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-WorkgroupId-04424]]
The variable decorated with code:WorkgroupId must: be declared as a
three-component vector of 32-bit integer values
****
--
[[interfaces-builtin-variables-workgroupsize]]
[open,refpage='WorkgroupSize',desc='Size of a workgroup',type='builtins']
--
:refpage: WorkgroupSize
code:WorkgroupSize::
ifdef::VK_VERSION_1_3[]
[NOTE]
.Note
====
SPIR-V 1.6 deprecated code:WorkgroupSize in favor of using the
code:LocalSizeId Execution Mode instead.
Support for code:LocalSizeId was added with `apiext:VK_KHR_maintenance4` and
promoted to core in Version 1.3.
====
endif::VK_VERSION_1_3[]
Decorating an object with the code:WorkgroupSize built-in decoration will
make that object contain the dimensions of a local workgroup.
If an object is decorated with the code:WorkgroupSize decoration, this takes
precedence over any code:LocalSize
ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[or code:LocalSizeId]
execution mode.
.Valid Usage
****
* [[VUID-{refpage}-WorkgroupSize-04425]]
The code:WorkgroupSize decoration must: be used only within the
code:GLCompute, code:MeshEXT, code:TaskEXT, code:MeshNV, or code:TaskNV
{ExecutionModel}
* [[VUID-{refpage}-WorkgroupSize-04426]]
The variable decorated with code:WorkgroupSize must: be a specialization
constant or a constant
* [[VUID-{refpage}-WorkgroupSize-04427]]
The variable decorated with code:WorkgroupSize must: be declared as a
three-component vector of 32-bit integer values
****
--
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[interfaces-builtin-variables-worldraydirection]]
[open,refpage='WorldRayDirectionKHR',desc='Ray direction in world space',type='builtins']
--
:refpage: WorldRayDirectionKHR
code:WorldRayDirectionKHR::
A variable decorated with the code:WorldRayDirectionKHR decoration will
specify the direction of the ray being processed, in world space.
The value is the parameter passed into code:OpTraceRayKHR.
.Valid Usage
****
* [[VUID-{refpage}-WorldRayDirectionKHR-04428]]
The code:WorldRayDirectionKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-WorldRayDirectionKHR-04429]]
The variable decorated with code:WorldRayDirectionKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-WorldRayDirectionKHR-04430]]
The variable decorated with code:WorldRayDirectionKHR must: be declared
as a three-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-worldrayorigin]]
[open,refpage='WorldRayOriginKHR',desc='Ray origin in world space',type='builtins']
--
:refpage: WorldRayOriginKHR
code:WorldRayOriginKHR::
A variable decorated with the code:WorldRayOriginKHR decoration will specify
the origin of the ray being processed, in world space.
The value is the parameter passed into code:OpTraceRayKHR.
.Valid Usage
****
* [[VUID-{refpage}-WorldRayOriginKHR-04431]]
The code:WorldRayOriginKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, code:ClosestHitKHR, or
code:MissKHR {ExecutionModel}
* [[VUID-{refpage}-WorldRayOriginKHR-04432]]
The variable decorated with code:WorldRayOriginKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-WorldRayOriginKHR-04433]]
The variable decorated with code:WorldRayOriginKHR must: be declared as
a three-component vector of 32-bit floating-point values
****
--
[[interfaces-builtin-variables-worldtoobject]]
[open,refpage='WorldToObjectKHR',desc='Transformation matrix from world to object space',type='builtins']
--
:refpage: WorldToObjectKHR
code:WorldToObjectKHR::
A variable decorated with the code:WorldToObjectKHR decoration will contain
the current world-to-object transformation matrix, which is determined by
the instance of the current intersection.
.Valid Usage
****
* [[VUID-{refpage}-WorldToObjectKHR-04434]]
The code:WorldToObjectKHR decoration must: be used only within the
code:IntersectionKHR, code:AnyHitKHR, or code:ClosestHitKHR
{ExecutionModel}
* [[VUID-{refpage}-WorldToObjectKHR-04435]]
The variable decorated with code:WorldToObjectKHR must: be declared
using the code:Input {StorageClass}
* [[VUID-{refpage}-WorldToObjectKHR-04436]]
The variable decorated with code:WorldToObjectKHR must: be declared as a
matrix with four columns of three-component vectors of 32-bit
floating-point values
****
--
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
ifdef::VK_ARM_shader_core_builtins[]
[[interfaces-builtin-variables-corecountarm]]
[open,refpage='CoreCountARM',desc='Number of cores on the device',type='builtins']
--
:refpage: CoreCountARM
code:CoreCountARM::
Decorating a variable with the code:CoreCountARM built-in decoration will
make that variable contain the number of cores on the device.
.Valid Usage
****
* [[VUID-{refpage}-CoreCountARM-07595]]
The variable decorated with code:CoreCountARM must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-CoreCountARM-07596]]
The variable decorated with code:CoreCountARM must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-coremaxidarm]]
[open,refpage='CoreMaxIDARM',desc='Max core ID that can be observed on the device running the invovation reading CoreMaxIDARM',type='builtins']
--
:refpage: CoreMaxIDARM
code:CoreMaxIDARM::
Decorating a variable with the code:CoreMaxIDARM built-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.
.Valid Usage
****
* [[VUID-{refpage}-CoreMaxIDARM-07597]]
The variable decorated with code:CoreMaxIDARM must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-CoreMaxIDARM-07598]]
The variable decorated with code:CoreMaxIDARM must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-coreidarm]]
[open,refpage='CoreIDARM',desc='Core ID on which a shader invocation is running',type='builtins']
--
:refpage: CoreIDARM
code:CoreIDARM::
Decorating a variable with the code:CoreIDARM built-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 [eq]#[0, code:CoreMaxIDARM]#.
.Valid Usage
****
* [[VUID-{refpage}-CoreIDARM-07599]]
The variable decorated with code:CoreIDARM must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-CoreIDARM-07600]]
The variable decorated with code:CoreIDARM must: be declared as a scalar
32-bit integer value
****
--
[[interfaces-builtin-variables-warpmaxidarm]]
[open,refpage='WarpMaxIDARM',desc='Max ID for a warp on the core running a shader invovation',type='builtins']
--
:refpage: WarpMaxIDARM
code:WarpMaxIDARM::
Decorating a variable with the code:WarpMaxIDARM built-in decoration will
make that variable contain the maximum warp ID for the core on which the
current invocation is running.
.Valid Usage
****
* [[VUID-{refpage}-WarpMaxIDARM-07601]]
The variable decorated with code:WarpMaxIDARM must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-WarpMaxIDARM-07602]]
The variable decorated with code:WarpMaxIDARM must: be declared as a
scalar 32-bit integer value
****
--
[[interfaces-builtin-variables-warpidarm]]
[open,refpage='WarpIDARM',desc='Warp ID within a core of a shader invocation',type='builtins']
--
:refpage: WarpIDARM
code:WarpIDARM::
Decorating a variable with the code:WarpIDARM built-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 [eq]#[0, code:WarpMaxIDARM]#.
.Valid Usage
****
* [[VUID-{refpage}-WarpIDARM-07603]]
The variable decorated with code:WarpIDARM must: be declared using the
code:Input {StorageClass}
* [[VUID-{refpage}-WarpIDARM-07604]]
The variable decorated with code:WarpIDARM must: be declared as a scalar
32-bit integer value
****
--
endif::VK_ARM_shader_core_builtins[]
ifdef::VK_AMDX_shader_enqueue[]
[[interfaces-builtin-variables-coalescedinputcountamd]]
[open,refpage='CoalescedInputCountAMDX',desc='Number of inputs coalesced for a coalescing node in a work graph',type='builtins']
--
:refpage: CoalescedInputCountAMDX
code:CoalescedInputCountAMDX::
Decorating a variable with the code:CoalescedInputCountAMDX built-in
decoration will make that variable contain the number of node dispatches
that the implementation coalesced into the input for the current shader.
This variable will take a value in the range [eq]#[1, arraySize)#, where
[eq]#arraySize# is the maximum size of the input payload array for the
shader.
.Valid Usage
****
* [[VUID-{refpage}-CoalescedInputCountAMDX-09172]]
The variable decorated with code:CoalescedInputCountAMDX must: be
declared using the code:Input {StorageClass}
* [[VUID-{refpage}-CoalescedInputCountAMDX-09173]]
If a variable is decorated with code:CoalescedInputCountAMDX, the
code:CoalescingAMDX execution mode must: be declared
* [[VUID-{refpage}-CoalescedInputCountAMDX-09174]]
The variable decorated with code:CoalescedInputCountAMDX must: be
declared as a scalar 32-bit integer value
****
--
[open,refpage='ShaderIndexAMDX',desc='Index assigned to the shader within the workgraph',type='builtins']
--
:refpage: ShaderIndexAMDX
code:ShaderIndexAMDX::
Decorating a variable with the code:ShaderIndexAMDX built-in decoration will
make that variable contain the index of the shader specified when it was
compiled, either via slink:VkPipelineShaderStageNodeCreateInfoAMDX::index or
by the code:ShaderIndexAMDX execution mode.
.Valid Usage
****
* [[VUID-{refpage}-ShaderIndexAMDX-09175]]
The variable decorated with code:ShaderIndexAMDX must: be declared using
the code:Input {StorageClass}
* [[VUID-{refpage}-ShaderIndexAMDX-09176]]
The variable decorated with code:ShaderIndexAMDX must: be declared as a
scalar 32-bit integer value
****
--
endif::VK_AMDX_shader_enqueue[]