Built-in variables are accessed in shaders by declaring a variable decorated
using 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
Variables decorated with the ClipDistance decoration provide the
mechanism for controlling user clipping. Declared as an array, the ith
element of the variable decorated as ClipDistance specifies a 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 array is explicitly sized by the shader.
The ClipDistance decoration can be applied to array inputs in
tessellation control, tessellation evaluation and geometry shader stages
which will contain the values written by the previous stage. It can be
applied to outputs in vertex, tessellation evaluation and geometry shaders.
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.
In the fragment shader, the ClipDistance decoration can be applied to
an array of floating-point input variables and contains the linearly
interpolated values described above.
ClipDistance must not be used in compute shaders.
ClipDistance must be declared as an array of 32-bit floating-point
values.
CullDistance
A variable decorated as CullDistance provides a mechanism for a vertex
processing stage to reject an entire primitive. CullDistance can be
applied to an array variable. 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. CullDistance can be applied to an
output variable in the last vertex processing stage (vertex, tessellation
evaluation or geometry shader).
If applied to an input variable, that variable will contain the
corresponding output in the previous shader stage. CullDistance
must not be applied to an input in the vertex shader or to an output in the
fragment shader, and must not be used in compute shaders.
In fragment shaders, the values of the CullDistance array are linearly
interpolated across each primitive.
CullDistance must be declared as an array of 32-bit floating-point
values.
FragCoord
This variable contains 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. The x and y components of FragCoord reflect
the location of the center of the pixel
(
$(0.5,0.5)$
) when sample shading is not enabled, and the
location of the sample corresponding to the shader invocation when using
sample shading.
The z component of FragCoord is the interpolated depth value of the
primitive, and the w component is the interpolated
$\frac{1}{w}$
.
The FragCoord decoration must be used only within fragment shaders. The
Centroid interpolation decoration is ignored on FragCoord.
FragCoord must be declared as a four-component vector of 32-bit
floating-point values.
FragDepth
Writing to an output variable decorated with FragDepth from the
fragment shader establishes a 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.
FragDepth must be declared as a scalar 32-bit floating-point value.
FrontFacing
The FrontFacing decoration can be applied to an input variable in the
fragment shader. 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 is not available to shader stages other than
fragment.
FrontFacing must be declared as a scalar 32-bit integer.
| Note | |
|---|---|
In GLSL, |
GlobalInvocationId
The GlobalInvocationId built-in decoration can be applied to a variable
that represents 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 unsigned integers.
HelperInvocation
This variable is non-zero if the 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.
HelperInvocation must be declared as a scalar 32-bit integer.
| Note | |
|---|---|
It is very likely that a helper invocation will have a value of
|
| Note | |
|---|---|
In GLSL, |
InvocationId
In a geometry shader, an input variable decorated with the InvocationId
decoration contains the index of the current shader invocation, which 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.
In tessellation control shaders, and input variable decorated with the
InvocationId decoration contains the index of the output patch vertex
assigned to the tessellation control shader invocation.
The InvocationId decoration must not be used in vertex, tessellation
evaluation, fragment, or compute shaders.
InvocationId must be declared as a scalar 32-bit integer.
InstanceIndex
The InstanceIndex decoration can be applied to a vertex shader input
which will be filled with 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 not be used in any shader stage other
than vertex.
InstanceIndex must be declared as a scalar 32-bit integer.
Layer
The Layer decoration can be applied to an output variable in the
geometry shader that is 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 an output variable
decorated with Layer, then the first layer is used. If a geometry
shader entry point’s interface includes an output variable decorated with
Layer, it must write the same value to Layer for all output
vertices of a given primitive. When used in a fragment shader, an input
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.
Layer must be declared as a scalar 32-bit integer.
LocalInvocationId
The LocalInvocationId built-in decoration can be applied to a variable
that represents 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 unsigned integers.
| Note | |
|---|---|
If the size of the workgroup in a particular dimension is one, then the
|
NumWorkgroups
The NumWorkgroups built-in decoration can be applied to a variable that
represents 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
An input variable decorated with PatchVertices in the tessellation
control or evaluation shader is an integer specifying the number of
vertices in the input patch being processed by the shader. A single
tessellation control or evaluation shader can read patches of differing
sizes, so the PatchVertices variable may differ between patches.
The PatchVertices decoration must be used only within tessellation
control and evaluation shaders.
PatchVertices must be declared as scalar 32-bit integer.
PointCoord
During point rasterization, a variable decorated with PointCoord
contains 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 PointCoord is undefined.
The PointCoord decoration must be used only within fragment shaders.
PointCoord must be declared as two-component vector of 32-bit
floating-point values.
| Note | |
|---|---|
Depending on how the point is rasterized, |
PointSize
The PointSize built-in decoration is used to pass the size of point
primitives between shader stages. It can be applied to inputs to
tessellation control and geometry shaders. It can be applied to output
variables in vertex, tessellation evaluation and geometry shaders. The value
written to the variable decorated as PointSize by the last vertex
processing stage in the pipeline is used as the framebuffer space size of
points produced by rasterization. As an input, it reflects the value written
to the output decorated with PointSize in the previous shader stage.
The PointSize decoration must not be applied to inputs in the vertex
shader and must not be used in fragment or compute shaders.
PointSize must be declared as a scalar 32-bit floating-point value.
Position
The Position built-in decoration can be used on variables declared as
input to tessellation control, tessellation evaluation and geometry shaders.
It can be used on variables declared as outputs in the vertex, tessellation
control, tessellation evaluation and geometry shaders. As an input, it
contains the data written to the output variable decorated as Position
in the previous shader stage. As an output, the data written to a variable
decorated as Position is passed to the next shader stage. In the last
vertex processing stage, the output position is used in subsequent primitive
assembly, clipping and rasterization operations.
Variables decorated as Position must not be used as inputs in vertex
shaders and must not be used in fragment or compute shaders.
Position must be declared as a four-component vector of 32-bit
floating-point values.
PrimitiveId
When the PrimitiveId decoration is applied to an input variable in the
tessellation control or tessellation evaluation shader, it will be filled
with the index of the patch within the current set of rendering primitives
that corresponds to the shader invocation.
When the PrimitiveId decoration is applied to an input variable in the
geometry shader, it will be filled with the number of primitives presented
as input to the geometry shader since the current set of rendering
primitives was started. When PrimitiveId is applied to an output in the
geometry shader, the resulting value is seen as an input to the fragment
shader.
When PrimitiveId is applied to an input in the fragment shader, it will
be filled with 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; otherwise the
PrimitiveId input in the fragment shader is undefined.
The PrimitiveId decoration must not be used in vertex or compute
shaders. PrimitiveId must not be used on output variables in
tessellation control, tessellation evaluation, or fragment shaders.
PrimitiveId must be declared as scalar 32-bit integer.
SampleId
The SampleId decoration can be applied to an integer input variable in
the fragment shader. This variable will 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.
SampleId is not available in shader stages other than fragment.
SampleId must be declared as a scalar 32-bit integer.
SampleMask
A fragment input variable 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 fragment output variable 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.
SampleMask must be declared as an array of 32-bit integers.
SamplePosition
This variable contains 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.
SamplePosition must be declared as a two-component vector of
floating-point values.
TessCoord
The TessCoord is applied to an input variable in tessellation
evaluation shaders and specifies 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.
TessCoord must be declared as three-component vector of 32-bit
floating-point values.
TessLevelOuter
The TessLevelOuter decoration is used in tessellation control
shaders to decorate an output variable to contain the outer 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. When applied to an input variable in a
tessellation evaluation shader, the shader can read the values written by
the tessellation control shader.
The TessLevelOuter decoration must be used only within
tessellation control and evaluation shaders.
TessLevelOuter must be declared as an array of size four,
containing 32-bit floating-point values.
TessLevelInner
The TessLevelInner decoration is used in tessellation control
shaders to decorate an output variable to contain the inner 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. When applied to an input variable in a
tessellation evaluation shader, the shader can read the values written by
the tessellation control shader.
The TessLevelInner decoration must be used only within
tessellation control and evaluation shaders.
TessLevelInner must be declared as an array of size two,
containing 32-bit floating-point values.
VertexIndex
The VertexIndex decoration can be applied to a vertex shader input
which will be filled with 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.
VertexIndex starts at the same starting value for each instance.
The VertexIndex decoration must be used only within vertex shaders.
VertexIndex must be declared as a 32-bit integer.
ViewportIndex
The ViewportIndex decoration can be applied to an output variable in
the geometry shader that is written 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 an
output variable decorated with ViewportIndex, then the first viewport
is used. If a geometry shader entry point’s interface includes an output
variable decorated with ViewportIndex, it must write the same value to
ViewportIndex for all output vertices of a given primitive. When used
in a fragment shader, an input 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.
ViewportIndex must be declared as a 32-bit integer.
WorkgroupId
The WorkgroupId built-in decoration can be applied to a variable that
represents 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 unsigned integers.
WorkgroupSize
The WorkgroupSize built-in decoration can be applied to an object that
represents 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 unsigned integers.