Built-in Variable (GLSL): Difference between revisions

From OpenGL Wiki
Jump to navigation Jump to search
← Older edit
Ldo (talk | contribs)
67 edits
→Fragment shader uniforms: mention versions
m Bot: Updating section links to use redirects.
 
(35 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The [[OpenGL Shading Language]] defines a number of special variables for the various shader stages. These '''predefined variables''' (or built-in variables) have special properties. They are usually for communicating with certain fixed-functionality. By convention, all predefined variables start with "gl_"; no user-defined variables may start with this.
{{shader float}}


== Vertex shader inputs ==
The [[OpenGL Shading Language]] defines a number of special variables for the various shader stages. These '''built-in variables''' (or built-in variables) have special properties. They are usually for communicating with certain fixed-functionality. By convention, all predefined variables start with "gl_"; no user-defined variables may start with this.


Vertex shaders have the following predefined inputs.
{{note|This page only describes the core OpenGL shading language pre-defined variables. Any variables that are from the compatibility profiles are not listed here.}}


<source lang="glsl">
== Vertex shader inputs ==
/* no inputs prior to GLSL 1.30 */
 
in int gl_VertexID; /* GLSL ≥ 1.30 */
in int gl_InstanceID; /* GLSL ≥ 1.40 */
</source>
 
The ''gl_VertexID'' is the index of the current vertex being processed. For array rendering, this value is the index of the current vertex. For indexed rendering, this is the index fetched from the element buffer for this vertex.


The ''gl_InstanceID'' specifies which instance is being rendered, when using [[Vertex_Specification#Instancing|instanced rendering]].
{{snippet|:Vertex Shader/Defined Inputs}}
 
== Vertex shader attributes ==
<source lang="glsl">
attribute vec4 gl_Color; /* GLSL < 1.40 */
attribute vec4 gl_SecondaryColor; /* GLSL < 1.40 */
attribute vec3 gl_Normal; /* GLSL < 1.40 */
attribute vec4 gl_Vertex; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord0; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord1; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord2; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord3; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord4; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord5; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord6; /* GLSL < 1.40 */
attribute vec4 gl_MultiTexCoord7; /* GLSL < 1.40 */
attribute float gl_FogCoord; /* GLSL < 1.40 */
</source>
These are all deprecated in GLSL 1.30, and removed in GLSL 1.40 and later.


== Vertex shader outputs ==
== Vertex shader outputs ==


Vertex shaders have the following predefined outputs.
{{snippet|:Vertex Shader/Defined Outputs}}
 
<source lang="glsl">
out vec4 gl_Position; /* GLSL < 1.50 */
out float gl_PointSize; /* GLSL < 1.50 */
out vec4 gl_ClipVertex; /* GLSL < 1.40 */
out float gl_ClipDistance[]; /* GLSL ≥ 1.30 < 1.50 */
 
out gl_PerVertex /* GLSL ≥ 1.50 */
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
}
</source>
 
''gl_PerVertex'' defines an [[GLSL Interface Blocks|interface block]] for outputs. The block is defined so that prefixing the names is not required.
 
''gl_Position'' is the output position of the current vertex (in clip-space, if there is no geometry shader). It is not necessary to write to this value in a vertex shader, though if you do not, don't be surprised if the primitives you get are not reasonable. You can reasonably omit writing to this variable if you are using transform feedback and shutting off rasterization, or if you are using a geometry shader that will use user-defined outputs to generate positions.
 
''gl_PointSize'' is the pixel width/height of the point being rasterized. It is only necessary to write to this when rendering points.
 
''gl_ClipDistance'' allows the shader to set the distance from a vertex to each clip plane. A positive distance means that the vertex is inside/behind the clip plane, and a negative distance means it is outside/in front of the clip plane.
 
In order to use this variable, the user must manually redeclare it with a size.
 
== Geometry shader inputs ==
 
<source lang="glsl">
/* no geometry shaders prior to GLSL 1.50 */
 
in gl_PerVertex /* GLSL ≥ 1.50 */
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_in[];
 
in int gl_PrimitiveIDIn; /* GLSL ≥ 1.50 */
</source>
 
The ''gl_PerVertex'' variables contain the values passed from the previous vertex shader stages. Note that in the geometry shader, they must be prefixed by ''gl_in'', which is an interface block array. The size of this array is based on the layout qualifier used for inputs for this geometry shader. You do not have to redeclare this block with a specific size; the system does this for you. As with any array, you can get its length with the ''length()'' function.
 
''gl_PrimitiveIDIn'' is the number of the current primitive being worked on during this rendering call. That is, the number of primitives previously processed by this ''glDraw*'' call.
 
GLSL 4.00 and above also have the following definitions:
 
<source lang="glsl">
in int gl_InvocationID;
</source>
 
Geometry shaders can be invoked multiple times; this value specifies the current invocation.
 
== Geometry shader outputs ==
 
<source lang="glsl">
/* no geometry shaders prior to GLSL 1.50 */
 
out gl_PerVertex /* GLSL ≥ 1.50 */
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
};
 
out int gl_PrimitiveID; /* GLSL ≥ 1.50 */
out int gl_Layer; /* GLSL ≥ 1.50 */
</source>
 
The ''gl_PerVertex'' has the same meaning as from the vertex shader stage.
 
''gl_PrimitiveID'' is a user-defined identifier for the primitive. It is passed directly to the fragment shader (see below). If the fragment shader uses its corresponding input, the value is undefined if the geometry shader does not write to it (OpenGL will automatically fill it in if there is no geometry shader).
 
The geometry shader should write to this value for the [[Provoking Vertex|provoking vertex]] of the output primitive.
 
''gl_Layer'' is used for rendering to [[Framebuffer_Object#Layered_Images|layered framebuffer objects]]. It specifies the layer that the particular primitive is rendered to.
 
The ''gl_Layer'' variable is assigned to each vertex. If different vertices of a primitive get a different layer value, then OpenGL states that which layer is rendered to is undefined. Therefore, you should set it for each vertex emitted, and the value for each vertex of the same primitive should be the same.
 
Note that all of the output variables are cleared when EmitVertex() is called from the geometry shader.
 
GLSL 4.10 defines the following extra outputs:
 
<source lang="glsl">
out int gl_ViewportIndex;
</source>
 
The ''gl_ViewportIndex'' represents the viewport transform and scissor tests that this primitive will be used against. You should use this variable similarly to ''gl_Layer'': always write to it and always write the same value to it for each primitive.


== Tessellation control shader inputs ==
== Tessellation control shader inputs ==
<source lang="glsl">
/* no tessellation control shaders prior to GLSL 4.00 */


in gl_PerVertex { /* GLSL ≥ 4.00 */
{{snippet|:Tessellation Control Shader/Defined Inputs}}
    vec4 gl_Position;
    float gl_PointSize;
    float gl_ClipDistance[];
} gl_in[gl_MaxPatchVertices];
in int gl_PatchVerticesIn; /* GLSL ≥ 4.00 */
in int gl_PrimitiveID; /* GLSL ≥ 4.00 */
in int gl_InvocationID; /* GLSL ≥ 4.00 */
</source>


== Tessellation control shader outputs ==
== Tessellation control shader outputs ==
<source lang="glsl">
/* no tessellation control shaders prior to GLSL 4.00 */


out gl_PerVertex { /* GLSL ≥ 4.00 */
{{snippet|:Tessellation Control Shader/Defined Outputs}}
    vec4 gl_Position;
    float gl_PointSize;
    float gl_ClipDistance[];
} gl_out[];
patch out float gl_TessLevelOuter[4]; /* GLSL ≥ 4.00 */
patch out float gl_TessLevelInner[2]; /* GLSL ≥ 4.00 */
</source>


== Tessellation evaluation shader inputs ==
== Tessellation evaluation shader inputs ==
<source lang="glsl">
/* no tessellation evaluation shaders prior to GLSL 4.00 */


in gl_PerVertex { /* GLSL ≥ 4.00 */
{{snippet|:Tessellation Evaluation Shader/Defined Inputs}}
    vec4 gl_Position;
    float gl_PointSize;
    float gl_ClipDistance[];
} gl_in[gl_MaxPatchVertices];
in int gl_PatchVerticesIn; /* GLSL ≥ 4.00 */
in int gl_PrimitiveID; /* GLSL ≥ 4.00 */
in vec3 gl_TessCoord; /* GLSL ≥ 4.00 */
patch in float gl_TessLevelOuter[4]; /* GLSL ≥ 4.00 */
patch in float gl_TessLevelInner[2]; /* GLSL ≥ 4.00 */
</source>


== Tessellation evaluation shader outputs ==
== Tessellation evaluation shader outputs ==
<source lang="glsl">
/* no tessellation evaluation shaders prior to GLSL 4.00 */


out gl_PerVertex { /* GLSL ≥ 4.00 */
{{snippet|:Tessellation Evaluation Shader/Defined Outputs}}
    vec4 gl_Position;
    float gl_PointSize;
    float gl_ClipDistance[];
};
</source>


== Fragment shader inputs ==
== Geometry shader inputs ==


<source lang="glsl">
{{snippet|:Geometry Shader/Defined Inputs}}
in vec4 gl_FragCoord; /* GLSL all versions */
in bool gl_FrontFacing; /* GLSL all versions */
in float gl_ClipDistance[]; /* GLSL all versions */
in vec2 gl_PointCoord; /* GLSL ≥ 1.50 */
in int gl_PrimitiveID; /* GLSL ≥ 1.50 */
</source>


''gl_FragCoord'' contains the window-space position of the current sample that this fragment represents. The Z component is the value that will be written to the depth buffer if the user does not override this (see below). The W component is special; it is 1/Wclip. That is, it is 1 divided by the W component of ''gl_Position'' output from the vertex or geometry shader.
== Geometry shader outputs ==


''gl_FrontFacing'' is true if the primitive is seen from the front, and false if it is the back.
{{snippet|:Geometry Shader/Defined Outputs}}
{{snippet|:Geometry Shader/Defined Outputs Layered}}


''gl_ClipDistance'' contains the values output from the vertex shader, linearly interpolated across the primitive. As before, it must be sized explicitly.
== Fragment shader inputs ==


''gl_PointCoord'' is the location within the area of a [[Point Rasterization|point]] that specifies this fragment's location. This is a normalized value, on the range [0, 1]. The (0,0) origin depends on the point coordinate origin set by OpenGL; the default is the lower-left corner.
{{snippet|:Fragment Shader/Defined Inputs}}


''gl_PrimitiveID'' is the value output by the geometry shader, or by OpenGL if no geometry shader was used. It represents the index of the primitive that is being rasterized.
== Fragment shader outputs ==
 
GLSL 4.00 adds the following inputs:
 
<source lang="glsl">
in int gl_SampleID; /* GLSL ≥ 4.00 */
in vec2 gl_SamplePosition; /* GLSL ≥ 4.00 */
in int gl_SampleMaskIn[]; /* GLSL ≥ 4.00 */
</source>
 
''gl_SampleID'' is the ID for the current sample being rasterized within the area of the pixel.
 
''gl_SamplePosition'' is the location of the current sample within the pixel area being rendered. These values are on the range [0, 1].


{{note|Using the ''gl_SamplePosition'' variable '''in any way''' will cause the fragment shader to be evaluated per-sample. Since the whole point of multisampling is to avoid that, it's probably not a good idea to do so unless you really need it.}}
{{snippet|:Fragment Shader/Defined Outputs}}


''gl_SampleMaskIn'' represents the sample coverage mask for the currently rasterized fragment. The user must redeclare the size of the sample mask to the implementation-dependent maximum number of samples, divided by 32, rounded up (to get the number of 32-bit integers).
== Compute shader inputs ==
 
{{snippet|:Compute Shader/Defined Inputs}}
== Fragment shader uniforms ==
 
The fragment shader defines some uniform built-in values for the sake of convenience:


== Compute shader other variables ==
<source lang="glsl">
<source lang="glsl">
struct gl_DepthRangeParameters /* GLSL all versions */
const uvec3 gl_WorkGroupSize;  // GLSL ≥ 4.30
{
    float near;
    float far;
    float diff;
};
uniform gl_DepthRangeParameters gl_DepthRange; /* GLSL all versions */
</source>
</source>


This struct provides access to the glDepthRange near and far values. The ''diff'' value is the far value minus the near value.
The ''gl_WorkGroupSize'' variable is a constant that contains the local work-group size of the shader, in 3 dimensions. It is defined by the [[Layout Qualifier (GLSL)|layout qualifiers]] ''local_size_x/y/z''. This is a compile-time constant.


== Fragment shader outputs ==
== Shader uniforms ==
<source lang="glsl">
out vec4 gl_FragColor; /* GLSL < 1.3 */
out vec4 gl_FragData[gl_MaxDrawBuffers]; /* GLSL < 1.3 */
</source>


The ''gl_FragColor'' value is what will be written to the colour buffer, representing (this contribution to) the output pixel. Alternatively, ''gl_FragData'' is a whole output array of values to be fed to the rest of the pipeline; the fragment shader writes to either ''gl_FragColor'' or ''glFragData'', but not both.
{{snippet|:Shader/Defined Uniforms}}


Note: these are deprecated as of GLSL 1.3. You are supposed to define your own '''out''' variables instead.
== Constants ==


<source lang="glsl">
There are many [[Shader Resource Limit|implementation-defined shader stage limits]] who's values would be useful to a particular shader. GLSL provides a number of constant integer variables that give these values to shaders. All of these values are available to ''all'' shader stages.
out float gl_FragDepth; /* GLSL all versions */
</source>


The ''gl_FragDepth'' value is the value that will be written to the depth buffer. It will also be used for the depth test. The fragment shader does not have to write to this variable; it will automatically be filled with with ''gl_FragCoord.z''. However, if the fragment shader writes to this variable anywhere, then it must ensure that the value is ''always'' written to, no matter what path is taken through the shader (unless discard is used in the other paths).
All of these variables are declared as {{code|const}}, so they are considered [[Constant Expression|constant expressions]]. These constants are named based on the OpenGL enumerators used to specify those limitations. The transformation is quite simple: take the GLSL name, put an underscore before every capital letter (unless there's one there already), and then make all the letters capital.


GLSL 4.00 adds the following output:
The variables are as follows:


<source lang="glsl">
<div style="font-size: 80%;">
out int gl_SampleMask[]; /* GLSL ≥ 4.00 */
{| class="wikitable" style="line-height: 1.0em;"
</source>
!
!
! colspan = 2 | Minimum Required Value
|-
! Type
! Name
! GL 3.3
! GL 4.4
|-
| {{code|int}}
| {{code|gl_MaxVertexAttribs}}
| colspan = 2 | 16
|-
| {{code|int}}
| {{code|gl_MaxVertexOutputComponents }}
| colspan = 2 | 64
|-
| {{code|int}}
| {{code|gl_MaxVertexUniformComponents}}
| colspan = 2 | 1024
|-
| {{code|int}}
| {{code|gl_MaxVertexTextureImageUnits}}
| colspan = 2 | 16
|-
| {{code|int}}
| {{code|gl_MaxGeometryInputComponents }}
| colspan = 2 | 64
|-
| {{code|int}}
| {{code|gl_MaxGeometryOutputComponents }}
| colspan = 2 | 128
|-
| {{code|int}}
| {{code|gl_MaxGeometryUniformComponents }}
| colspan = 2 | 1024
|-
| {{code|int}}
| {{code|gl_MaxGeometryTextureImageUnits}}
| colspan = 2 | 16
|-
| {{code|int}}
| {{code|gl_MaxGeometryOutputVertices}}
| colspan = 2 | 256
|-
| {{code|int}}
| {{code|gl_MaxGeometryTotalOutputComponents }}
| colspan = 2 | 1024
|-
| {{code|int}}
| {{code|gl_MaxGeometryVaryingComponents }}
| colspan = 2 | 64
|-
| {{code|int}}
| {{code|gl_MaxFragmentInputComponents }}
| colspan = 2 | 128
|-
| {{code|int}}
| {{code|gl_MaxDrawBuffers}}
| colspan = 2 | 8
|-
| {{code|int}}
| {{code|gl_MaxFragmentUniformComponents}}
| colspan = 2 | 1024
|-
| {{code|int}}
| {{code|gl_MaxTextureImageUnits}}<sup>1</sup>
| colspan = 2 | 16
|-
| {{code|int}}
| {{code|gl_MaxClipDistances }}
| colspan = 2 | 8
|-
| {{code|int}}
| {{code|gl_MaxCombinedTextureImageUnits}}
| 48
| 96
|-
! colspan = 4 | Requires OpenGL 4.0
|-
| {{code|int}}
| {{code|gl_MaxTessControlInputComponents}}
| N/A
| 128
|-
| {{code|int}}
| {{code|gl_MaxTessControlOutputComponents}}
| N/A
| 128
|-
| {{code|int}}
| {{code|gl_MaxTessControlUniformComponents}}
| N/A
| 1024
|-
| {{code|int}}
| {{code|gl_MaxTessControlTextureImageUnits}}
| N/A
| 16
|-
| {{code|int}}
| {{code|gl_MaxTessControlTotalOutputComponents}}
| N/A
| 4096
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationInputComponents}}
| N/A
| 128
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationOutputComponents}}
| N/A
| 128
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationUniformComponents}}
| N/A
| 1024
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationTextureImageUnits}}
| N/A
| 16
|-
| {{code|int}}
| {{code|gl_MaxTessPatchComponents}}
| N/A
| 120
|-
| {{code|int}}
| {{code|gl_MaxPatchVertices}}
| N/A
| 32
|-
| {{code|int}}
| {{code|gl_MaxTessGenLevel}}
| N/A
| 64
|-
! colspan = 4 | Requires OpenGL 4.1
|-
| {{code|int}}
| {{code|gl_MaxViewports}}
| N/A
| 16
|-
| {{code|int}}
| {{code|gl_MaxVertexUniformVectors}}
| N/A
| 256
|-
| {{code|int}}
| {{code|gl_MaxFragmentUniformVectors}}
| N/A
| 256
|-
| {{code|int}}
| {{code|gl_MaxVaryingVectors}}
| N/A
| 15
|-
! colspan = 4 | Requires OpenGL 4.2
|-
| {{code|int}}
| {{code|gl_MaxVertexImageUniforms}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxVertexAtomicCounters}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxVertexAtomicCounterBuffers}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessControlImageUniforms}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessControlAtomicCounters}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessControlAtomicCounterBuffers}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationImageUniforms}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationAtomicCounters}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxTessEvaluationAtomicCounterBuffers}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxGeometryImageUniforms}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxGeometryAtomicCounters}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxGeometryAtomicCounterBuffers}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxFragmentImageUniforms}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxFragmentAtomicCounters}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxFragmentAtomicCounterBuffers}}
| N/A
| 1
|-
| {{code|int}}
| {{code|gl_MaxCombinedImageUniforms}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxCombinedAtomicCounters}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxCombinedAtomicCounterBuffers}}
| N/A
| 1
|-
| {{code|int}}
| {{code|gl_MaxImageUnits}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxCombinedImageUnitsAndFragmentOutputs}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxImageSamples}}
| N/A
| 0
|-
| {{code|int}}
| {{code|gl_MaxAtomicCounterBindings}}
| N/A
| 1
|-
| {{code|int}}
| {{code|gl_MaxAtomicCounterBufferSize}}
| N/A
| 32
|-
| {{code|int}}
| {{code|gl_MinProgramTexelOffset}}
| N/A
| -8
|-
| {{code|int}}
| {{code|gl_MaxProgramTexelOffset}}
| N/A
| 7
|-
! colspan = 4 | Requires OpenGL 4.3
|-
| {{code|ivec3}}
| {{code|gl_MaxComputeWorkGroupCount}}
| N/A
| { 65535, 65535, 65535 }
|-
| {{code|ivec3}}
| {{code|gl_MaxComputeWorkGroupSize}}
| N/A
| { 1024, 1024, 64 }
|-
| {{code|int}}
| {{code|gl_MaxComputeUniformComponents}}
| N/A
| 512
|-
| {{code|int}}
| {{code|gl_MaxComputeTextureImageUnits}}
| N/A
| 16
|-
| {{code|int}}
| {{code|gl_MaxComputeImageUniforms}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxComputeAtomicCounters}}
| N/A
| 8
|-
| {{code|int}}
| {{code|gl_MaxComputeAtomicCounterBuffers}}
| N/A
| 1
|-
! colspan = 4 | Requires OpenGL 4.4
|-
| {{code|int}}
| {{code|gl_MaxTransformFeedbackBuffers}}
| N/A
| 4
|-
| {{code|int}}
| {{code|gl_MaxTransformFeedbackInterleavedComponents}}
| N/A
| 64
|-
|}
</div>


