Built-in variables are accessed in shaders by declaring a variable decorated
with a BuiltIn
decoration.
The meaning of each BuiltIn
decoration is as follows.
In the remainder of this section, the name of a built-in is used
interchangeably with a term equivalent to a variable decorated with that
particular built-in.
Built-ins that represent integer values can be declared as either signed or
unsigned 32-bit integers.
ClipDistance
Decorating a variable with the ClipDistance
built-in decoration will
make that variable contain the mechanism for controlling user clipping.
ClipDistance
is an array such that the ith element of the array
specifies the clip distance for plane i.
A clip distance of 0 means the vertex is on the plane, a positive distance
means the vertex is inside the clip half-space, and a negative distance
means the point is outside the clip half-space.
The ClipDistance
decoration must be used only within vertex, fragment,
tessellation control, tessellation evaluation, and geometry shaders.
In vertex shaders, any variable decorated with ClipDistance
must be
declared using the Output
storage class.
In fragment shaders, any variable decorated with ClipDistance
must be
declared using the Input
storage class.
In tessellation control, tessellation evaluation, or geometry shaders, any
variable decorated with ClipDistance
must not be in a storage class
other than Input
or Output
.
Any variable decorated with ClipDistance
must be declared as an array
of 32-bit floating-point values.
![]() | Note |
---|---|
The array variable decorated with |
![]() | Note |
---|---|
In the last vertex processing 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 |
CullDistance
Decorating a variable with the CullDistance
built-in decoration will
make that variable contain the mechanism for controlling user culling.
If any member of this array is assigned a negative value for all vertices
belonging to a primitive, then the primitive is discarded before
rasterization.
The CullDistance
decoration must be used only within vertex, fragment,
tessellation control, tessellation evaluation, and geometry shaders.
In vertex shaders, any variable decorated with CullDistance
must be
declared using the Output
storage class.
In fragment shaders, any variable decorated with CullDistance
must be
declared using the Input
storage class.
In tessellation control, tessellation evaluation, or geometry shaders, any
variable decorated with CullDistance
must not be declared in a storage
class other than input or output.
Any variable decorated with CullDistance
must be declared as an array
of 32-bit floating-point values.
![]() | Note |
---|---|
In fragment shaders, the values of the |
![]() | Note |
---|---|
If |
FragCoord
Decorating a variable with the FragCoord
built-in decoration will make
that variable contain the framebuffer coordinate
$(x,y,z,\frac{1}{w})$
of the fragment being processed.
The (x,y) coordinate (0,0) is the upper left corner of the upper
left pixel in the framebuffer.
When sample shading is enabled, the x and y components of
FragCoord
reflect the location of the sample corresponding to the
shader invocation.
When sample shading is not enabled, the x and y components of FragCoord
reflect the location of the center of the pixel, (0.5,0.5).
The z component of FragCoord
is the interpolated depth value of
the primitive.
The w component is the interpolated $\frac{1}{w}$ .
The FragCoord
decoration must be used only within fragment shaders.
The variable decorated with FragCoord
must be declared using the
Input
storage class.
The Centroid
interpolation decoration is ignored on FragCoord
.
The variable decorated with FragCoord
must be declared as a
four-component vector of 32-bit floating-point values.
FragDepth
Decorating a variable with the FragDepth
built-in decoration will make
that variable contain the new depth value for all samples covered by the
fragment.
This value will be used for depth testing and, if the depth test passes, any
subsequent write to the depth/stencil attachment.
To write to FragDepth
, a shader must declare the DepthReplacing
execution mode.
If a shader declares the DepthReplacing
execution mode and there is an
execution path through the shader that does not set FragDepth
, then the
fragment’s depth value is undefined for executions of the shader that take
that path.
The FragDepth
decoration must be used only within fragment shaders.
The variable decorated with FragDepth
must be declared using the
Output
storage class.
The variable decorated with FragDepth
must be declared as a scalar
32-bit floating-point value.
FrontFacing
Decorating a variable with the FrontFacing
built-in decoration will
make that variable contain whether a primitive is front or back facing.
This variable is non-zero if the current fragment is considered to be part
of a front-facing primitive and is zero if the
fragment is considered to be part of a back-facing primitive.
The FrontFacing
decoration must be used only within fragment shaders.
The variable decorated with FrontFacing
must be declared using the
Input
storage class.
The variable decorated with FrontFacing
must be declared as a boolean.
GlobalInvocationId
Decorating a variable with the GlobalInvocationId
built-in decoration
will make that variable contain the location of the current invocation
within the global workgroup.
Each component is equal to the index of the local workgroup multiplied by
the size of the local workgroup plus LocalInvocationId
.
The GlobalInvocationId
decoration must be used only within compute
shaders.
The variable decorated with GlobalInvocationId
must be declared using
the Input
storage class.
The variable decorated with GlobalInvocationId
must be declared as a
three-component vector of 32-bit integers.
HelperInvocation
Decorating a variable with the HelperInvocation
built-in decoration
will make that variable contain whether the current invocation is a helper
invocation.
This variable is non-zero if the current fragment being shaded is a helper
invocation and zero otherwise.
A helper invocation is an invocation of the shader that is produced to
satisfy internal requirements such as the generation of derivatives.
The HelperInvocation
decoration must be used only within fragment
shaders.
The variable decorated with HelperInvocation
must be declared using
the Input
storage class.
The variable decorated with HelperInvocation
must be declared as a
boolean.
![]() | Note |
---|---|
It is very likely that a helper invocation will have a value of
|
InvocationId
Decorating a variable with the InvocationId
built-in decoration will
make that variable contain the index of the current shader invocation in a
geometry shader, or the index of the output patch vertex in a tessellation
control shader.
In a geometry shader, the index of the current shader invocation ranges from
zero to the number of instances declared in the
shader minus one.
If the instance count of the geometry shader is one or is not specified,
then InvocationId
will be zero.
The InvocationId
decoration must be used only within tessellation
control and geometry shaders.
The variable decorated with InvocationId
must be declared using the
Input
storage class.
The variable decorated with InvocationId
must be declared as a scalar
32-bit integer.
InstanceIndex
Decorating a variable with the InstanceIndex
built-in decoration will
make that variable contain the index of the instance that is being processed
by the current vertex shader invocation.
InstanceIndex
begins at the firstInstance
parameter to
vkCmdDraw
or vkCmdDrawIndexed
or at the firstInstance
member of a structure consumed by vkCmdDrawIndirect
or
vkCmdDrawIndexedIndirect
.
The InstanceIndex
decoration must be used only within vertex shaders.
The variable decorated with InstanceIndex
must be declared using the
Input
storage class.
The variable decorated with InstanceIndex
must be declared as a scalar
32-bit integer.
Layer
Decorating a variable with the Layer
built-in decoration will make that
variable contain the select layer of a multi-layer framebuffer attachment.
In a geometry shader, any variable decorated with Layer
can be written
with the framebuffer layer index to which the primitive produced by the
geometry shader will be directed.
If a geometry shader entry point’s interface does not include a variable
decorated with Layer
, then the first layer is used.
If a geometry shader entry point’s interface includes a variable decorated
with Layer
, it must write the same value to Layer
for all output
vertices of a given primitive.
In a fragment shader, a variable decorated with Layer
contains the
layer index of the primitive that the fragment invocation belongs to.
The Layer
decoration must be used only within geometry and fragment
shaders.
In a geometry shader, any variable decorated with Layer
must be
declared using the Output
storage class.
In a fragment shader, any variable decorated with Layer
must be
declared using the Input
storage class.
Any variable decorated with Layer
must be declared as a scalar 32-bit
integer.
LocalInvocationId
Decorating a variable with the LocalInvocationId
built-in decoration
will make that variable contain the location of the current compute shader
invocation within the local workgroup.
Each component ranges from zero through to the size of the workgroup in that
dimension minus one.
The LocalInvocationId
decoration must be used only within compute
shaders.
The variable decorated with LocalInvocationId
must be declared using
the Input
storage class.
The variable decorated with LocalInvocationId
must be declared as a
three-component vector of 32-bit integers.
![]() | Note |
---|---|
If the size of the workgroup in a particular dimension is one, then the
|
NumWorkgroups
Decorating a variable with the NumWorkgroups
built-in decoration will
make that variable contain the number of local workgroups that are part of
the dispatch that the invocation belongs to.
Each component is equal to the values of the parameters passed into
vkCmdDispatch
or read from the VkDispatchIndirectCommand
structure read through a call to vkCmdDispatchIndirect
.
The NumWorkgroups
decoration must be used only within compute shaders.
The variable decorated with NumWorkgroups
must be declared using the
Input
storage class.
The variable decorated with NumWorkgroups
must be declared as a
three-component vector of 32-bit integers.
PatchVertices
Decorating a variable with the PatchVertices
built-in decoration will
make that variable contain the number of vertices in the input patch being
processed by the shader.
A single tessellation control or tessellation evaluation shader can read
patches of differing sizes, so the value of the PatchVertices
variable
may differ between patches.
The PatchVertices
decoration must be used only within tessellation
control and tessellation evaluation shaders.
The variable decorated with PatchVertices
must be declared using the
Input
storage class.
The variable decorated with PatchVertices
must be declared as a scalar
32-bit integer.
PointCoord
Decorating a variable with the PointCoord
built-in decoration will make
that variable contain the coordinate of the current fragment within the
point being rasterized, normalized to the size of the point with origin in
the upper left corner of the point, as described in
Basic Point Rasterization.
If the primitive the fragment shader invocation belongs to is not a point,
then the variable decorated with PointCoord
contains an undefined
value.
The PointCoord
decoration must be used only within fragment shaders.
The variable decorated with PointCoord
must be declared using the
Input
storage class.
The variable decorated with PointCoord
must be declared as
two-component vector of 32-bit floating-point values.
![]() | Note |
---|---|
Depending on how the point is rasterized, |
PointSize
Decorating a variable with the PointSize
built-in decoration will make
that variable contain the size of point primitives.
The value written to the variable decorated with PointSize
by the last
vertex processing stage in the pipeline is used as the framebuffer-space
size of points produced by rasterization.
The PointSize
decoration must be used only within vertex, tessellation
control, tessellation evaluation, and geometry shaders.
In a vertex shader, any variable decorated with PointSize
must be
declared using the Output
storage class.
In a tessellation control, tessellation evaluation, or geometry shader, any
variable decorated with PointSize
must be declared using either the
Input
or Output
storage class.
Any variable decorated with PointSize
must be declared as a scalar
32-bit floating-point value.
![]() | Note |
---|---|
When |
Position
Decorating a variable with the Position
built-in decoration will make
that variable contain the position of the current vertex.
In the last vertex processing stage, the value of the variable decorated
with Position
is used in subsequent primitive assembly, clipping, and
rasterization operations.
The Position
decoration must be used only within vertex, tessellation
control, tessellation evaluation, and geometry shaders.
In a vertex shader, any variable decorated with Position
must be
declared using the Output
storage class.
In a tessellation control, tessellation evaluation, or geometry shader, any
variable decorated with Position
must not be declared in a storage
class other than input or output.
Any variable decorated with Position
must be declared as a
four-component vector of 32-bit floating-point values.
![]() | Note |
---|---|
When |
PrimitiveId
Decorating a variable with the PrimitiveId
built-in decoration will
make that variable contain the index of the current primitive.
In tessellation control and tessellation evaluation shaders, it will contain the index of the patch within the current set of rendering primitives that correspond to the shader invocation.
In a geometry shader, it will contain the number of primitives presented as input to the shader since the current set of rendering primitives was started.
In a fragment shader, it will contain the primitive index written by the geometry shader if a geometry shader is present, or with the value that would have been presented as input to the geometry shader had it been present.
If a geometry shader is present and the fragment shader reads from an input
variable decorated with PrimitiveId
, then the geometry shader must
write to an output variable decorated with PrimitiveId
in all execution
paths.
The PrimitiveId
decoration must be used only within fragment,
tessellation control, tessellation evaluation, and geometry shaders.
In a tessellation control or tessellation evaluation shader, any variable
decorated with PrimitiveId
must be declared using the Output
storage class.
In a geometry shader, any variable decorated with PrimitiveId
must be
declared using either the Input
or Output
storage class.
In a fragment shader, any variable decorated with PrimitiveId
must be
declared using the Input
storage class, and either the Geometry
or
Tessellation
capability must also be declared.
Any variable decorated with PrimitiveId
must be declared as a scalar
32-bit integer.
![]() | Note |
---|---|
When the |
SampleId
Decorating a variable with the SampleId
built-in decoration will make
that variable contain the zero-based index of the sample the invocation
corresponds to.
SampleId
ranges from zero to the number of samples in the framebuffer
minus one.
If a fragment shader entry point’s interface includes an input variable
decorated with SampleId
, per-sample shading is enabled for draws that
use that fragment shader.
The SampleId
decoration must be used only within fragment shaders.
The variable decorated with SampleId
must be declared using the
Input
storage class.
The variable decorated with SampleId
must be declared as a scalar
32-bit integer.
SampleMask
Decorating a variable with the SampleMask
built-in decoration will make
any variable contain the sample coverage mask for the current fragment
shader invocation.
A variable in the Input
storage class decorated with SampleMask
will contain a bitmask of the set of samples covered by the primitive
generating the fragment during rasterization.
It has a sample bit set if and only if the sample is considered covered for
this fragment shader invocation.
SampleMask
[] is an array of integers.
Bits are mapped to samples in a manner where bit B of mask M
(SampleMask[M]
) corresponds to sample 32 × M + B.
When state specifies multiple fragment shader invocations for a given fragment, the sample mask for any single fragment shader invocation specifies the subset of the covered samples for the fragment that correspond to the invocation. In this case, the bit corresponding to each covered sample will be set in exactly one fragment shader invocation.
A variable in the Output
storage class decorated with SampleMask
is an array of integers forming a bit array in a manner similar an input
variable decorated with SampleMask
, but where each bit represents
coverage as computed by the shader.
Modifying the sample mask by writing zero to a bit of SampleMask
causes
the sample to be considered uncovered.
However, setting sample mask bits to one will never enable samples not
covered by the original primitive.
If the fragment shader is being evaluated at any frequency other than
per-fragment, bits of the sample mask not corresponding to the current
fragment shader invocation are ignored.
This array must be sized in the fragment shader either implicitly or
explicitly, to be no larger than the implementation-dependent maximum
sample-mask (as an array of 32-bit elements), determined by the maximum
number of samples.
If a fragment shader entry point’s interface includes an output variable
decorated with SampleMask
, the sample mask will be undefined for any
array elements of any fragment shader invocations that fail to assign a
value.
If a fragment shader entry point’s interface does not include an output
variable decorated with SampleMask
, the sample mask has no effect on
the processing of a fragment.
The SampleMask
decoration must be used only within fragment shaders.
Any variable decorated with SampleMask
must be declared using either
the Input
or Output
storage class.
Any variable decorated with SampleMask
must be declared as an array of
32-bit integers.
SamplePosition
Decorating a variable with the SamplePosition
built-in decoration will
make that variable contain the sub-pixel position of the sample being
shaded.
The top left of the pixel is considered to be at coordinate (0,0) and
the bottom right of the pixel is considered to be at coordinate (1,1).
If a fragment shader entry point’s interface includes an input variable
decorated with SamplePosition
, per-sample shading is enabled for draws
that use that fragment shader.
The SamplePosition
decoration must be used only within fragment
shaders.
The variable decorated with SamplePosition
must be declared using the
Input
storage class.
The variable decorated with SamplePosition
must be declared as a
two-component vector of 32-bit floating-point values.
TessCoord
Decorating a variable with the TessCoord
built-in decoration will make
that variable contain the three-dimensional (u,v,w) barycentric
coordinate of the tessellated vertex within the patch.
u, v, and w are in the range [0,1] and vary linearly
across the primitive being subdivided.
For the tessellation modes of Quads
or IsoLines
, the third
component is always zero.
The TessCoord
decoration must be used only within tessellation
evaluation shaders.
The variable decorated with TessCoord
must be declared using the
Input
storage class.
The variable decorated with TessCoord
must be declared as
three-component vector of 32-bit floating-point values.
TessLevelOuter
Decorating a variable with the TessLevelOuter
built-in decoration will
make that variable contain the outer tessellation levels for the current
patch.
In tessellation control shaders, the variable decorated with
TessLevelOuter
can be written to which controls the tessellation
factors for the resulting patch.
These values are used by the tessellator to control primitive tessellation
and can be read by tessellation evaluation shaders.
In tessellation evaluation shaders, the variable decorated with
TessLevelOuter
can read the values written by the tessellation control
shader.
The TessLevelOuter
decoration must be used only within tessellation
control and tessellation evaluation shaders.
In a tessellation control shader, any variable decorated with
TessLevelOuter
must be declared using the Output
storage class.
In a tessellation evaluation shader, any variable decorated with
TessLevelOuter
must be declared using the Input
storage class.
Any variable decorated with TessLevelOuter
must be declared as an
array of size four, containing 32-bit floating-point values.
TessLevelInner
Decorating a variable with the TessLevelInner
built-in decoration will
make that variable contain the inner tessellation levels for the current
patch.
In tessellation control shaders, the variable decorated with
TessLevelInner
can be written to, which controls the tessellation
factors for the resulting patch.
These values are used by the tessellator to control primitive tessellation
and can be read by tessellation evaluation shaders.
In tessellation evaluation shaders, the variable decorated with
TessLevelInner
can read the values written by the tessellation control
shader.
The TessLevelInner
decoration must be used only within tessellation
control and tessellation evaluation shaders.
In a tessellation control shader, any variable decorated with
TessLevelInner
must be declared using the Output
storage class.
In a tessellation evaluation shader, any variable decorated with
TessLevelInner
must be declared using the Input
storage class.
Any variable decorated with TessLevelInner
must be declared as an
array of size two, containing 32-bit floating-point values.
VertexIndex
Decorating a variable with the VertexIndex
built-in decoration will
make that variable contain the index of the vertex that is being processed
by the current vertex shader invocation.
For non-indexed draws, this variable begins at the firstVertex
parameter to vkCmdDraw
or the firstVertex
member of a structure
consumed by vkCmdDrawIndirect
and increments by one for each vertex in
the draw.
For indexed draws, its value is the content of the index buffer for the
vertex plus the vertexOffset
parameter to vkCmdDrawIndexed
or
the vertexOffset
member of the structure consumed by
vkCmdDrawIndexedIndirect
.
The VertexIndex
decoration must be used only within vertex shaders.
The variable decorated with VertexIndex
must be declared using the
Input
storage class.
The variable decorated with VertexIndex
must be declared as a scalar
32-bit integer.
![]() | Note |
---|---|
|
ViewportIndex
Decorating a variable with the ViewportIndex
built-in decoration will
make that variable contain the index of the viewport.
In a geometry shader, the variable decorated with ViewportIndex
can be
written to with the viewport index to which the primitive produced by the
geometry shader will be directed.
The selected viewport index is used to select the viewport transform and
scissor rectangle.
If a geometry shader entry point’s interface does not include a variable
decorated with ViewportIndex
, then the first viewport is used.
If a geometry shader entry point’s interface includes a variable decorated
with ViewportIndex
, it must write the same value to ViewportIndex
for all output vertices of a given primitive.
In a fragment shader, the variable decorated with ViewportIndex
contains the viewport index of the primitive that the fragment invocation
belongs to.
The ViewportIndex
decoration must be used only within geometry and
fragment shaders.
In a geometry shader, any variable decorated with ViewportIndex
must
be declared using the Output
storage class.
In a fragment shader, any variable decorated with ViewportIndex
must
be declared using the Input
storage class.
Any variable decorated with ViewportIndex
must be declared as a scalar
32-bit integer.
WorkgroupId
Decorating a variable with the WorkgroupId
built-in decoration will
make that variable contain the global workgroup that the current invocation
is a member of.
Each component ranges from zero to the values of the parameters passed into
vkCmdDispatch
or read from the VkDispatchIndirectCommand
structure read through a call to vkCmdDispatchIndirect
.
The WorkgroupId
decoration must be used only within compute shaders.
The variable decorated with WorkgroupId
must be declared using the
Input
storage class.
The variable decorated with WorkgroupId
must be declared as a
three-component vector of 32-bit integers.
WorkgroupSize
Decorating a variable with the WorkgroupSize
built-in decoration will
make that variable contain the dimensions of a local workgroup.
If an object is decorated with the WorkgroupSize
decoration, this must
take precedence over any execution mode set for LocalSize
.
The WorkgroupSize
decoration must be used only within compute shaders.
The object decorated with WorkgroupSize
must be a specialization
constant or a constant.
The object decorated with WorkgroupSize
must be declared as a
three-component vector of 32-bit integers.