Web 图形与 3D / 系统课时
通过 Uniform 向 GPU 传参
通过 Uniform 向 GPU 传参
让 JavaScript 控制 GLSL 中的颜色、亮度和模型变换,而不必每帧重建顶点缓冲区。本例使用旋转三角形、亮度滑块和两套可切换材质,验证参数上传顺序以及不同 Program 各自保存 Uniform 的规则。
学习目标
- 分清逐顶点读取的属性与一次绘制中共享的 Uniform。
- 使用
getUniformLocation和uniform1f、uniform4fv、uniformMatrix4fv上传数据。 - 让 JavaScript 状态驱动画面,并解释切换 Program 后的参数归属。
Uniform 与顶点属性如何分工
顶点属性 aPosition 从 VBO 按顶点依次读取;uniform 是 GLSL 中的只读输入,通常用来传入一次绘制共享的颜色、时间、光照参数或变换矩阵。同一 Program 内,不同绘制调用可以设置不同 Uniform,但一次调用中的顶点不能各自拥有不同的同名 Uniform 值。
| 数据 | 在 GLSL 中声明 | 数据来源 | 本例用途 |
|---|---|---|---|
| 顶点位置 | in vec2 aPosition |
VBO,通过顶点属性指针读取 | 三角形的三个顶点 |
| 模型变换 | uniform mat4 uModel |
JavaScript 每帧上传 | 旋转整个三角形 |
| 材质颜色 | uniform vec4 uColor |
JavaScript 选择的颜色数组 | 蓝色或橙色 |
| 亮度系数 | uniform float uBrightness |
页面滑块,范围 0~1 | 缩放 RGB 分量 |

