GLSL 1.2 Reference

From DGE
Jump to: navigation, search

Vertex Shader Special Variables

Some OpenGL operations occur in fixed functionality between the vertex processor and the fragment processor. Shaders communicate with the fixed functionality of OpenGL through the use of built-in variables.

These built-in vertex shader variables for communicating with fixed functionality are intrinsically declared as follows:

out vec4 gl_Position;    // must be written to
out float gl_PointSize;  // may be written to
in int gl_VertexID;
out float gl_ClipDistance[]; // may be written to
out vec4 gl_ClipVertex;  // may be written to, deprecated

The variable gl_Position is available only in the vertex language and is intended for writing the homogeneous vertex position. All executions of a well-formed vertex shader executable must write a value into this variable. It can be written at any time during shader execution. It may also be read back by a vertex shader after being written. This value will be used by primitive assembly, clipping, culling, and other fixed functionality operations that operate on primitives after vertex processing has occurred. Compilers may generate a diagnostic message if they detect gl_Position is not written, or read before being written, but not all such cases are detectable. Its value is undefined if the vertex shader executable does not write gl_Position.

The variable gl_PointSize is available only in the vertex language and is intended for a vertex shader to write the size of the point to be rasterized. It is measured in pixels.

The variable gl_VertexID is a vertex shader an input variable that holds an integer index for the vertex, as defined by the OpenGL Graphics System Specification. While the variable gl_VertexID is always present, its value is not always defined. For details on when it is defined, see the "Shader Inputs" subsection of section 2.20.3 "Shader Execution" of the OpenGL Graphics System Specification, Version 3.0.

The variable gl_ClipDistance provides the forward compatible mechanism in the vertex shader for controlling user clipping. To use this, a vertex shader is responsible for maintaining a set of clip planes, computing the distance from the vertex to each clip plane, and storing distances to the plane in gl_ClipDistance[i] for each plane i. A distance of 0 means the vertex is on the plane, a positive distance means the vertex is inside the clip plane, and a negative distance means the point is outside the clip plane. 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 sized by the shader either redeclaring it with a size or indexing it only with integral constant expressions. This needs to size the array to include all the clip planes that are enabled via the OpenGL API; if the size does not include all enabled planes, 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 planes are enabled. The shader must also set all values in gl_ClipDistance that have been enabled via the OpenGL API, or results are undefined. Values written into gl_ClipDistance for planes that are not enabled have no effect.

The variable gl_ClipVertex is deprecated. It is available only in the vertex language and provides a place for vertex shaders to write the coordinate to be used with the user clipping planes. The user must ensure the clip vertex and user clipping planes are defined in the same coordinate space. User clip planes work properly only under linear transform. It is undefined what happens under non-linear transform.

If a linked set of shaders forming the vertex stage contains no static write to gl_ClipVertex or gl_ClipDistance, but the application has requested clipping against user clip planes through the API, then the coordinate written to gl_Position is used for comparison against the user clip planes. This behavior is also deprecated. Writing to gl_ClipDistance is the preferred method for user clipping. It is an error for a shader to statically write both gl_ClipVertex and gl_ClipDistance.

If gl_PointSize is not written to, its value is undefined in subsequent pipe stages.

Fragment Shader Special Variables

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

in vec4 gl_FragCoord;                     // deprecated
in bool gl_FrontFacing;                   // deprecated
in float gl_ClipDistance[];
out vec4 gl_FragColor;
out vec4 gl_FragData[gl_MaxDrawBuffers];
out float gl_FragDepth;

Except as noted below, they behave as other input and output variables.

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

Fragment shaders output values to the OpenGL pipeline using the built-in variables gl_FragColor, gl_FragData, and gl_FragDepth, unless the discard statement is executed. Both gl_FragColor and gl_FragData are deprecated; the preferred usage is to explicitly declare these outputs in the fragment shader using the out storage qualifier.

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

Deprecated: 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.

If the frame buffer is configured as a color index buffer then behavior is undefined when using a fragment shader.

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.

Deprecated: 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 errors.

If a shader executes the discard keyword, the fragment is discarded, and the values of any user-defined fragment outputs, gl_FragDepth, gl_FragColor, and gl_FragData 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, and 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 in 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 shader.

The built-in input variable gl_ClipDistance array contains linearly interpolated values for the vertex values written by the vertex shader to the gl_ClipDistance vertex output variable. This array must be sized in the fragment shader either implicitly or explicitly to be the same size as it was sized in the vertex shader. Only elements in this array that have clipping enabled will have defined values.

Vertex Shader Built-In Inputs

