如何通过WebGL的uniform变量在HTML中传递变换矩阵参数给着色器？

本文共计928个文字，预计阅读时间需要4分钟。

在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) 验证

传矩阵看着简单，真正卡住人的往往是 location 为空、数组顺序反了、program 没绑对这三处——它们都不会抛出明显错误，只会让画面不动或变形。动手前先打印 location 和 matrix 前 4 个值，比反复调 shader 更快定位问题。