Built-In Variables

The built-in vertex shader variables are intrinsically declared as follows:

The variable gl_Position is intended for writing the homogeneous vertex position. It can be written at any time during shader execution. This value will be used by primitive assembly, clipping, culling, and other fixed functionality operations, if present, that operate on primitives after vertex processing has occurred. Its value is undefined after the vertex processing stage if the vertex shader executable does not write gl_Position.

The variable gl_PointSize is intended for a shader to write the size of the point to be rasterized. It is measured in pixels. If gl_PointSize is not written to, its value is undefined in subsequent pipe stages.

The variable gl_ClipDistance is intended for writing clip distances, and provides the forward compatible mechanism for controlling user clipping. The element gl_ClipDistance[i] specifies a clip distance for each half-space i. A distance of 0 means the vertex is on the boundary of the half-space, a positive distance means the vertex is inside the clip volume, and a negative distance means the point is outside the clip volume. The clip distances will be linearly interpolated across the primitive and the portion of the primitive with interpolated distances less than 0 will be clipped.

The gl_ClipDistance array is predeclared as unsized and must be either explicitly sized by the shader redeclaring it with a size or implicitly sized by indexing it only with constant integral expressions. This needs to size the array to include all the clip half-spaces that are enabled via the API; if the size does not include all enabled half-spaces, results are undefined. The size can be at most gl_MaxClipDistances. The number of varying components (see gl_MaxVaryingComponents) consumed by gl_ClipDistance will match the size of the array, no matter how many half-spaces are enabled. The shader must also set all values in gl_ClipDistance that have been enabled via the API, or results are undefined. Values written into gl_ClipDistance for half-spaces that are not enabled have no effect.

The variable gl_CullDistance provides a mechanism for controlling user culling. The element gl_CullDistance[i] specifies a cull distance for half-space i. A distance of 0 means the vertex is on the boundary of the half-space, a positive distance means the vertex is inside the cull volume, and a negative distance means the point is outside the cull volume. Primitives whose vertices all have a negative cull distance for half-spaces i will be discarded.

The gl_CullDistance array is predeclared as unsized and must be either explicitly sized by the shader redeclaring it with a size or implicitly sized by indexing it only with constant integral expressions. The size determines the number and set of enabled cull distances and can be at most gl_MaxCullDistances. The number of varying components (see gl_MaxVaryingComponents) consumed by gl_CullDistance will match the size of the array. Shaders writing gl_CullDistance must write all enabled distances, or culling results are undefined.

As an output variable, gl_CullDistance provides the place for the shader to write these distances. As an input in all but the fragment language, it reads the values written in the previous shader stage. In the fragment language, gl_CullDistance array contains linearly interpolated values for the vertex values written by a shader to the gl_CullDistance vertex output variable.

It is a compile-time or link-time error for the set of shaders forming a program to have the sum of the sizes of the gl_ClipDistance and gl_CullDistance arrays to be larger than gl_MaxCombinedClipAndCullDistances.

The variable gl_VertexID is a vertex shader input variable that holds an integer index for the vertex, as defined under “Shader Inputs” in section 11.1.3.9 “Shader Inputs” of the OpenGL Specification. It is only present when not targeting Vulkan. Even when present, the value of gl_VertexID is not always defined.

The variable gl_InstanceID is a vertex shader input variable that holds the instance number of the current primitive in an instanced draw call (see “Shader Inputs” in section 11.1.3.9 “Shader Inputs” of the OpenGL Specification). It is only present when not targeting Vulkan. If the current primitive does not come from an instanced draw call, the value of gl_InstanceID is zero.

The variable gl_VertexIndex is a vertex language input variable that holds an integer index for the vertex, relative to a base. It is only present when targeting Vulkan. Even when present, the value of gl_VertexIndex is not always defined.

The variable gl_InstanceIndex is a vertex language input variable that holds the instance number of the current primitive in an instanced draw call, relative to a base. It is only present when targeting Vulkan. If the current primitive does not come from an instanced draw call, the value of gl_InstanceIndex is zero.