Deprecated: The following predeclared input names can be used from within a vertex shader to access the current values of OpenGL state.

in vec4 gl_Color;           // deprecated
in vec4 gl_SecondaryColor;  // deprecated
in vec3 gl_Normal;          // deprecated
in vec4 gl_Vertex;          // deprecated
in vec4 gl_MultiTexCoord0;  // deprecated
in vec4 gl_MultiTexCoord1;  // deprecated
in vec4 gl_MultiTexCoord2;  // deprecated
in vec4 gl_MultiTexCoord3;  // deprecated
in vec4 gl_MultiTexCoord4;  // deprecated
in vec4 gl_MultiTexCoord5;  // deprecated
in vec4 gl_MultiTexCoord6;  // deprecated
in vec4 gl_MultiTexCoord7;  // deprecated
in float gl_FogCoord;       // deprecated

Built-In Constants

The following built-in constants are provided to vertex and fragment shaders. The actual values used are implementation dependent, but must be at least the value shown. Some are deprecated, as indicated in comments.

// Implementation dependent constants. The example values below
// are the minimum values allowed for these maximums.

const int  gl_MaxTextureUnits = 16;
const int  gl_MaxVertexAttribs = 16;
const int  gl_MaxVertexUniformComponents = 1024;
const int  gl_MaxVaryingFloats = 64;            // Deprecated
const int  gl_MaxVaryingComponents = 64;
const int  gl_MaxVertexTextureImageUnits = 16;
const int  gl_MaxCombinedTextureImageUnits = 16;
const int  gl_MaxTextureImageUnits = 16;
const int  gl_MaxFragmentUniformComponents = 1024;
const int  gl_MaxDrawBuffers = 8;
const int  gl_MaxClipDistances = 8;

// The following are deprecated.

const int gl_MaxClipPlanes = 8;                 // deprecated
const int gl_MaxTextureCoords = 8;              // deprecated

The constant gl_MaxVaryingFloats is deprecated, use gl_MaxVaryingComponents instead. The constant gl_MaxClipPlanes is deprecated along with user clip planes, use clip distances and gl_MaxClipDistances instead. The constant gl_MaxTextureCoords is deprecated, use user-defined interpolants instead. Built-In Uniform State

As an aid to accessing OpenGL processing state, the following uniform variables are built into the OpenGL Shading Language. All section numbers and notations are references to the OpenGL Graphics System Specification, Version 3.0.

// Depth range in window coordinates, section 2.12.1

struct gl_DepthRangeParameters {
    float near;  // n
    float far;   // f
    float diff;  // f - n

uniform gl_DepthRangeParameters gl_DepthRange;

The following state is deprecated:

// Deprecated.

uniform mat4 gl_ModelViewMatrix;
uniform mat4 gl_ProjectionMatrix;
uniform mat4 gl_ModelViewProjectionMatrix;
uniform mat4 gl_TextureMatrix[gl_MaxTextureCoords];
// Deprecated.
uniform mat3 gl_NormalMatrix; // transpose of the inverse of the
                              // upper leftmost 3x3 of gl_ModelViewMatrix

uniform mat4    gl_ModelViewMatrixInverse;
uniform mat4    gl_ProjectionMatrixInverse;
uniform mat4    gl_ModelViewProjectionMatrixInverse;
uniform mat4    gl_TextureMatrixInverse[gl_MaxTextureCoords];

uniform mat4    gl_ModelViewMatrixTranspose;
uniform mat4    gl_ProjectionMatrixTranspose;
uniform mat4    gl_ModelViewProjectionMatrixTranspose;
uniform mat4    gl_TextureMatrixTranspose[gl_MaxTextureCoords];

uniform mat4    gl_ModelViewMatrixInverseTranspose;
uniform mat4    gl_ProjectionMatrixInverseTranspose;
uniform mat4    gl_ModelViewProjectionMatrixInverseTranspose;
uniform mat4    gl_TextureMatrixInverseTranspose[gl_MaxTextureCoords];

// Deprecated.

uniform float gl_NormalScale;

// Deprecated.

uniform vec4 gl_ClipPlane[gl_MaxClipPlanes];

// Deprecated.

struct gl_PointParameters {