''gl_SampleMask'' is a bitmask that represents the samples, when using [[Multisampling|multisample rendering]], that will be written to. The user must redeclare the size of the sample mask to the implementation-dependent maximum number of samples, divided by 32, rounded up (to get the number of 32-bit integers).
<sup>1</sup>: This is the number of fragment shader texture image units.


The mask bits will be logically AND'd with the coverage mask computed normally.


[[Category:OpenGL Shading Language]]
[[Category:OpenGL Shading Language]]

Latest revision as of 16:35, 6 May 2015

GLSL

The OpenGL Shading Language defines a number of special variables for the various shader stages. These built-in variables (or built-in variables) have special properties. They are usually for communicating with certain fixed-functionality. By convention, all predefined variables start with "gl_"; no user-defined variables may start with this.

Note: This page only describes the core OpenGL shading language pre-defined variables. Any variables that are from the compatibility profiles are not listed here.

Vertex shader inputs

V · E

Vertex Shaders have the following built-in input variables. 

in int gl_VertexID;
in int gl_InstanceID;
in int gl_DrawID; // Requires GLSL 4.60 or ARB_shader_draw_parameters
in int gl_BaseVertex; // Requires GLSL 4.60 or ARB_shader_draw_parameters
in int gl_BaseInstance; // Requires GLSL 4.60 or ARB_shader_draw_parameters
gl_VertexID
the index of the vertex currently being processed. When using non-indexed rendering, it is the effective index of the current vertex (the number of vertices processed + the first​ value). For indexed rendering, it is the index used to fetch this vertex from the buffer.
Note: gl_VertexID will have the baseVertex​ parameter added to the index, if there was such a parameter in the rendering command.
gl_InstanceID
the index of the current instance when doing some form of instanced rendering. The instance count always starts at 0, even when using base instance calls. When not using instanced rendering, this value will be 0.
Warning: This value does not follow the baseInstance​ provided by some instanced rendering functions. gl_InstanceID always falls on the half-open range [0, instancecount​). If you have GLSL 4.60, you may use gl_BaseInstance to compute the proper instance index.
gl_DrawID
the index of the drawing command within multi-draw rendering commands (including indirect multi-draw commands). The first draw command has an ID of 0, increasing by one as the renderer passes through drawing commands.
This value will always be a Dynamically Uniform Expression.
gl_BaseVertex
the value of the baseVertex​ parameter of the rendering command. If the rendering command did not include that parameter, the value of this input will be 0.
gl_BaseInstance
the value of the baseInstance​ parameter of the instanced rendering command. If the rendering command did not include this parameter, the value of this input will be 0.