The variable gl_DrawID is a vertex shader input variable that holds the integer index of the drawing command to which the current vertex belongs (see “Shader Inputs” in section 11.1.3.9 of the OpenGL Specification). If the vertex is not invoked by a Multi* form of a draw command, then the value of gl_DrawID is zero.

The variable gl_BaseVertex is a vertex shader input variable that holds the integer value passed to the baseVertex parameter of the command that resulted in the current shader invocation (see “Shader Inputs” in section 11.1.3.9 of the OpenGL Specification).

The variable gl_BaseInstance is a vertex shader input variable that holds the integer value passed to the baseInstance parameter of the command that resulted in the current shader invocation (see “Shader Inputs” in section 11.1.3.9 of the OpenGL Specification).

In the tessellation control shader, built-in variables are intrinsically declared as:

In the tessellation evaluation shader, built-in variables are intrinsically declared as:

In the geometry shader, built-in variables are intrinsically declared as:

The built-in special variables that are accessible from a fragment shader are intrinsically declared as follows:

The output of the fragment shader executable is processed by the fixed function operations at the back end of the API pipeline.

The fixed functionality computed depth for a fragment may be obtained by reading gl_FragCoord.z, described below.

Writing to gl_FragDepth will establish the depth value for the fragment being processed. If depth buffering is enabled, and no shader writes gl_FragDepth, then the fixed function value for depth will be used as the fragment’s depth value. If a shader statically assigns a value to gl_FragDepth, and there is an execution path through the shader that does not set gl_FragDepth, then the value of the fragment’s depth may be undefined for executions of the shader that take that path. That is, if the set of linked fragment shaders statically contain a write to gl_FragDepth, then it is responsible for always writing it.

If a shader executes the discard keyword, the fragment is discarded, and the values of any user-defined fragment outputs, gl_FragDepth, and gl_SampleMask become irrelevant.

The variable gl_FragCoord is available as an input variable from within fragment shaders and it holds the window relative coordinates (x, y, z, 1/w) values for the fragment. If multi-sampling, this value can be for any location within the pixel, or one of the fragment samples. The use of centroid does not further restrict this value to be inside the current primitive. This value is the result of the fixed functionality that interpolates primitives after vertex processing to generate fragments. The z component is the depth value that would be used for the fragment’s depth if no shader contained any writes to gl_FragDepth. This is useful for invariance if a shader conditionally computes gl_FragDepth but otherwise wants the fixed functionality fragment depth.

Fragment shaders have access to the input built-in variable gl_FrontFacing, whose value is true if the fragment belongs to a front-facing primitive. One use of this is to emulate two-sided lighting by selecting one of two colors calculated by a vertex or geometry shader.

The values in gl_PointCoord are two-dimensional coordinates indicating where within a point primitive the current fragment is located, when point sprites are enabled. They range from 0.0 to 1.0 across the point. If the current primitive is not a point, or if point sprites are not enabled, then the values read from gl_PointCoord are undefined.

For both the input array gl_SampleMaskIn[] and the output array gl_SampleMask[], bit B of mask M (gl_SampleMaskIn[M] or gl_SampleMask[M]) corresponds to sample 32*M+B. These arrays have ceil(s/32) elements, where s is the maximum number of color samples supported by the implementation.

The input variable gl_SampleMaskIn indicates the set of samples covered by the primitive generating the fragment during multisample rasterization. It has a sample bit set if and only if the sample is considered covered for this fragment shader invocation.

The output array gl_SampleMask[] sets the sample mask for the fragment being processed. Coverage for the current fragment will become the logical AND of the coverage mask and the output gl_SampleMask. 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 32bit elements), determined by the maximum number of samples.. If the fragment shader statically assigns a value to gl_SampleMask, the sample mask will be undefined for any array elements of any fragment shader invocations that fail to assign a value. If a shader does not statically assign a value to gl_SampleMask, the sample mask has no effect on the processing of a fragment.

