## 14.6. Built-In Variables

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 `ClipDistance` is explicitly sized by the shader.

| 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 `ClipDistance` is then used by a fragment shader, `ClipDistance` contains these linearly interpolated values.

`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 `CullDistance` array are linearly interpolated across each primitive.

| Note
If `CullDistance` decorates an input variable, that variable will contain the corresponding value from the `CullDistance` decorated output variable from the previous shader stage.

`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 `SampleMask` fragment shader input value that is zero.

`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 `LocalInvocationId` in that dimension will be zero. If the workgroup is effectively two-dimensional, then `LocalInvocationId`.z will be zero. If the workgroup is effectively one-dimensional, then both `LocalInvocationId`.y and `LocalInvocationId`.z will be zero.

`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, `PointCoord` may never reach $(0,0)$ or $(1,1)$ .

`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 `PointSize` decorates a variable in the input storage class, it contains the data written to the output variable decorated with `PointSize` from the previous shader stage.

`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 `Position` decorates a variable in the input storage class, it contains the data written to the output variable decorated with `Position` from the previous shader stage.

`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 `PrimitiveId` decoration is applied to an output variable in the geometry shader, the resulting value is seen through the `PrimitiveId` decorated input variable in the fragment shader.

`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
`VertexIndex` starts at the same starting value for each instance.

`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.