Vertex shader outputs

V · E

Vertex Shaders have the following predefined outputs. 

out gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
};

gl_PerVertex defines an interface block for outputs. The block is defined without an instance name, so that prefixing the names is not required.

These variables only take on the meanings below if this shader is the last active Vertex Processing stage, and if rasterization is still active (ie: GL_RASTERIZER_DISCARD is not enabled). The text below explains how the Vertex Post-Processing system uses the variables. These variables may not be redeclared with interpolation qualifiers.

gl_Position
the clip-space output position of the current vertex.
gl_PointSize
the pixel width/height of the point being rasterized. It only has a meaning when rendering point primitives. It will be clamped to the GL_POINT_SIZE_RANGE.
gl_ClipDistance
allows the shader to set the distance from the vertex to each user-defined clipping half-space. A non-negative distance means that the vertex is inside/behind the clip plane, and a negative distance means it is outside/in front of the clip plane. Each element in the array is one clip plane. In order to use this variable, the user must manually redeclare it with an explicit size. With GLSL 4.10 or ARB_separate_shader_objects, the whole gl_PerVertex block needs to be redeclared. Otherwise just the gl_ClipDistance built-in needs to be redeclared.

Tessellation control shader inputs

V · E

Tessellation Control Shaders provide the following built-in input variables: 

 in int gl_PatchVerticesIn;
 in int gl_PrimitiveID;
 in int gl_InvocationID;