The input variable gl_SampleID is filled with the sample number of the sample currently being processed. This variable is in the range 0 to gl_NumSamples-1, where gl_NumSamples is the total number of samples in the framebuffer, or 1 if rendering to a non-multisample framebuffer. Any static use of this variable in a fragment shader causes the entire shader to be evaluated per-sample.

The input variable gl_SamplePosition contains the position of the current sample within the multisample draw buffer. The x and y components of gl_SamplePosition contain the sub-pixel coordinate of the current sample and will have values in the range 0.0 to 1.0. Any static use of this variable in a fragment shader causes the entire shader to be evaluated per sample.

The value gl_HelperInvocation is true if the fragment shader invocation is considered a helper invocation and is false otherwise. A helper invocation is a fragment shader invocation that is created solely for the purposes of evaluating derivatives for use in non-helper fragment shader invocations. Such derivatives are computed implicitly in the built-in function texture() (see “Texture Functions”), and explicitly in the derivative functions in “Derivative Functions”, for example dFdx() and dFdy().

Fragment shader helper invocations execute the same shader code as non-helper invocations, but will not have side effects that modify the framebuffer or other shader-accessible memory. In particular:

Helper invocations may be generated for pixels not covered by a primitive being rendered. While fragment shader inputs qualified with centroid are normally required to be sampled in the intersection of the pixel and the primitive, the requirement is ignored for such pixels since there is no intersection between the pixel and primitive.

Helper invocations may also be generated for fragments that are covered by a primitive being rendered when the fragment is killed by early fragment tests (using the early_fragment_tests qualifier) or where the implementation is able to determine that executing the fragment shader would have no effect other than assisting in computing derivatives for other fragment shader invocations.

The set of helper invocations generated when processing any set of primitives is implementation-dependent.

gl_ClipDistance contains linearly interpolated values for the vertex- pipeline values written by a shader to the gl_ClipDistance output variable. Only elements in this array that have clipping enabled will have defined values.

gl_CullDistance contains linearly interpolated values for the vertex- pipeline values written by a shader to the gl_CullDistance output variable.

The input variable gl_PrimitiveID is filled with the value written to the gl_PrimitiveID geometry shader output, if a geometry shader is present. Otherwise, it is filled with the number of primitives processed by the shader since the current set of rendering primitives was started.

The input variable gl_Layer is filled with the value written to the gl_Layer geometry shader output, if a geometry shader is present. If the geometry stage does not dynamically assign a value to gl_Layer, the value of gl_Layer in the fragment stage will be undefined. If the geometry stage makes no static assignment to gl_Layer, the input value in the fragment stage will be zero. Otherwise, the fragment stage will read the same value written by the geometry stage, even if that value is out of range. If a fragment shader contains a static access to gl_Layer, it will count against the implementation defined limit for the maximum number of inputs to the fragment stage.

The input variable gl_ViewportIndex is filled with the value written to the output variable gl_ViewportIndex in the geometry stage, if a geometry shader is present. If the geometry stage does not dynamically assign a value to gl_ViewportIndex, the value of gl_ViewportIndex in the fragment shader will be undefined. If the geometry stage makes no static assignment to gl_ViewportIndex, the fragment stage will read zero. Otherwise, the fragment stage will read the same value written by the geometry stage, even if that value is out of range. If a fragment shader contains a static access to gl_ViewportIndex, it will count against the implementation defined limit for the maximum number of inputs to the fragment stage.

In the compute shader, built-in variables are declared as follows:

The built-in variable gl_NumWorkGroups is a compute-shader input variable containing the number of workgroups in each dimension of the dispatch that will execute the compute shader. Its content is equal to the values specified in the num_groups_x, num_groups_y, and num_groups_z parameters passed to the DispatchCompute API entry point.