       float size;
       float sizeMin;
       float sizeMax;
       float fadeThresholdSize;
       float distanceConstantAttenuation;
       float distanceLinearAttenuation;
       float distanceQuadraticAttenuation;

uniform gl_PointParameters gl_Point;

// Deprecated.

struct gl_MaterialParameters {
    vec4 emission; // Ecm
    vec4 ambient;  // Acm
    vec4 diffuse;  // Dcm
    vec4 specular; // Scm
    float shininess; // Srm

uniform gl_MaterialParameters gl_FrontMaterial;
uniform gl_MaterialParameters gl_BackMaterial;

// Deprecated.

struct gl_LightSourceParameters {
    vec4 ambient;               // Acli
    vec4 diffuse;               // Dcli
    vec4 specular;              // Scli
    vec4 position;              // Ppli
    vec4 halfVector;            // Derived: Hi
    vec3 spotDirection;         // Sdli
    float spotExponent;         // Srli
    float spotCutoff;           // Crli
                                // (range: [0.0,90.0], 180.0)
    float spotCosCutoff;        // Derived: cos(Crli)
                                // (range: [1.0,0.0],-1.0)
    float constantAttenuation; // K0
    float linearAttenuation; // K1
    float quadraticAttenuation;// K2

uniform gl_LightSourceParameters gl_LightSource[gl_MaxLights];

struct gl_LightModelParameters {
    vec4 ambient;          // Acs

uniform gl_LightModelParameters gl_LightModel;

// Deprecated.
// Derived state from products of light and material.

struct gl_LightModelProducts {
    vec4 sceneColor;       // Derived. Ecm + Acm * Acs

uniform gl_LightModelProducts gl_FrontLightModelProduct;
uniform gl_LightModelProducts gl_BackLightModelProduct;
struct gl_LightProducts {
    vec4 ambient;          // Acm * Acli
    vec4 diffuse;          // Dcm * Dcli
    vec4 specular;         // Scm * Scli

uniform gl_LightProducts gl_FrontLightProduct[gl_MaxLights];
uniform gl_LightProducts gl_BackLightProduct[gl_MaxLights];

// Deprecated.

uniform vec4 gl_TextureEnvColor[gl_MaxTextureUnits];
uniform vec4 gl_EyePlaneS[gl_MaxTextureCoords];
uniform vec4 gl_EyePlaneT[gl_MaxTextureCoords];
uniform vec4 gl_EyePlaneR[gl_MaxTextureCoords];
uniform vec4 gl_EyePlaneQ[gl_MaxTextureCoords];
uniform vec4 gl_ObjectPlaneS[gl_MaxTextureCoords];
uniform vec4 gl_ObjectPlaneT[gl_MaxTextureCoords];
uniform vec4 gl_ObjectPlaneR[gl_MaxTextureCoords];
uniform vec4 gl_ObjectPlaneQ[gl_MaxTextureCoords];

//                                1.0 / (end - start)
// Deprecated.

struct gl_FogParameters {
       vec4 color;
       float density;
       float start;
       float end;
       float scale; // Derived:

uniform gl_FogParameters gl_Fog;

Built-In Vertex Output and Fragment Input Variables

Unlike user-defined interpolated variables, the mapping between the built-in vertex output variables to the built-in fragment input variables doesn't have a strict one-to-one correspondence. Two sets are provided, one for each language. Their relationship is described below.

It is deprecated to have the GL provide fixed functionality behavior for a programmable pipeline stage. For example, mixing a fixed functionality vertex stage with a programmable fragment stage is deprecated. Pipeline configurations where only a proper subset of stages are being used do not require the unused stages to have shaders.

The following built-in vertex output variables are available, but deprecated. 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.

out vec4  gl_FrontColor;    // deprecated
out vec4  gl_BackColor;     // deprecated
out vec4  gl_FrontSecondaryColor; // deprecated
out vec4  gl_BackSecondaryColor; // deprecated

out vec4 gl_TexCoord[]; // deprecated, at most will be gl_MaxTextureCoords
out float gl_FogFragCoord;// deprecated

For gl_FogFragCoord (deprecated), the value written will be used as the "c" value in section 3.11 of the OpenGL Graphics System Specification, Version 3.0, 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 (deprecated) must either be an integral constant expressions, or this array must be re-declared by the shader with a size. The size can be at most gl_MaxTextureCoords. Using indexes close to 0 may aid the implementation in preserving varying resources.

The following fragment input variables are available in a fragment shader.

in vec2 gl_PointCoord;

The following fragment inputs are also available in a fragment shader, but are deprecated:

in float gl_FogFragCoord;   // deprecated
in vec4 gl_TexCoord[];      // deprecated
in vec4 gl_Color;           // deprecated
in vec4 gl_SecondaryColor;  // deprecated

Deprecated: 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. 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 3.11 of the OpenGL Graphics System Specification, Version 3.0. 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.

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.