gl_PatchVerticesIn
the number of vertices in the input patch.
gl_PrimitiveID
the index of the current patch within this rendering command.
gl_InvocationID
the index of the TCS invocation within this patch. A TCS invocation writes to per-vertex output variables by using this to index them.

The TCS also takes the built-in variables output by the vertex shader: 

in gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_in[gl_MaxPatchVertices];

Note that just because gl_in is defined to have gl_MaxPatchVertices entries does not mean that you can access beyond gl_PatchVerticesIn and get reasonable values. These variables have only the meaning the vertex shader that passed them gave them.

Tessellation control shader outputs

V · E

Tessellation Control Shaders have the following built-in patch output variables: 

patch out float gl_TessLevelOuter[4];
patch out float gl_TessLevelInner[2];

These define the outer and inner tessellation levels used by the tessellation primitive generator. They define how much tessellation to apply to the patch. Their exact meaning depends on the type of patch (and other settings) defined in the Tessellation Evaluation Shader.

Note: If any of the outer levels used by the abstract patch type is 0 or negative (or NaN), then the patch will be discarded by the generator, and no TES invocations for this patch will result.

As with any other patch variable, multiple TCS invocations for the same patch can write to the same tessellation level variable, so long as they are all computing and writing the exact same value.

TCS's also provide the following optional per-vertex output variables: 

out gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_out[];

The use of any of these in a TCS is completely optional. Indeed, their semantics will generally be of no practical value to the TCS. They have the same general meaning as for vertex shaders, but since a TCS must always be followed by an evaluation shader, the TCS never has to write to any of them.

Tessellation evaluation shader inputs

V · E

Tessellation Evaluation Shaders have the following built-in inputs. 

in vec3 gl_TessCoord;
in int gl_PatchVerticesIn;
in int gl_PrimitiveID;
gl_TessCoord
the location within the tessellated abstract patch for this particular vertex. Every input parameter other than this one will be identical for all TES invocations within a patch.
Which components of this vec3 that have valid values depends on the abstract patch type. For isolines and quads, only the XY components have valid values. For triangles, all three components have valid values. All valid values are normalized floats (on the range [0, 1]).
gl_PatchVerticesIn
the vertex count for the patch being processed. This is either the output vertex count specified by the TCS, or the patch vertex size specified by glPatchParameter if no TCS is active. Attempts to index per-vertex inputs by a value greater than or equal to gl_PatchVerticesIn results in undefined behavior.
gl_PrimitiveID
the index of the current patch in the series of patches being processed for this draw call. Primitive restart, if used, has no effect on the primitive ID.
Note: The tessellation primitive generator will cull patches that have a zero for one of the active outer tessellation levels. The intent of the specification seems to be that gl_PrimitiveID will still be incremented for culled patches. So the primitive ID for the TES is equivalent to the ID for the TCS invocations that generated that patch. But this is not entirely clear from the spec itself.

The TES also has access to the tessellation levels provided for the patch by the TCS or by OpenGL: 

patch in float gl_TessLevelOuter[4];
patch in float gl_TessLevelInner[2];

Only the outer and inner levels actually used by the abstract patch are valid. For example, if this TES uses isolines, only gl_TessLevelOuter[0] and gl_TessLevelOuter[1] will have valid values.

The TES also takes the built-in per-vertex variables output by the TCS: 

in gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_in[gl_MaxPatchVertices];

Note that just because gl_in is defined to have gl_MaxPatchVertices entries does not mean that you can access beyond gl_PatchVerticesIn and get reasonable values.

Tessellation evaluation shader outputs

V · E

Tessellation Evaluation Shaders have the following built-in outputs. 

out gl_PerVertex {
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
};

gl_PerVertex defines an interface block for outputs. The block is defined without an instance name, so that prefixing the names is not required.

