4.3. Built-in Uniform Variables

OpenGL was designed as a state machine. It has a variety of state that can be set. At the time graphics primitives are provided to OpenGL for rendering, the current state settings affect how the graphics primitives are treated and ultimately how they are rendered into the frame buffer.

Some applications heavily utilize this aspect of OpenGL. Large amounts of application code might be dedicated to manipulating OpenGL state and providing an interface to allow the end user to change state to produce different rendering effects.

The OpenGL Shading Language makes it easy for these types of applications to take advantage of programmable graphics technology. It contains a variety of built-in uniform variables that allow a shader to access current OpenGL state. In this way, an application can continue to use OpenGL as a state management machine and still provide shaders that combine that state in ways that aren't possible with the OpenGL fixed functionality path. Because they are defined as uniform variables, shaders are allowed to read from these built-in variables but not to write to them.

The built-in uniform variables in Listing 4.1 allow shaders to access current OpenGL state. Any of these variables can be accessed from within either vertex shaders or fragment shaders. If an OpenGL state value has not been modified by an application, it contains the default value as defined by OpenGL, and the corresponding built-in uniform variable is also equal to that value.

Listing 4.1. Built-in uniform variables

// // Matrix state // uniform mat4 gl_ModelViewMatrix; uniform mat4 gl_ProjectionMatrix; uniform mat4 gl_ModelViewProjectionMatrix; uniform mat4 gl_TextureMatrix[gl_MaxTextureCoords]; // // Derived matrix state that provides inverse and transposed versions // of the matrices above. Poorly conditioned matrices may result // in unpredictable values in their inverse forms. // 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] // // Normal scaling // uniform float gl_NormalScale; // // Depth range in window coordinates // struct gl_DepthRangeParameters { float near; // n float far; // f float diff; // f - n }; uniform gl_DepthRangeParameters gl_DepthRange; // // Clip planes // uniform vec4 gl_ClipPlane[gl_MaxClipPlanes]; // // Point Size // struct gl_PointParameters { float size; float sizeMin; float sizeMax; float fadeThresholdSize; float distanceConstantAttenuation; float distanceLinearAttenuation; float distanceQuadraticAttenuation; }; uniform gl_PointParameters gl_Point; // // Material State // 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; // // Light State // 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; // // 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]; // // Texture Environment and Generation // 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]; // // Fog // struct gl_FogParameters { vec4 color; float density; float start; float end; float scale; // 1.0 / (gl_Fog.end - gl_Fog.start) }; uniform gl_FogParameters gl_Fog;

As you can see, these built-in uniform variables have been defined so as to take advantage of the language features whenever possible. Structures are used as containers to group a collection of parameters such as depth range parameters, material parameters, light source parameters, and fog parameters. Arrays define clip planes and light sources. Defining these uniform variables in this way improves code readability and allows shaders to take advantage of language capabilities like looping.

The list of built-in uniform variables also includes some derived state. These state values are things that aren't passed in directly by the application but are derived by the OpenGL implementation from values that are passed. For various reasons, it's convenient to have the OpenGL implementation compute these derived values and allow shaders to access them. The normal matrix (gl_NormalMatrix) is an example of this. It is simply the inverse transpose of the upper-left 3 x 3 subset of the modelview matrix. Because it is used so often, it wouldn't make sense to require shaders to compute this from the modelview matrix whenever it is needed. Instead, the OpenGL implementation is responsible for computing this whenever it is needed, and it is accessible to shaders through a built-in uniform variable.

Here are some examples of how these built-in uniform variables might be used. A vertex shader can transform the incoming vertex position (gl_Vertex) by OpenGL's current modelview-projection matrix (gl_ModelViewProjectionMatrix) with the following line of code:

gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;

Similarly, if a normal is needed, it is transformed by the current normal matrix:

tnorm = gl_NormalMatrix * gl_Normal;

(The transformed normal would typically also need to be normalized in order to be used in lighting computations. This normalization can be done with the built-in function normalize, which is discussed in Section 5.4.)

Here are some other examples of accessing built-in OpenGL state:

gl_FrontMaterial.emission  // emission value for front material
gl_LightSource[0].ambient  // ambient term of light source #0
gl_ClipPlane[3][0]         // first component of user clip plane #3
gl_Fog.color.rgb           // r, g, and b components of fog color
gl_TextureMatrix[1][2][3]  // 3rd column, 4th component of 2nd
                           // texture matrix

The mapping of OpenGL state values to these built-in variables should be straightforward, but if you need more details, see the OpenGL Shading Language Specification document.