查询位置并按 GLSL 类型上传
必须先成功链接 Program,再执行 gl.getUniformLocation(program, 'uColor')。返回的是该 Program 专用的 WebGLUniformLocation,应在链接后缓存;值为 null 通常表示拼写错误,或变量未被实际使用而在链接时被优化掉。
| GLSL 类型 | JavaScript 上传接口 | 合法数据示例 |
|---|---|---|
float |
gl.uniform1f(loc, 0.85) |
单个浮点数 |
vec4 |
gl.uniform4fv(loc, new Float32Array([1, 0, 0, 1])) |
4 个分量 |
mat4 |
gl.uniformMatrix4fv(loc, false, matrix) |
列主序 16 个浮点数 |
int / sampler2D |
gl.uniform1i(loc, 0) |
整数或纹理单元编号 |
上传前调用 gl.useProgram(program);否则位置属于另一 Program 时会触发 INVALID_OPERATION。矩阵接口的第二个参数在 WebGL 中必须为 false,传入数组按列主序解释。改变 Uniform 不会改写 VBO 中的顶点数据。
完整示例:换色、调亮与旋转
把下面内容保存为 index.html,用支持 WebGL 2 的桌面浏览器打开。示例为了集中演示 Uniform,将三角形坐标直接放在裁剪空间,用 mat4 绕 Z 轴旋转,暂不引入观察和投影矩阵。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>WebGL 2 Uniform 演示</title>
<style>
canvas { display: block; max-width: 100%; margin-top: 12px; }
</style>
</head>
<body>
<button id="material">切换蓝色 / 橙色材质</button>
<label>亮度
<input id="brightness" type="range" min="0" max="1" step="0.01" value="0.85">
</label>
<canvas id="scene" width="640" height="360"></canvas>
<script>
const gl = document.querySelector('#scene').getContext('webgl2');
if (!gl) throw new Error('无法创建 WebGL 2 上下文');
const vertexSource = `#version 300 es
layout(location = 0) in vec2 aPosition;
uniform mat4 uModel;
void main() {
gl_Position = uModel * vec4(aPosition, 0.0, 1.0);
}`;
const fragmentSource = `#version 300 es
precision highp float;
uniform vec4 uColor;
uniform float uBrightness;
out vec4 fragColor;
void main() {
fragColor = vec4(uColor.rgb * uBrightness, uColor.a);
}`;
function compile(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader));
}
return shader;
}
function link() {
const program = gl.createProgram();
const vs = compile(gl.VERTEX_SHADER, vertexSource);
const fs = compile(gl.FRAGMENT_SHADER, fragmentSource);
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.deleteShader(vs);
gl.deleteShader(fs);
return program;
}
// 同名 Uniform 在两个 Program 中也有不同的 location。
const programs = [link(), link()];
const uniforms = programs.map(program => {
const loc = {
model: gl.getUniformLocation(program, 'uModel'),
color: gl.getUniformLocation(program, 'uColor'),
brightness: gl.getUniformLocation(program, 'uBrightness')
};
if (Object.values(loc).some(value => value === null)) {
throw new Error('Uniform 未激活或变量名不匹配');
}
return loc;
});
const vao = gl.createVertexArray();
const vbo = gl.createBuffer();
gl.bindVertexArray(vao);
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
-0.6, -0.5, 0.6, -0.5, 0.0, 0.65
]), gl.STATIC_DRAW);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
gl.bindVertexArray(null);
const colors = [
new Float32Array([0.12, 0.50, 0.96, 1]),
new Float32Array([0.98, 0.44, 0.12, 1])
];
let active = 0;
document.querySelector('#material').addEventListener('click', () => {
active = 1 - active;
});
function frame(timeMs) {
const angle = timeMs * 0.001;
const c = Math.cos(angle);
const s = Math.sin(angle);
// mat4 采用列主序,绕 Z 轴旋转而不改变齐次坐标 w。
const model = new Float32Array([
c, s, 0, 0, -s, c, 0, 0,
0, 0, 1, 0, 0, 0, 0, 1
]);
gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
gl.clearColor(0.96, 0.97, 1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(programs[active]);
const loc = uniforms[active];
gl.uniformMatrix4fv(loc.model, false, model);
gl.uniform4fv(loc.color, colors[active]);
gl.uniform1f(loc.brightness, Number(
document.querySelector('#brightness').value
));
gl.bindVertexArray(vao);
gl.drawArrays(gl.TRIANGLES, 0, 3);
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
</script>
</body>
</html>预期结果:页面显示一块 640×360 的浅色画布,蓝色三角形持续绕中心旋转;点击按钮改为橙色,再点一次恢复蓝色;亮度滑块调至 0 时三角形变黑,背景颜色不变。页面控制台不应出现 Shader 编译或 Program 链接错误。
切换 Program 时如何避免传错参数
示例使用两个独立链接的 Program,即使 Shader 源码相同,也分别缓存 uModel、uColor 和 uBrightness 的位置。gl.useProgram(programs[1]) 只选择新的当前 Program:不会把 A 的 Uniform 复制给 B,也不会清空 A 原有的 Uniform 值。切回 A 后,它此前的值仍在;本例为了确保 JavaScript 状态与画面一致,每帧都对当前 Program 重传三个参数。成功重新链接某个 Program 则会重置其活动 Uniform,并使旧位置失效,需要重新查询。
| 现象 | 常见原因 | 修复与检查 |
|---|---|---|
getUniformLocation 返回 null |
变量名错误或未在 Shader 中实际参与计算 | 检查 GLSL 声明及使用处;不要把 null 当成位置 0 |
切换材质后报 INVALID_OPERATION |
B Program 使用了从 A 查询到的位置 | 将 location 按 Program 分别保存,并先 useProgram |
| 矩阵上传后物体不按预期旋转 | 数组按行主序编排或把 transpose 传为 true |
按列主序排列 16 个分量,并固定传 false |
| 修改亮度却未改变画面 | uniform1f 未在绘制前执行,或 GLSL 没有使用对应值 |
在 drawArrays 前上传;检查片元着色器中是否乘以 uBrightness |
调试时可在渲染后通过 gl.getUniform(programs[active], uniforms[active].brightness) 检查最近上传的浮点值;亮度滑块为 0.25 时,应读到接近 0.25 的值。Uniform 适合每次绘制共享的小规模参数,逐顶点颜色或位置仍应交给顶点缓冲区与属性输入。