WebGLRenderingContext: getUniformLocation() 方法

语法

getUniformLocation(program, name)

参数

program

要从中查找指定 uniform 变量的 WebGLProgram。

name

一个字符串，指定要返回其位置的 uniform 变量的名称。名称中不能包含任何空格，并且不能使用此函数来获取任何以保留字符串 "gl_" 开头的 uniform 的位置，因为那些是 WebGL 层内部使用的。

可能的值对应于 getActiveUniform 返回的 uniform 名称；有关声明的 uniform 如何映射到 uniform 位置名称的详细信息，请参阅该函数。

此外，对于声明为数组的 uniform，以下名称也有效：

• 不带 [0] 后缀的 uniform 名称。例如，为 arrayUniform 返回的位置等同于为 arrayUniform[0] 返回的位置。
• 带整数索引的 uniform 名称。例如，为 arrayUniform[2] 返回的位置将直接指向 arrayUniform uniform 的第三个条目。

返回值

一个 WebGLUniformLocation 值，指示命名变量的位置（如果存在）。如果指定的变量不存在，则返回 null。

WebGLUniformLocation 是一个不透明的值，用于唯一标识 uniform 变量在 GPU 内存中的位置。有了这个值，您就可以调用其他 WebGL 方法来访问 uniform 变量的值。

错误

可能发生以下错误；要检查 getUniformLocation() 返回后的错误，请调用 getError()。

GL_INVALID_VALUE

program 参数不是 WebGL 生成的值或对象。

GL_INVALID_OPERATION

program 参数不对应 WebGL 生成的 GLSL 程序，或者指定的程序尚未成功链接。

示例

在此示例中，取自文章 A basic 2D WebGL animation example 的 animateScene() 方法，它从着色程序获取三个 uniform 的位置，然后设置每个 uniform 的值。

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]);

将当前着色程序设置为 shaderProgram 后，此代码会获取三个 uniform "uScalingFactor"、"uGlobalColor" 和 "uRotationVector"，每次调用 getUniformLocation() 获取一个 uniform。

然后设置这三个 uniform 的值

• uScalingFactor uniform — 一个 2 分量的顶点 — 从变量 currentScale 接收水平和垂直缩放因子。
• uniform uRotationVector 被设置为变量 currentRotation 的内容。这同样是一个 2 分量的顶点。
• 最后，uniform uGlobalColor 被设置为颜色 [0.1, 0.7, 0.2, 1.0]，此 4 分量向量中的分量分别代表红色、绿色、蓝色和 alpha 的值。

完成此操作后，下一次调用着色函数时，它们各自名为 uScalingFactor、uGlobalColor 和 uRotationVector 的变量都将具有 JavaScript 代码提供的值。

规范

浏览器兼容性

另见

• WebGLRenderingContext.getAttribLocation()
• WebGLRenderingContext.getActiveUniform()
• WebGLUniformLocation