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 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 fragment, 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.
Any variable decorated with PrimitiveId must be declared as 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 \times 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 theglobal 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.