These variables only take on the meanings below if this shader is the last active Vertex Processing stage, and if rasterization is still active (ie: GL_RASTERIZER_DISCARD is not enabled). The text below explains how the Vertex Post-Processing system uses the variables. These variables may not be redeclared with interpolation qualifiers.

gl_Position
the clip-space output position of the current vertex.
gl_PointSize
the pixel width/height of the point being rasterized. It only has a meaning when rendering point primitives, which in a TES requires using the point_mode​ input layout qualifier.
gl_ClipDistance
allows the shader to set the distance from the vertex to each User-Defined Clip Plane. A positive distance means that the vertex is inside/behind the clip plane, and a negative distance means it is outside/in front of the clip plane. Each element in the array is one clip plane. In order to use this variable, the user must manually redeclare it with an explicit size.

Geometry shader inputs

V · E

Geometry Shaders provide the following built-in input variables: 

in gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
} gl_in[];

These variables have only the meaning the prior shader stage(s) that passed them gave them.

There are some GS input values that are based on primitives, not vertices. These are not aggregated into arrays. These are: 

in int gl_PrimitiveIDIn;
in int gl_InvocationID; // Requires GLSL 4.0 or ARB_gpu_shader5
gl_PrimitiveIDIn
the current input primitive's ID, based on the number of primitives processed by the GS since the current drawing command started.
gl_InvocationID
the current instance, as defined when instancing geometry shaders.

Geometry shader outputs

V · E

Geometry Shaders have the following built-in outputs. 

out gl_PerVertex
{
  vec4 gl_Position;
  float gl_PointSize;
  float gl_ClipDistance[];
};

gl_PerVertex defines an interface block for outputs. The block is defined without an instance name, so that prefixing the names is not required.

The GS is the final Vertex Processing stage. Therefore, unless rasterization is being turned off, you must write to some of these values. These outputs are always associated with stream 0. So if you're emitting vertices to a different stream, you don't have to write to them.

gl_Position
the clip-space output position of the current vertex. This value must be written if you are emitting a vertex to stream 0, unless rasterization is off.
gl_PointSize
the pixel width/height of the point being rasterized. It is only necessary to write to this when outputting point primitives.
gl_ClipDistance
allows the shader to set the distance from the vertex to each User-Defined Clip Plane. A positive distance means that the vertex is inside/behind the clip plane, and a negative distance means it is outside/in front of the clip plane. In order to use this variable, the user must manually redeclare it (and therefore the interface block) with an explicit size.

Certain predefined outputs have special meaning and semantics. 

out int gl_PrimitiveID;

The primitive ID will be passed to the fragment shader. The primitive ID for a particular line/triangle will be taken from the provoking vertex of that line/triangle, so make sure that you are writing the correct value for the right provoking vertex.

The meaning for this value is whatever you want it to be. However, if you want to match the standard OpenGL meaning (ie: what the Fragment Shader would get if no GS were used), you must do this for each vertex before emitting it: 

gl_PrimitiveID = gl_PrimitiveIDIn;

This naturally assumes that the number of primitives output by the GS equals the number of primitives received by the GS.

V · E

Layered rendering in the GS works via two special output variables: 

out int gl_Layer;
out int gl_ViewportIndex; // Requires GL 4.1 or ARB_viewport_array.

The gl_Layer output defines which layer in the layered image the primitive goes to. Each vertex in the primitive must get the same layer index. Note that when rendering to cubemap arrays, the gl_Layer value represents layer-faces (the faces within a layer), not the layers of cubemaps.

gl_ViewportIndex, which requires GL 4.1 or ARB_viewport_array, specifies which viewport index to use with this primitive.

Note: ARB_viewport_array, while technically a 4.1 feature, is widely available on 3.3 hardware, from both NVIDIA and AMD.

Fragment shader inputs

V · E

Fragment Shaders have the following built-in input variables. 

in vec4 gl_FragCoord;
in bool gl_FrontFacing;
in vec2 gl_PointCoord;
gl_FragCoord
The location of the fragment in window space. The X, Y and Z components are the window-space position of the fragment. The Z value will be written to the depth buffer if gl_FragDepth is not written to by this shader stage. The W component of gl_FragCoord is 1/Wclip, where Wclip is the interpolated W component of the clip-space vertex position output to gl_Position from the last Vertex Processing stage.
The space of gl_FragCoord can be modified by redeclaring gl_FragCoord with special input layout qualifiers:
layout(origin_upper_left) in vec4 gl_FragCoord;
This means that the origin for gl_FragCoord's window-space will be the upper-left of the screen, rather than the usual lower-left.
layout(pixel_center_integer​) in vec4 gl_FragCoord;
OpenGL window space is defined such that pixel centers are on half-integer boundaries. So the center of the lower-left pixel is (0.5, 0.5). Using pixel_center_integer​ adjust gl_FragCoord such that whole integer values represent pixel centers.
Both of these exist to be compatible with D3D's window space. Unless you need your shaders to have this compatibility, you are advised not to use these features.
gl_FrontFacing
This is false if the fragment was generated by the back-face of the primitive; it is true in all other cases (including Primitives that have no back face).
gl_PointCoord
The location within a point primitive that defines the position of the fragment relative to the side of the point. Points are effectively rasterized as window-space squares of a certain pixel size. Since points are defined by a single vertex, the only way to tell where in that square a particular fragment is is with gl_PointCoord.
The values of gl_PointCoord's coordinates range from [0, 1]. OpenGL uses a upper-left origin for point-coordinates by default, so (0, 0) is the upper-left. However, the origin can be switched to a bottom-left origin by calling glPointParameteri(GL_POINT_SPRITE_COORD_ORIGIN, GL_LOWER_LEFT);

OpenGL 4.0 and above define additional system-generated input values: 

