Uniform (GLSL)/Explicit Uniform Location

From OpenGL Wiki
< Uniform (GLSL)
Revision as of 17:49, 25 April 2019 by Alfonse (talk | contribs) (Updated warning to match the ambiguity in the specification.)
Jump to navigation Jump to search

Uniforms defined outside of Interface Blocks have a location. This location can be directly assigned in the shader, using this syntax:

layout(location = 2) uniform mat4 modelToWorldMatrix;

Calling glGetUniformLocation(prog, "modelToWorldMatrix") is guaranteed to return 2. It is illegal to assign the same uniform location to two uniforms in the same shader or the same program. Even if those two uniforms have the same name and type, and are defined in different shader stages, it is not legal to explicitly assign them the same uniform location; a linker error will occur.

All non-array/struct types will be assigned a single location. Arrays and structs will be assigned sequentially increasing locations, starting with the given location. Given this:

layout(location = 2) uniform mat4 some_mats[10];

some_mats will be assigned all of the uniform locations on the half-open range [2, 12). This will apply for nested types. Consider the following:

struct Thingy
  vec4 an_array[3];
  int foo;
layout(location = 2) uniform Thingy some_thingies[6];

Each Thingy takes up 4 uniform locations; the first three going to an_array and the fourth going to foo. Thus, some_thingies takes up 24 uniform locations.

Uploading arrays of uniforms with one of the glUniform*v functions will work. For example, uniform location 2 represents the array `some_thingies[0].an_array`. As such, you can upload an array of vec4s to this array with glUniform4fv(2, 3, ...);.

No two uniform declarations in a program can be explicitly assigned the same location. This also means that explicit uniform location ranges cannot overlap. So this is illegal:

layout(location = 2) uniform mat4 some_mats[10];
layout(location = 6) uniform vec4 some_vecs[4];
Warning: While it is clear that two uniforms with different definitions (names and types) in different stages of the same program may not have the same explicit uniform location, what is less clear is whether two uniforms with the same name and type may exist in different stages. If you declare a uniform with the same name/type in two stages of the same program, OpenGL considers them to be the same uniform, with a single uniform location. The question is whether you can get this functionality when providing an explicit location for that uniform. Some parts of the specification suggest that you cannot, while other parts suggest that you can. Some implementations permit this, but the spec itself is ambiguous. This issue is [under active review].

The maximum number of available locations within a single program is GL_MAX_UNIFORM_LOCATIONS, which will be at least 1024 locations. You may not use a uniform location outside of the range [0, GL_MAX_UNIFORM_LOCATIONS), nor may the sequential assignment of uniform locations due to array/struct aggregation go outside of this range.