Part of the WebGL API, the WebGLRenderingContext
method getUniformLocation()
returns the location of a specific uniform variable which is part of a given WebGLProgram
.
The uniform variable is returned as a WebGLUniformLocation
object, which is an opaque identifier used to specify where in the GPU's memory that uniform variable is located.
Once you have the uniform's location, you can access the uniform itself using one of the other uniform access methods, passing in the uniform location as one of the inputs:
The uniform itself is declared in the shader program using GLSL.
getUniformLocation(program, name)
A WebGLUniformLocation
value indicating the location of the named variable, if it exists. If the specified variable doesn't exist, null
is returned instead.
The WebGLUniformLocation
is an opaque value used to uniquely identify the location in the GPU's memory at which the uniform variable is located. With this value in hand, you can call other WebGL methods to access the value of the uniform variable.
Note: The WebGLUniformLocation
type is compatible with the GLint
type when specifying the index or location of a uniform attribute.
The following errors may occur; to check for errors after getUniformLocation()
returns, call getError()
.
GL_INVALID_VALUE
-
The program
parameter is not a value or object generated by WebGL.
GL_INVALID_OPERATION
-
The program
parameter doesn't correspond to a GLSL program generated by WebGL, or the specified program hasn't been linked successfully.
In this example, taken from the animateScene()
method in the article A basic 2D WebGL animation example, obtains the locations of three uniforms from the shading program, then sets the value of each of the three uniforms.
gl.useProgram(shaderProgram);
uScalingFactor = gl.getUniformLocation(shaderProgram, "uScalingFactor");
uGlobalColor = gl.getUniformLocation(shaderProgram, "uGlobalColor");
uRotationVector = gl.getUniformLocation(shaderProgram, "uRotationVector");
gl.uniform2fv(uScalingFactor, currentScale);
gl.uniform2fv(uRotationVector, currentRotation);
gl.uniform4fv(uGlobalColor, [0.1, 0.7, 0.2, 1.0]);
Note: This code snippet is taken from the function animateScene()
in "A basic 2D WebGL animation example." See that article for the full sample and to see the resulting animation in action.
After setting the current shading program to shaderProgram
, this code fetches the three uniforms "uScalingFactor"
, "uGlobalColor"
, and "uRotationVector"
, calling getUniformLocation()
once for each uniform.
Then the three uniforms' values are set:
- The
uScalingFactor
uniform — a 2-component vertex — receives the horizontal and vertical scaling factors from the variable currentScale
. - The uniform
uRotationVector
is set to the contents of the variable currentRotation
. This, too, is a 2-component vertex. - Finally, the uniform
uGlobalColor
is set to the color [0.1, 0.7, 0.2, 1.0]
, the components in this 4-component vector represent the values of red, green, blue, and alpha, respectively.
Having done this, the next time the shading functions are called, their own variables named uScalingFactor
, uGlobalColor
, and uRotationVector
will all have the values provided by the JavaScript code.