Uniform (GLSL)

From OpenGL.org
Revision as of 01:23, 8 July 2012 by Alfonse (Talk | contribs) (GLSL definition and behavior)

Jump to: navigation, search



GLSL definition and behavior

Uniform variables must be defined in GLSL at global scope.


struct TheStruct
  vec3 first;
  vec4 second;
  mat4x3 third;
uniform vec3 oneUniform;
uniform TheStruct aUniformOfArrayType;
uniform mat4 matrixArrayUniform[25];
uniform TheStruct uniformArrayOfStructs[10];






Active uniforms



Implementation limits






Uniform management



Each active uniform has a location. The location is a numeric handle to that uniform; it functions as a shorthand that is faster to search for than the uniform's name. Uniform locations are unique to a specific program. Even if you define the exact same set of uniforms in two different programs, OpenGL does not guarantee that the same uniforms in the two programs will have the same location. So you must keep track of each uniform location for each program.


 GLint glGetUniformLocation(GLuint program​, const char *name​);

The program​ is the program object name that you want to find a uniform for. This must be a program that has successfully linked. And name​ is the name of the uniform you wish to search for. The return value is -1 if name​ isn't an active uniform in the program, name​ is the name of a uniform block (see below), or program​ isn't a successfully linked program. Otherwise, the return value is the uniform's location.


struct MyStruct
  vec2 firstField;
  vec4 secondField;
  mat2 thirdField;
uniform MyStruct mainUniform;

The name "mainUniform" does not have a location; calling glGetUniformLocation on it will return -1. However, each of mainUniform's fields do have a location. So you can call glGetUniformLocation(program, "mainUniform.secondField");​ just fine.

Arrays are handled simply. Take this GLSL uniform definition:

uniform vec3 positions[20];



Arrays of structures are special. Take this as an example:

uniform MyStruct manyStructs[3];



However, in order to change a uniform value, you must first bind the program to the context with glUseProgram. The glUniform* functions do not take a program object name; they use the currently bound program. If you are using GL 4.1 or better, or ARB_separate_shader_objects, you may use the glProgramUniform* functions to set uniforms directly on a program.

Sampler uniforms


Uniform blocks and buffers


Samplers cannot be part of uniform blocks.

Accessing uniform information



 void glGetUniformIndices(GLuint program​, GLsizei uniformCount​, const char ** uniformNames​, GLuint *uniformIndices​);

This will cause the array uniformIndices​, which is of size uniformCount​ to be filled with the indices for the strings in the uniformNames​ list (also of size uniformCount​); If a uniform name in the string list doesn't correspond to the name of an active uniform, then the corresponding index in uniformIndices​ will be GL_INVALID_INDEX.

The uniform indices are between 0 and GL_ACTIVE_UNIFORMS (an integer queried with glGetProgramiv). If you simply want to iterate over all of the available uniforms, you may simply query GL_ACTIVE_UNIFORMS and loop over each uniform index on the half-open range [0, GL_ACTIVE_UNIFORMS).


 void glGetActiveUniformName( GLuint program​, GLuint uniformIndex​, GLsizei bufSize​, GLsizei *length​, char *uniformName​);

This function stores the name in the uniformName​ buffer, which is of size bufSize​ bytes. The actual length of uniformName​ is stored in length​ (unless length​ is NULL, which is allowed).


 void glGetActiveUniformsiv( GLuint program​, GLsizei uniformCount​, GLconstuint *uniformIndices​, GLenum pname​, GLint *params​ );

The uniformIndices​ array is a list of uniform indices uniformCount​ in length. These are the uniforms that the user is asking to acquire. pname​ is an enum that determines what information to query for the uniforms. params​ are the values that get returned; it is an array uniformCount​ in length. One value for each uniform index is generated.

The possibilities for pname​ are:

  • GL_UNIFORM_TYPE: Retrieves the GLenum for the uniform's type.
  • GL_UNIFORM_NAME_LENGTH: The length of that uniform's name.


An older function, superseded by glGetActiveUniformName and glGetActiveUniformsiv also exists.

 void {{apifunc|glGetActiveUniform( GLuint program​, GLuint index​, GLsizei bufSize​, GLsizei *length​, GLint *size​, GLenum *type​, char *name​ );

This retrieves the name as in glGetActiveUniformName, but it also retrieves GL_UNIFORM_TYPE in type​, GL_UNIFORM_SIZE in size​, and GL_UNIFORM_NAME_LENGTH in length​.

The length of the longest uniform name in a program can be queried with GL_ACTIVE_UNIFORM_MAX_LENGTH through glGetProgramiv. You can use this along with GL_ACTIVE_UNIFORMS to allocate an array of strings that will be sufficiently large enough to hold the string names for a program's uniforms.