怎样在HTML中用WebGL的uniform变量向着色器传递变换矩阵参数
作者：袖梨
2026-06-12
必须先用gl.getUniformLocation获取uniform位置并检查是否为null，再用gl.uniformMatrix4fv传列主序的16元素数组，且需确保当前绑定正确program。
如何获取uniform location并检查是否有效
WebGL中必须先用 gl.getUniformLocation 获取 uniform 变量的位置（location），再用 gl.uniformMatrix4fv 传值。如果变量名拼错、着色器没编译成功、或变量未被使用，gl.getUniformLocation 会返回 null——这是最常踩的坑。
- 确保顶点着色器里声明了
uniform mat4 u_modelViewProjection;，且该变量在 main 中被实际使用（否则编译器可能优化掉） - 调用
gl.getUniformLocation后立刻检查返回值：const loc = gl.getUniformLocation(program, 'u_modelViewProjection');<br>if (loc === null) { console.error('Uniform not found: u_modelViewProjection'); } - 不要在着色器里用
#define或条件编译隐藏该 uniform，否则它可能“存在但不可见”
为什么必须用 gl.uniformMatrix4fv 而不是 gl.uniform4fv
矩阵是 4×4 共 16 个浮点数，gl.uniform4fv 只能传 4 个分量，直接用会导致数据错位、渲染异常。WebGL 提供专用函数处理矩阵布局，且默认按列主序（column-major）接收数据。
-
gl.uniformMatrix4fv(loc, false, matrixArray)：第二个参数false表示“不转置”，即你传入的数组已是列主序（如 Three.js 的matrix.elements） - 若你手算的是行主序（比如从数学公式直接写成 [r0,r1,r2,r3, ...]），必须设为
true让 WebGL 内部转置，否则矩阵作用方向完全错误 - 数组长度必须为 16；少于 16 会静默截断，多于 16 会报
INVALID_VALUE
常见矩阵构造错误：JavaScript 数组顺序 vs 着色器期望
很多开发者把矩阵当成二维数组写，例如 [[1,0,0,0], [0,1,0,0], ...]，但 gl.uniformMatrix4fv 只接受一维 Float32Array 或普通数组，且要求列主序排列。
- 正确的一维列主序（OpenGL 标准）：
[m00, m10, m20, m30, // 第一列<br> m01, m11, m21, m31, // 第二列<br> m02, m12, m22, m32, // 第三列<br> m03, m13, m23, m33] // 第四列
- Three.js 的
matrix.elements默认就是这个顺序，可直接传；但glMatrix.mat4.create()创建的也是列主序，无需额外转换 - 如果用
new Float32Array(16)手动填充，务必按列填，别按行填——填错后模型可能缩成一个点或翻转消失，很难排查
uniform 传值前必须绑定正确的 program
WebGL 的 uniform location 是和 program 绑定的，但 location 值本身不携带 program 上下文。如果你切换了 program 却忘了重新 bind，或者在错误的 program 上调用 gl.uniformMatrix4fv，值会被写到别的着色器里，甚至静默失败。
立即学习“前端免费学习笔记（深入）”；
- 每次传 uniform 前，确认当前激活的是目标 program：
gl.useProgram(program);<br>const loc = gl.getUniformLocation(program, 'u_modelViewProjection');<br>gl.uniformMatrix4fv(loc, false, matrix);
- 避免全局缓存 location 并跨 program 复用；不同 program 的同名 uniform location 值很可能不同
- 调试时可在
gl.useProgram后加console.assert(gl.getParameter(gl.CURRENT_PROGRAM) === program)验证