in int gl_SampleID;
in vec2 gl_SamplePosition;
in int gl_SampleMaskIn[];
gl_SampleID
This is an integer identifier for the current sample that this fragment is rasterized for.
Warning: Any use of this variable at all will force this shader to be evaluated per-sample. Since much of the point of multisampling is to avoid that, you should use it only when you must.
gl_SamplePosition
This is the location of the current sample for the fragment within the pixel's area, with values on the range [0, 1]. The origin is the bottom-left of the pixel area.
Warning: Any use of this variable at all will force this shader to be evaluated per-sample. Since much of the point of multisampling is to avoid that, you should use it only when you must.
gl_SampleMaskIn
When using multisampling, this variable contains a bitfield for the sample mask of the fragment being generated. The array is as long as needed to fill in the number of samples supported by the GL implementation.

Some Fragment shader built-in inputs will take values specified by OpenGL, but these values can be overridden by user control. 

in float gl_ClipDistance[];
in int gl_PrimitiveID;
gl_ClipDistance
This array contains the interpolated clipping plane half-spaces, as output for vertices from the last Vertex Processing stage.
gl_PrimitiveID
This value is the index of the current primitive being rendered by this drawing command. This includes any Tessellation applied to the mesh, so each individual primitive will have a unique index.
However, if a Geometry Shader is active, then the gl_PrimitiveID is exactly and only what the GS provided as output. Normally, gl_PrimitiveID is guaranteed to be unique, so if two FS invocations have the same primitive ID, they come from the same primitive. But if a GS is active and outputs non-unique values, then different fragment shader invocations for different primitives will get the same value. If the GS did not output a value for gl_PrimitiveID, then the fragment shader gets an undefined value.

Warning: The above discussion of gl_PrimitiveID is based on a particular reading of the OpenGL 4.6 specification. However, the specification itself is somewhat inconsistent with this view, suggesting that the primitive ID may only get incremented based on data fed to the system, not data generated by, for example, the tessellator. And the Vulkan specification seems to concur with this interpretation, and at least one implementation is known to agree with that as well. Until there is some clarification on the issue, you should consider the above to be questionable.

GL 4.3 provides the following additional inputs: 

in int gl_Layer;
in int gl_ViewportIndex;
gl_Layer
This is either 0 or the layer number for this primitive output by the Geometry Shader.
gl_ViewportIndex
This is either 0 or the viewport index for this primitive output by the Geometry Shader.

Fragment shader outputs

V · E

Fragment Shaders have the following built-in output variables. 

out float gl_FragDepth;
gl_FragDepth
This output is the fragment's depth. If the shader does not statically write this value, then it will take the value of gl_FragCoord.z.
To "statically write" to a variable means that you write to it anywhere in the program. Even if the writing code is technically unreachable for some reason, if there is a gl_FragDepth = ... expression anywhere in the shader, then it is statically written.
Warning: If the fragment shader statically writes to gl_FragDepth, then it is the responsibility of the shader to statically write to the value in all circumstances. No matter what branches may or may not be taken, the shader must ensure that the value is written. So, if you conditionally write to it in one place, you should at least make sure that there is a single non-conditional write sometime before that.

GLSL 4.20 or ARB_conservative_depth allows the user to specify that modifications to gl_FragDepth (relative to the gl_FragCoord.z value it would have otherwise had) will happen in certain ways. This allows the implementation the freedom to not turn off Early Depth Tests in certain situations.

This is done by re-declaring gl_FragDepth with a special layout qualifier: 

layout (depth_<condition>) out float gl_FragDepth;

The condition​ can be one of the following:

any
The default. You may freely change the depth, but you lose the most potential performance.
greater
You will only make the depth larger, compared to gl_FragCoord.z.
less
You will only make the depth smaller, compared to gl_FragCoord.z.
unchanged
If you write to gl_FragDepth, you will write exactly gl_FragCoord.z.

Violating the condition​ yields undefined behavior.

GLSL 4.00 or ARB_sample_shading brings us: 

out int gl_SampleMask[];
gl_SampleMask
This defines the sample mask for the fragment when performing mutlisampled rendering. If a shader does not statically write to it, then it will be filled in by gl_SampleMaskIn. The sample mask output here will be logically AND'd with the sample mask computed by the rasterizer.
Warning: Just as with gl_FragDepth, if a fragment shader writes to gl_SampleMask at all, it must make sure to write to the value for all execution paths. But it must also make sure to write to each element in the array. The array has the same size as gl_SampleMaskIn.

Compute shader inputs

V · E

Compute Shaders have the following built-in input variables. 

in uvec3 gl_NumWorkGroups;
in uvec3 gl_WorkGroupID;
in uvec3 gl_LocalInvocationID;
in uvec3 gl_GlobalInvocationID;
in uint  gl_LocalInvocationIndex;
gl_NumWorkGroups
This variable contains the number of work groups passed to the dispatch function.
gl_WorkGroupID
This is the current work group for this shader invocation. Each of the XYZ components will be on the half-open range [0, gl_NumWorkGroups.XYZ).
gl_LocalInvocationID
This is the current invocation of the shader within the work group. Each of the XYZ components will be on the half-open range [0, gl_WorkGroupSize.XYZ).
gl_GlobalInvocationID
This value uniquely identifies this particular invocation of the compute shader among all invocations of this compute dispatch call. It's a short-hand for the math computation:
gl_WorkGroupID * gl_WorkGroupSize + gl_LocalInvocationID;
gl_LocalInvocationIndex
This is a 1D version of gl_LocalInvocationID. It identifies this invocation's index within the work group. It is short-hand for this math computation:
  gl_LocalInvocationIndex =
          gl_LocalInvocationID.z * gl_WorkGroupSize.x * gl_WorkGroupSize.y +
          gl_LocalInvocationID.y * gl_WorkGroupSize.x + 
          gl_LocalInvocationID.x;

