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 分量

顶点属性与 Uniform 的数据流及双 Program 状态

查询位置并按 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 轴旋转,暂不引入观察和投影矩阵。

html
<!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 适合每次绘制共享的小规模参数,逐顶点颜色或位置仍应交给顶点缓冲区与属性输入。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通过 Uniform 向 GPU 传参

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通