The built-in constant gl_WorkGroupSize is a compute-shader constant containing the workgroup size of the shader. The size of the workgroup in the X, Y, and Z dimensions is stored in the x, y, and z components. The constant values in gl_WorkGroupSize will match those specified in the required local_size_x, local_size_y, and local_size_z layout qualifiers for the current shader. This is a constant so that it can be used to size arrays of memory that can be shared within the workgroup. It is a compile-time error to use gl_WorkGroupSize in a shader that does not declare a fixed workgroup size, or before that shader has declared a fixed workgroup size, using local_size_x, local_size_y, and local_size_z. Use of variables whose values are derived from gl_WorkGroupSize, however, is not constrained to follow a declaration of the fixed workgroup size.

The built-in variable gl_WorkGroupID is a compute-shader input variable containing the three-dimensional index of the workgroup that the current invocation is executing in. The possible values range across the parameters passed into DispatchCompute, i.e., from (0, 0, 0) to (gl_NumWorkGroups.x - 1, gl_NumWorkGroups.y - 1, gl_NumWorkGroups.z -1).

The built-in variable gl_LocalInvocationID is a compute-shader input variable containing the three-dimensional index of the current work item within the workgroup. The possible values for this variable range across the workgroup size, i.e., (0,0,0) to (gl_WorkGroupSize.x - 1, gl_WorkGroupSize.y - 1, gl_WorkGroupSize.z - 1). Use of gl_LocalInvocationID is allowed before declarations of local_size_x, local_size_y, and local_size_z.

The built-in variable gl_GlobalInvocationID is a compute shader input variable containing the global index of the current work item. This value uniquely identifies this invocation from all other invocations across all workgroups initiated by the current DispatchCompute call. This is computed as:

The built-in variable gl_LocalInvocationIndex is a compute shader input variable that contains the one-dimensional representation of the gl_LocalInvocationID. This is computed as:

Use of gl_LocalInvocationIndex is allowed before declarations of local_size_x, local_size_y, and local_size_z.

When using the compatibility profile, the GL can provide fixed functionality behavior for the vertex and fragment programmable pipeline stages. For example, mixing a fixed functionality vertex stage with a programmable fragment stage.

The following built-in vertex, tessellation control, tessellation evaluation, and geometry output variables are available to specify inputs for the subsequent programmable shader stage or the fixed functionality fragment stage. A particular one should be written to if any functionality in a corresponding fragment shader or fixed pipeline uses it or state derived from it. Otherwise, behavior is undefined. The following members are added to the output gl_PerVertex block in these languages:

The output variable gl_ClipVertex provides a place for vertex and geometry shaders to write the coordinate to be used with the user clipping half-spaces. Writing to gl_ClipDistance is the preferred method for user clipping. It is a compile-time or link-time error for the set of shaders forming a program to statically read or write both gl_ClipVertex and either gl_ClipDistance or gl_CullDistance. If neither gl_ClipVertex nor gl_ClipDistance is written, their values are undefined and any clipping against user clip half-spaces is also undefined.

Similarly to what was previously described for the core profile, the gl_PerVertex block can be redeclared in a shader to explicitly include these additional members. For example:

The user must ensure the clip vertex and user clipping half-spaces are defined in the same coordinate space.

The output variables gl_FrontColor, glFrontSecondaryColor, gl_BackColor, and glBackSecondaryColor assign primary and secondary colors for front and back faces of primitives containing the vertex being processed. The output variable gl_TexCoord assigns texture coordinates for the vertex being processed.

For gl_FogFragCoord, the value written will be used as the “c” value in section 16.4 “Fog” of the Compatibility profile of the OpenGL Specification, by the fixed functionality pipeline. For example, if the z-coordinate of the fragment in eye space is desired as “c”, then that’s what the vertex shader executable should write into gl_FogFragCoord.

As with all arrays, indices used to subscript gl_TexCoord must either be a constant integral expressions, or this array must be redeclared by the shader with a size. The size can be at most gl_MaxTextureCoords. Using indices close to 0 may aid the implementation in preserving varying resources. The redeclaration of gl_TexCoord can also be done at global scope as, for example:

(This treatment is a special case for gl_TexCoord[], not a general method for redeclaring members of blocks.) It is a compile-time error to redeclare gl_TexCoord[] at global scope if there is a redeclaration of the corresponding built-in block; only one form of redeclaration is allowed within a shader (and hence within a stage, as block redeclarations must match across all shaders using it).

In the tessellation control, evaluation, and geometry shaders, the outputs of the previous stage described above are also available in the input gl_PerVertex block in these languages.

These can be redeclared to establish an explicit pipeline interface, the same way as described above for the output block gl_PerVertex, and the input redeclaration must match the output redeclaration of the previous stage. However, when a built-in interface block with an instance name is redeclared (e.g. gl_in), the instance name must be included in the redeclaration. It is a compile-time error to not include the built-in instance name or to change its name. For example,

Built-in block arrays predeclared with a size can be redeclared with unsized syntax. This keeps their size equal to the original predeclared size.

Treatment of gl_TexCoord[] redeclaration is also identical to that described for the output block gl_TexCoord[] redeclaration.

The following fragment input block is also available in a fragment shader when using the compatibility profile:

The values in gl_Color and gl_SecondaryColor will be derived automatically by the system from gl_FrontColor, gl_BackColor, gl_FrontSecondaryColor, and gl_BackSecondaryColor based on which face is visible in the primitive producing the fragment. If fixed functionality is used for vertex processing, then gl_FogFragCoord will either be the z-coordinate of the fragment in eye space, or the interpolation of the fog coordinate, as described in section 16.4 “Fog” of the Compatibility profile of the OpenGL Specification. The gl_TexCoord[] values are the interpolated gl_TexCoord[] values from a vertex shader or the texture coordinates of any fixed pipeline based vertex functionality.

Indices to the fragment shader gl_TexCoord array are as described above in the vertex shader text.

As described above for the input and output gl_PerVertex blocks, the gl_PerFragment block can be redeclared to create an explicit interface to another program. When matching these interfaces between separate programs, members in the gl_PerVertex output block must be declared if and only if the corresponding fragment shader members generated from them are present in the gl_PerFragment input block. These matches are described in detail in section 7.4.1 “Shader Interface Matching” of the OpenGL Specification. If they don’t match within a program, a link-time error will result. If the mismatch is between two programs, values passed between programs are undefined. Unlike with all other block matching, the order of declaration within gl_PerFragment does not have to match across shaders and does not have to correspond with order of declaration in a matching gl_PerVertex redeclaration.

The following fragment output variables are available in a fragment shader when using the compatibility profile:

Writing to gl_FragColor specifies the fragment color that will be used by the subsequent fixed functionality pipeline. If subsequent fixed functionality consumes fragment color and an execution of the fragment shader executable does not write a value to gl_FragColor then the fragment color consumed is undefined.

The variable gl_FragData is an array. Writing to gl_FragData[n] specifies the fragment data that will be used by the subsequent fixed functionality pipeline for data n. If subsequent fixed functionality consumes fragment data and an execution of a fragment shader executable does not write a value to it, then the fragment data consumed is undefined.

If a shader statically assigns a value to gl_FragColor, it may not assign a value to any element of gl_FragData. If a shader statically writes a value to any element of gl_FragData, it may not assign a value to gl_FragColor. That is, a shader may assign values to either gl_FragColor or gl_FragData, but not both. Multiple shaders linked together must also consistently write just one of these variables. Similarly, if user-declared output variables are in use (statically assigned to), then the built-in variables gl_FragColor and gl_FragData may not be assigned to. These incorrect usages all generate compile-time or link-time errors.

If a shader executes the discard keyword, the fragment is discarded, and the values of gl_FragDepth and gl_FragColor become irrelevant.

These variables are present only in the compatibility profile. They are not available to compute shaders, but are available to all other shaders.