Compute shader other variables

const uvec3 gl_WorkGroupSize;   // GLSL ≥ 4.30

The gl_WorkGroupSize variable is a constant that contains the local work-group size of the shader, in 3 dimensions. It is defined by the layout qualifiers local_size_x/y/z. This is a compile-time constant.

Shader uniforms

V · E

Shaders define the following uniforms. 

struct gl_DepthRangeParameters
{
    float near;
    float far;
    float diff;
};
uniform gl_DepthRangeParameters gl_DepthRange;

uniform int gl_NumSamples; // GLSL 4.20

This struct provides access to the glDepthRange near and far values. The diff value is the far value minus the near value. Do recall that OpenGL makes no requirement that far is greater than near. With regard to multiple Viewports, gl_DepthRange only stores the range for viewport 0.

gl_NumSamples is the number of samples in the current Framebuffer. If the framebuffer is not multisampled, then this value will be 1.

Constants

There are many implementation-defined shader stage limits who's values would be useful to a particular shader. GLSL provides a number of constant integer variables that give these values to shaders. All of these values are available to all shader stages.

All of these variables are declared as const, so they are considered constant expressions. These constants are named based on the OpenGL enumerators used to specify those limitations. The transformation is quite simple: take the GLSL name, put an underscore before every capital letter (unless there's one there already), and then make all the letters capital.

The variables are as follows:

Minimum Required Value
Type Name GL 3.3 GL 4.4
int gl_MaxVertexAttribs 16
int gl_MaxVertexOutputComponents 64
int gl_MaxVertexUniformComponents 1024
int gl_MaxVertexTextureImageUnits 16
int gl_MaxGeometryInputComponents 64
int gl_MaxGeometryOutputComponents 128
int gl_MaxGeometryUniformComponents 1024
int gl_MaxGeometryTextureImageUnits 16
int gl_MaxGeometryOutputVertices 256
int gl_MaxGeometryTotalOutputComponents 1024
int gl_MaxGeometryVaryingComponents 64
int gl_MaxFragmentInputComponents 128
int gl_MaxDrawBuffers 8
int gl_MaxFragmentUniformComponents 1024
int gl_MaxTextureImageUnits1 16
int gl_MaxClipDistances 8
int gl_MaxCombinedTextureImageUnits 48 96
Requires OpenGL 4.0
int gl_MaxTessControlInputComponents N/A 128
int gl_MaxTessControlOutputComponents N/A 128
int gl_MaxTessControlUniformComponents N/A 1024
int gl_MaxTessControlTextureImageUnits N/A 16
int gl_MaxTessControlTotalOutputComponents N/A 4096
int gl_MaxTessEvaluationInputComponents N/A 128
int gl_MaxTessEvaluationOutputComponents N/A 128
int gl_MaxTessEvaluationUniformComponents N/A 1024
int gl_MaxTessEvaluationTextureImageUnits N/A 16
int gl_MaxTessPatchComponents N/A 120
int gl_MaxPatchVertices N/A 32
int gl_MaxTessGenLevel N/A 64
Requires OpenGL 4.1
int gl_MaxViewports N/A 16
int gl_MaxVertexUniformVectors N/A 256
int gl_MaxFragmentUniformVectors N/A 256
int gl_MaxVaryingVectors N/A 15
Requires OpenGL 4.2
int gl_MaxVertexImageUniforms N/A 0
int gl_MaxVertexAtomicCounters N/A 0
int gl_MaxVertexAtomicCounterBuffers N/A 0
int gl_MaxTessControlImageUniforms N/A 0
int gl_MaxTessControlAtomicCounters N/A 0
int gl_MaxTessControlAtomicCounterBuffers N/A 0
int gl_MaxTessEvaluationImageUniforms N/A 0
int gl_MaxTessEvaluationAtomicCounters N/A 0
int gl_MaxTessEvaluationAtomicCounterBuffers N/A 0
int gl_MaxGeometryImageUniforms N/A 0
int gl_MaxGeometryAtomicCounters N/A 0
int gl_MaxGeometryAtomicCounterBuffers N/A 0
int gl_MaxFragmentImageUniforms N/A 8
int gl_MaxFragmentAtomicCounters N/A 8
int gl_MaxFragmentAtomicCounterBuffers N/A 1
int gl_MaxCombinedImageUniforms N/A 8
int gl_MaxCombinedAtomicCounters N/A 8
int gl_MaxCombinedAtomicCounterBuffers N/A 1
int gl_MaxImageUnits N/A 8
int gl_MaxCombinedImageUnitsAndFragmentOutputs N/A 8
int gl_MaxImageSamples N/A 0
int gl_MaxAtomicCounterBindings N/A 1
int gl_MaxAtomicCounterBufferSize N/A 32
int gl_MinProgramTexelOffset N/A -8
int gl_MaxProgramTexelOffset N/A 7
Requires OpenGL 4.3
ivec3 gl_MaxComputeWorkGroupCount N/A { 65535, 65535, 65535 }
ivec3 gl_MaxComputeWorkGroupSize N/A { 1024, 1024, 64 }
int gl_MaxComputeUniformComponents N/A 512
int gl_MaxComputeTextureImageUnits N/A 16
int gl_MaxComputeImageUniforms N/A 8
int gl_MaxComputeAtomicCounters N/A 8
int gl_MaxComputeAtomicCounterBuffers N/A 1
Requires OpenGL 4.4
int gl_MaxTransformFeedbackBuffers N/A 4
int gl_MaxTransformFeedbackInterleavedComponents N/A 64

1: This is the number of fragment shader texture image units.

Retrieved from "https://wikis.khronos.org/opengl/index.php?title=Built-in_Variable_(GLSL)&oldid=12444"