Web 图形与 3D / 知识点
WebGL 开发速查手册
手册条目
检测当前浏览器是否支持 WebGL 2,并为不支持的环境提供降级提示。
检测 WebGL 支持
用于判断浏览器是否可使用 WebGL 2,并在不支持时提前给出降级方案,避免初始化渲染流程时出现空白页面或运行异常。
基本用法
通过 Canvas 的 getContext('webgl2') 获取上下文。返回对象表示支持,返回 null 表示当前环境不可用。
const canvas = document.createElement('canvas');
// 尝试创建 WebGL 2 上下文,不修改页面状态
const gl = canvas.getContext('webgl2');
if (gl) {
console.log('WebGL 2 supported');
} else {
console.log('WebGL 2 unavailable');
}预期输出
WebGL 2 supported读取方法:浏览器控制台查看输出;如果输出 WebGL 2 unavailable,说明需要降级处理。
常用检测参数
检测时可以同时获取错误原因,方便定位浏览器、驱动或安全策略问题。
function checkWebGL2() {
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2');
return {
supported: Boolean(gl),
renderer: gl ? gl.getParameter(gl.RENDERER) : 'none'
};
}
console.log(checkWebGL2());预期结果
{ supported: true, renderer: "WebKit WebGL" }实际 renderer 会根据浏览器和显卡驱动变化。
风险与边界
- 浏览器禁用硬件加速时可能检测失败,需要提示用户开启硬件加速。
- 远程桌面、虚拟机或旧显卡环境可能支持 API 但性能不足。
- 不支持 WebGL 2 时不要直接终止页面,可改用 WebGL 1、Canvas 2D 或静态内容。
排障清单
- 打开浏览器设置确认硬件加速已启用。
- 检查控制台是否存在 WebGL 相关安全错误。
- 使用其他浏览器测试,排除单浏览器配置问题。
检测结果只代表 API 可创建,不代表复杂场景一定达到目标帧率。
从 Canvas 获取 WebGL 2 渲染上下文并配置常用上下文属性。
创建 WebGL 上下文
用于从 HTML Canvas 获取 WebGL 2 渲染环境,并设置透明背景、抗锯齿等常用初始化参数,为后续着色器、缓冲区和纹理操作提供基础。
基本语法
Canvas 通过 getContext() 创建渲染上下文:
const canvas = document.querySelector('#canvas');
const gl = canvas.getContext('webgl2', {
alpha: true,
antialias: true,
depth: true
});
if (!gl) {
throw new Error('WebGL 2 is not available');
}
console.log(gl.VERSION);预期输出
WebGL 2.0读取方法:浏览器控制台查看 WebGL 版本信息。
常用配置项
| 参数 | 作用 | 使用场景 |
|---|---|---|
| alpha | 是否启用透明通道 | Canvas 需要叠加页面元素时 |
| antialias | 是否开启抗锯齿 | 提升边缘显示效果 |
| depth | 是否启用深度缓冲 | 三维模型深度排序 |
初始化示例
<canvas id="canvas" width="800" height="600"></canvas>
<script>
const canvas = document.getElementById('canvas');
// 创建 WebGL 2 上下文,失败时提前退出
const gl = canvas.getContext('webgl2', { antialias: true });
// 设置初始清屏颜色并执行一次清理
if (gl) {
gl.clearColor(0.1, 0.1, 0.1, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
}
</script>预期结果
Canvas 显示深色背景风险与边界
- 上下文创建失败通常由浏览器限制、驱动问题或资源不足导致。
- 同一页面创建过多 WebGL 上下文可能触发浏览器回收旧上下文。
- 不需要透明效果时关闭
alpha可以减少部分开销。
排障清单
- 确认 Canvas 宽高已正确设置,避免默认 300×150 导致显示异常。
- 检查
getContext('webgl2')是否返回null。 - 监听
webglcontextlost事件处理上下文丢失场景。
创建成功只代表渲染环境可用,实际绘制仍需完成着色器、缓冲区和渲染循环初始化。
根据显示尺寸和设备像素比调整 Canvas 缓冲区,避免画面模糊或拉伸。
适配画布分辨率
当 Canvas 的 CSS 显示尺寸与内部绘图缓冲区尺寸不一致时,WebGL 会把低分辨率结果放大,造成模糊或比例异常。正确做法是读取显示尺寸,乘以设备像素比更新 canvas.width、canvas.height,并同步调用 gl.viewport()。
基本语法
Canvas 有两套尺寸:
canvas.clientWidth、canvas.clientHeight:页面中的 CSS 显示尺寸。canvas.width、canvas.height:WebGL 实际渲染使用的绘图缓冲区尺寸。window.devicePixelRatio:一个 CSS 像素对应的物理像素数。
只在目标尺寸发生变化时重设缓冲区,避免每帧重新分配显存。
高频用法
下面示例将 320×180 CSS 像素的画布按设备像素比扩展,并在尺寸变化后更新视口。把内容保存为 index.html 后直接用浏览器打开。
<!doctype html>
<meta charset="utf-8">
<style>
html, body { margin: 0; }
canvas {
width: 320px;
height: 180px;
display: block;
border: 1px solid #999;
}
</style>
<canvas id="gl"></canvas>
<script>
const canvas = document.querySelector("#gl");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("WebGL 2 不可用");
function resizeCanvasToDisplaySize() {
// 限制 DPR 可控制移动端和 4K 屏上的显存及填充率开销。
const dpr = Math.min(window.devicePixelRatio || 1, 2);
const width = Math.round(canvas.clientWidth * dpr);
const height = Math.round(canvas.clientHeight * dpr);
if (canvas.width === width && canvas.height === height) return false;
canvas.width = width;
canvas.height = height;
return true;
}
function render() {
if (resizeCanvasToDisplaySize()) {
// viewport 使用绘图缓冲区像素,不是 CSS 像素。
gl.viewport(0, 0, canvas.width, canvas.height);
console.log(
`CSS ${canvas.clientWidth}x${canvas.clientHeight}; ` +
`buffer ${canvas.width}x${canvas.height}; ` +
`DPR ${window.devicePixelRatio || 1}`
);
}
gl.clearColor(0.1, 0.4, 0.8, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
requestAnimationFrame(render);
}
render();
</script>预期结果
页面显示清晰的蓝色 320×180 画布。
在 DPR=2 的设备上,控制台类似:
CSS 320x180; buffer 640x360; DPR 2实际 DPR、浏览器缩放比例和边框计算可能不同,因此缓冲区数值以控制台为准。
常见场景还包括:窗口缩放时持续检测、全屏画布按父容器尺寸适配,以及性能敏感设备将 DPR 上限设为 1.5 或 2。
风险与边界
直接执行 canvas.width = canvas.clientWidth 会忽略高 DPI,画面仍可能模糊。反过来只修改 canvas.width、canvas.height 而不保留 CSS 尺寸,画布在页面中的布局可能改变。
过大的 DPR 会按宽高平方级增加像素量,可能导致帧率下降或显存压力。安全做法是限制 DPR,并用 gl.getParameter(gl.MAX_VIEWPORT_DIMS) 检查设备支持的最大视口尺寸。
修改 canvas.width 或 canvas.height 会重建并清空默认绘图缓冲区,但视口不会自动匹配新尺寸。应在下一次绘制前重新设置 gl.viewport(),并重新清屏。
排障清单
- 画面模糊:确认缓冲区尺寸约等于 CSS 尺寸乘以 DPR。
- 画面只占左下角:尺寸变化后遗漏了
gl.viewport(0, 0, canvas.width, canvas.height)。 - 画面拉伸:投影矩阵仍使用旧宽高比,需要同步更新相机或投影参数。
- 页面频繁抖动:不要同时根据缓冲区尺寸反写 CSS 尺寸,避免尺寸反馈循环。
速查:先调整绘图缓冲区,再更新视口,最后按新宽高比重算投影。
使用视口控制 WebGL 渲染结果在画布中的输出区域。
设置视口
gl.viewport(x, y, width, height) 决定裁剪空间中的渲染结果映射到绘图缓冲区的哪个矩形区域。它适用于全画布渲染、分屏预览、画中画和固定宽高比留边。
基本语法
片段示例:以下调用依赖已创建的 WebGL2RenderingContext gl 和对应的 canvas。
gl.viewport(x, y, width, height);
// 画布尺寸变化后,通常恢复为全缓冲区视口。
gl.viewport(0, 0, canvas.width, canvas.height);x、y 是视口左下角坐标,width、height 是视口尺寸,单位都是绘图缓冲区像素。WebGL 坐标原点位于左下角,不是 DOM 常见的左上角。
高频用法
下面示例在同一画布中设置两个视口,并分别绘制相同三角形。保存为 index.html 后直接打开。
<!doctype html>
<meta charset="utf-8">
<canvas id="gl" width="400" height="200"></canvas>
<script>
const canvas = document.querySelector("#gl");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("WebGL 2 不可用");
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;
}
const vertexShader = compile(gl.VERTEX_SHADER, `#version 300 es
in vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`);
const fragmentShader = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision highp float;
uniform vec4 u_color;
out vec4 outColor;
void main() {
outColor = u_color;
}`);
const program = gl.createProgram();
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
const positions = new Float32Array([
0.0, 0.8,
-0.8, -0.8,
0.8, -0.8
]);
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);
const positionLoc = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(positionLoc);
gl.vertexAttribPointer(positionLoc, 2, gl.FLOAT, false, 0, 0);
gl.useProgram(program);
const colorLoc = gl.getUniformLocation(program, "u_color");
gl.clearColor(0.08, 0.08, 0.08, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
const half = canvas.width / 2;
// 左半区和右半区使用独立视口,但共享同一套顶点数据。
gl.viewport(0, 0, half, canvas.height);
gl.uniform4f(colorLoc, 1.0, 0.45, 0.1, 1.0);
gl.drawArrays(gl.TRIANGLES, 0, 3);
gl.viewport(half, 0, half, canvas.height);
gl.uniform4f(colorLoc, 0.1, 0.65, 1.0, 1.0);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log(Array.from(gl.getParameter(gl.VIEWPORT)));
</script>预期结果
画布左半区显示橙色三角形,右半区显示蓝色三角形。
控制台输出:
[200, 0, 200, 200]常用设置包括:全画布使用 0, 0, canvas.width, canvas.height;左右分屏按缓冲区宽度各取一半;固定宽高比时先计算居中的视口矩形,再把多余区域留作黑边。
输出字段说明
gl.getParameter(gl.VIEWPORT) 返回四个整数:[x, y, width, height]。它反映当前视口状态,适合验证尺寸更新或分屏计算是否正确。
风险与边界
gl.viewport() 只改变后续图元的坐标映射,不会限制 gl.clear() 的清除范围。需要只清除某个子区域时,应同时启用 gl.SCISSOR_TEST 并调用 gl.scissor()。
传入负的宽或高会产生 INVALID_VALUE;超过设备上限的尺寸会被限制。可通过 gl.getParameter(gl.MAX_VIEWPORT_DIMS) 查询上限。
CSS 尺寸与缓冲区尺寸不一致时,使用 clientWidth 计算视口会导致区域偏小。安全做法是始终基于 canvas.width、canvas.height 计算视口,并在画布重设尺寸后重新调用。
排障清单
- 只显示在左下角:视口仍是旧缓冲区尺寸。
- 分屏比例错误:用 CSS 像素计算了视口,或宽度除法后出现取整偏差。
- 清屏影响全部区域:为局部清除启用剪裁测试,而不是只设置视口。
- 图像上下位置相反:记住视口原点在左下角,DOM 坐标转换时需翻转 Y 轴。
速查:视口控制“画到哪里”,剪裁测试控制“哪些像素允许被修改”。
设置清屏颜色并清空颜色、深度或模板缓冲区。
清空渲染缓冲区
在开始绘制一帧、切换场景或重置离屏帧缓冲时,先设置清除值,再用 gl.clear() 清空颜色、深度或模板缓冲区。清除应放在本帧绘制命令之前,否则会把已经绘制的内容覆盖掉。
基本语法
gl.clearColor(r, g, b, a) 设置颜色缓冲区的清除颜色;gl.clearDepth(value) 和 gl.clearStencil(value) 分别设置深度、模板清除值。gl.clear(mask) 执行清除,多个缓冲区使用按位或 | 合并。
const canvas = document.createElement("canvas");
canvas.width = 480;
canvas.height = 270;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl", {
depth: true,
stencil: true
});
if (!gl) {
throw new Error("当前浏览器不支持 WebGL");
}
// 先设置各缓冲区的清除值,再一次性清除本帧需要的缓冲区。
gl.clearColor(0.1, 0.2, 0.3, 1.0);
gl.clearDepth(1.0);
gl.clearStencil(0);
gl.clear(
gl.COLOR_BUFFER_BIT |
gl.DEPTH_BUFFER_BIT |
gl.STENCIL_BUFFER_BIT
);
const color = Array.from(gl.getParameter(gl.COLOR_CLEAR_VALUE))
.map((value) => value.toFixed(1))
.join(",");
console.log(`清屏颜色: ${color}`);预期结果
页面出现一块深蓝灰色画布。
控制台输出:清屏颜色: 0.1,0.2,0.3,1.0实际画布尺寸和颜色显示会受页面缩放、显示器色彩以及浏览器合成影响,但缓冲区清除值应与控制台一致。
常用清除掩码
gl.COLOR_BUFFER_BIT:清空颜色缓冲区,常用于每帧背景重置。gl.DEPTH_BUFFER_BIT:清空深度缓冲区,启用深度测试的 3D 场景通常每帧都要清除。gl.STENCIL_BUFFER_BIT:清空模板缓冲区,仅在创建上下文时启用模板并实际使用模板测试时需要。
只绘制纯 2D 内容且未使用深度、模板测试时,通常只清除颜色缓冲区即可。
高频用法
每帧开头清除颜色和深度缓冲区。以下为片段示例,依赖已创建的 gl 上下文:
gl.clearColor(0.02, 0.02, 0.03, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);预期结果
后续绘制从统一背景色和默认深度值开始,不残留上一帧内容。仅清除颜色缓冲区时,不会重置已有深度值;如果下一次绘制仍启用深度测试,旧深度数据可能导致片元被意外丢弃。
风险与边界
启用 gl.SCISSOR_TEST 时,gl.clear() 只清除裁剪框内区域;颜色写掩码、深度写掩码和模板写掩码也会影响清除结果。出现“只清了一块”或“深度没有重置”时,先恢复完整视口和写掩码,再执行清除。以下为片段示例,依赖已创建的 gl 上下文:
gl.disable(gl.SCISSOR_TEST);
gl.colorMask(true, true, true, true);
gl.depthMask(true);
gl.stencilMask(0xFF);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT | gl.STENCIL_BUFFER_BIT);预期结果
允许写入的整个缓冲区被清除,不再受裁剪框或写掩码限制。默认帧缓冲在浏览器完成页面合成后可能不保留内容。需要跨帧读取像素时,优先渲染到自建帧缓冲对象;不要仅依赖 preserveDrawingBuffer: true,它可能增加内存和合成开销。
兼容性
上述 API 同时适用于 WebGL 1 和 WebGL 2。WebGL 2 还提供 clearBuffer* 系列方法,可按绘制缓冲区清除,但普通单画布渲染使用 gl.clear() 更通用。
编写、创建并编译负责顶点坐标和顶点属性处理的顶点着色器。
创建顶点着色器
在提交顶点数据前,用顶点着色器把模型坐标转换为裁剪空间坐标,并处理每个顶点的属性。创建后必须设置源码、编译并检查状态;编译失败时不要继续链接程序。
基本语法
创建流程固定为 createShader → shaderSource → compileShader → 检查 COMPILE_STATUS。顶点着色器必须为 gl_Position 赋值;点精灵还可设置 gl_PointSize。
const canvas = document.createElement("canvas");
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器不支持 WebGL");
}
const vertexSource = `
attribute vec2 a_position;
uniform float u_pointSize;
void main() {
// 输入坐标已经位于 -1 到 1 的裁剪空间,z 设为 0,w 设为 1。
gl_Position = vec4(a_position, 0.0, 1.0);
gl_PointSize = u_pointSize;
}
`;
const vertexShader = gl.createShader(gl.VERTEX_SHADER);
if (!vertexShader) {
throw new Error("无法创建顶点着色器对象");
}
gl.shaderSource(vertexShader, vertexSource);
gl.compileShader(vertexShader);
const compiled = gl.getShaderParameter(
vertexShader,
gl.COMPILE_STATUS
);
if (!compiled) {
const log = gl.getShaderInfoLog(vertexShader) || "未知编译错误";
gl.deleteShader(vertexShader);
throw new Error(`顶点着色器编译失败: ${log}`);
}
console.log(`顶点着色器编译成功: ${compiled}`);预期输出
顶点着色器编译成功: true示例只验证顶点着色器是否成功编译;要实际绘制,还需创建片元着色器、链接程序,并为 a_position 与 u_pointSize 提供数据。
关键接口
gl.createShader(gl.VERTEX_SHADER):创建顶点着色器对象,返回null时应立即停止。gl.shaderSource(shader, source):绑定 GLSL ES 源码,源码字符串中的换行会影响错误日志行号。gl.compileShader(shader):触发编译,调用本身不代表编译成功。gl.getShaderParameter(shader, gl.COMPILE_STATUS):读取编译结果。gl.getShaderInfoLog(shader):读取语法、类型和版本错误,生产环境可记录日志,但不要直接向终端用户暴露完整源码。
高频用法
为输入属性保留清晰语义,并在 CPU 侧按名称查询位置。以下为片段示例,依赖已成功创建并链接的 program:
const positionLocation = gl.getAttribLocation(program, "a_position");
const pointSizeLocation = gl.getUniformLocation(program, "u_pointSize");预期结果
链接成功且变量未被优化掉时,positionLocation 为大于等于 0 的整数,pointSizeLocation 为 WebGLUniformLocation 对象。属性位置返回 -1 通常表示名称写错、变量未参与最终输出或被编译器优化掉。
风险与边界
不要只检查 JavaScript 是否抛错。GLSL 编译错误通常记录在着色器日志中,若跳过 COMPILE_STATUS 检查,后续链接失败会把问题推迟到更难定位的位置。
着色器对象成功链接到程序后可调用 gl.deleteShader() 释放引用;程序仍保留已链接代码。着色器被附加时,删除操作会延迟回收,但为便于排障,应先完成编译、链接和日志检查。
顶点着色器输出的 gl_Position 是裁剪空间坐标。若直接传入像素坐标而未转换到 [-1, 1] 范围,几何体通常会落到视锥外而不可见。
排障清单
- 日志提示版本或
attribute语法错误:确认上下文是 WebGL 1 还是 WebGL 2。 - 编译成功但属性位置为
-1:检查变量是否真正参与gl_Position计算。 - 画面为空:确认缓冲区绑定、属性步长、数据类型和
enableVertexAttribArray均正确。 - 点未显示或尺寸异常:确认绘制模式为
gl.POINTS,并检查设备支持的点大小范围。
兼容性
WebGL 1 使用 GLSL ES 1.00,顶点输入关键字是 attribute。WebGL 2 使用 GLSL ES 3.00,需要在源码首行声明 #version 300 es,并把 attribute 改为 in;两种语法不能混用。
编写、创建并编译负责像素颜色计算的片元着色器。
创建片元着色器
片元着色器负责计算每个片元最终写入颜色缓冲区的颜色。创建时要同时保证 GLSL 版本、输出变量写法和当前 WebGL 上下文匹配。
基本语法
WebGL 1 使用 gl_FragColor 输出颜色;WebGL 2 使用 #version 300 es 和自定义 out 变量。两者不能混写。
可运行示例
下面代码优先创建 WebGL 2,上下文不可用时回退到 WebGL 1,并按上下文选择对应片元着色器源码。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="canvas" width="320" height="180"></canvas>
<script>
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器或设备不支持 WebGL");
}
const isWebGL2 = typeof WebGL2RenderingContext !== "undefined"
&& gl instanceof WebGL2RenderingContext;
const fragmentSource = isWebGL2
? `#version 300 es
precision mediump float;
uniform vec4 uColor;
out vec4 outColor;
void main() {
outColor = uColor;
}`
: `precision mediump float;
uniform vec4 uColor;
void main() {
gl_FragColor = uColor;
}`;
const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
if (!fragmentShader) {
throw new Error("创建片元着色器对象失败");
}
gl.shaderSource(fragmentShader, fragmentSource);
gl.compileShader(fragmentShader);
const compiled = gl.getShaderParameter(
fragmentShader,
gl.COMPILE_STATUS
);
console.log(`context=${isWebGL2 ? "WebGL2" : "WebGL1"}`);
console.log(`compileStatus=${compiled}`);
if (!compiled) {
console.error(gl.getShaderInfoLog(fragmentShader));
gl.deleteShader(fragmentShader);
}
</script>
</body>
</html>预期输出
context=WebGL2
compileStatus=true不支持 WebGL 2 时第一行会是 context=WebGL1,编译状态仍应为 true。
关键写法
precision mediump float;为片元浮点运算声明默认精度,WebGL 片元着色器通常必须显式指定。uniform vec4 uColor;从 JavaScript 接收统一颜色值,实际绘制前还需在链接后的程序上设置该 uniform。gl.shaderSource()只写入源码;必须调用gl.compileShader()才会执行编译。
风险与边界
在 WebGL 2 上使用 gl_FragColor,或在 WebGL 1 上使用 #version 300 es,会触发编译失败,后续链接程序也会失败。安全做法是固定项目使用的上下文版本,或像示例一样为两个版本分别维护源码。
mediump 在部分移动 GPU 上精度有限,高动态范围颜色、复杂光照或大量累计计算可能出现色带和误差。此时可改用 highp,但应先通过 gl.getShaderPrecisionFormat() 检查设备支持情况。
速查:创建对象、写入源码、编译、检查 COMPILE_STATUS,四步缺一不可。
读取着色器编译状态和错误日志,快速定位 GLSL 语法问题。
检查着色器错误
着色器没有成功编译时,先读取 COMPILE_STATUS,再读取 getShaderInfoLog()。不要等到程序链接或绘制失败后才反查 GLSL 源码。
检查方法
gl.getShaderParameter(shader, gl.COMPILE_STATUS) 返回布尔值;为 false 时,gl.getShaderInfoLog(shader) 通常包含错误行号、错误类型和附近标记。
可运行示例
下面故意遗漏分号,验证错误检测流程。错误日志的具体格式由浏览器和 GPU 驱动决定,因此代码同时打印带行号的源码。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="canvas" width="320" height="180"></canvas>
<script>
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器或设备不支持 WebGL");
}
const source = `precision mediump float;
void main() {
gl_FragColor = vec4(1.0, 0.2, 0.1, 1.0)
}`;
const shader = gl.createShader(gl.FRAGMENT_SHADER);
if (!shader) {
throw new Error("创建着色器对象失败");
}
gl.shaderSource(shader, source);
gl.compileShader(shader);
const compiled = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
const infoLog = gl.getShaderInfoLog(shader) || "";
console.log(`compileStatus=${compiled}`);
if (!compiled) {
const numberedSource = source
.split("\n")
.map((line, index) => `${index + 1}: ${line}`)
.join("\n");
console.error(infoLog.trim() || "<EMPTY_SHADER_LOG>");
console.error(numberedSource);
gl.deleteShader(shader);
}
</script>
</body>
</html>预期输出
compileStatus=false
<GLSL_ERROR_LOG>
1: precision mediump float;
2:
3: void main() {
4: gl_FragColor = vec4(1.0, 0.2, 0.1, 1.0)
5: }<GLSL_ERROR_LOG> 会替换为浏览器实际日志,通常会指向第 4 行附近,并提示缺少分号或语法错误。
输出读取
优先看日志中的行号,再对照编号源码。日志可能使用 ERROR: 0:4、0(4) 等不同格式,其中最后的数字通常对应源码行号。
日志为空不代表编译成功,最终判断必须以 COMPILE_STATUS 为准。某些驱动只返回简短描述,因此保留带行号源码比单独打印日志更可靠。
排障清单
- 确认源码首行的 GLSL 版本与
webgl或webgl2上下文一致。 - 检查分号、括号、变量类型、函数返回值和未声明标识符。
- 检查片元着色器是否声明浮点精度。
- 编译通过但链接失败时,再分别读取顶点着色器日志和
gl.getProgramInfoLog(program)。
风险与边界
只打印日志、不检查状态,可能把空日志误判为成功;只检查状态、不打印源码,则会在动态拼接 GLSL 时难以定位真实行号。安全做法是失败时同时记录状态、日志和编号源码,但生产环境应避免把包含业务规则或用户生成内容的完整着色器源码上传到公共日志。
速查:COMPILE_STATUS 决定成功与否,getShaderInfoLog() 负责解释失败原因。
将顶点着色器和片元着色器链接为可用于绘制的程序对象。
链接着色器程序
目标是把已编译的顶点着色器和片元着色器链接成可激活的 WebGLProgram,并用 LINK_STATUS 和当前程序状态确认它可以进入后续 attribute、uniform 与绘制配置。
前置条件
- 顶点着色器和片元着色器必须来自同一个
WebGLRenderingContext,且各自的COMPILE_STATUS为true。 - WebGL 1 中跨阶段使用的
varying需要在两侧保持名称、类型和数组大小兼容;不一致通常会在链接阶段失败。 - 只有链接成功后才查询
gl.getAttribLocation()和gl.getUniformLocation();这些位置属于具体程序,不能跨程序复用。
操作步骤
- 编译顶点着色器和片元着色器;任一编译失败就停止。
- 用
gl.createProgram()创建程序,并用gl.attachShader()附加两个着色器。 - 调用
gl.linkProgram(program),随后检查gl.LINK_STATUS。 - 仅在链接成功后调用
gl.useProgram(program),再查询并缓存该程序需要的位置。
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
if (!gl) {
throw new Error('当前浏览器不支持 WebGL');
}
function compileShader(type, source) {
const shader = gl.createShader(type);
if (!shader) {
throw new Error('无法创建着色器对象');
}
gl.shaderSource(shader, source);
gl.compileShader(shader);
// 编译失败时立即清理,避免把源码错误误判成程序链接错误。
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
const log = gl.getShaderInfoLog(shader);
gl.deleteShader(shader);
throw new Error(log || '着色器编译失败');
}
return shader;
}
function linkProgram(vertexShader, fragmentShader) {
const program = gl.createProgram();
if (!program) {
throw new Error('无法创建程序对象');
}
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
const log = gl.getProgramInfoLog(program);
// 失败对象不再复用,连同本次创建的着色器一起释放。
gl.detachShader(program, vertexShader);
gl.detachShader(program, fragmentShader);
gl.deleteProgram(program);
gl.deleteShader(vertexShader);
gl.deleteShader(fragmentShader);
throw new Error(log || '程序链接失败');
}
return program;
}
const vertexShader = compileShader(
gl.VERTEX_SHADER,
`attribute vec2 aPosition;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
}`
);
const fragmentShader = compileShader(
gl.FRAGMENT_SHADER,
`precision mediump float;
void main() {
gl_FragColor = vec4(0.2, 0.6, 1.0, 1.0);
}`
);
const program = linkProgram(vertexShader, fragmentShader);
gl.useProgram(program);
const aPosition = gl.getAttribLocation(program, 'aPosition');
// 链接完成后可释放独立着色器对象;program 的已链接可执行代码仍然有效。
gl.detachShader(program, vertexShader);
gl.detachShader(program, fragmentShader);
gl.deleteShader(vertexShader);
gl.deleteShader(fragmentShader);
console.log('program linked:', gl.getProgramParameter(program, gl.LINK_STATUS));
console.log('current program set:', gl.getParameter(gl.CURRENT_PROGRAM) === program);
console.log('aPosition location valid:', aPosition >= 0);预期输出
program linked: true
current program set: true
aPosition location valid: true验证检查点
LINK_STATUS === true 只表示两个阶段已经组成合法程序,不代表顶点缓冲或 uniform 已配置完成。getAttribLocation() 返回 -1 表示对应 attribute 不存在或被优化掉;getUniformLocation() 找不到 uniform 时返回 null。
多个程序之间切换时,分别缓存各自的 attribute 与 uniform 位置,并在绘制前调用对应的 gl.useProgram()。不要在渲染循环里重复查询这些位置。
失败处理
链接失败时立即读取 gl.getProgramInfoLog(program),不要继续配置 attribute、uniform 或发起绘制。优先检查两个着色器的 COMPILE_STATUS,再检查跨阶段 varying 的名称、类型和数组大小;来自不同 WebGL 上下文的对象也不能混用。
不要仅凭“屏幕没有画面”判断链接失败。忘记 gl.useProgram()、顶点缓冲未绑定或必需的 uniform 未赋值,同样可能导致无可见输出。WebGL 2 仍使用相同的程序链接 API,但着色器源码需要符合 GLSL ES 3.00 语法。
恢复正常状态
新程序链接失败时,删除无效对象,修正源码后重新创建和链接,不要继续复用失败的程序。若应用已有稳定程序,可保留其引用;新程序未通过验证时继续 gl.useProgram(previousProgram),避免把未验证程序切入绘制链路。
速查:只有 LINK_STATUS === true 且目标程序已被 gl.useProgram() 激活后,才进入该程序自己的 attribute、uniform 和绘制配置。
检查程序链接与验证状态,定位着色器接口不匹配等问题。
检查程序链接错误
目标是确认顶点着色器与片元着色器能否成功组成 WebGL 程序,并在失败时从 LINK_STATUS、VALIDATE_STATUS 和程序日志定位接口不匹配或当前状态异常。处理完成后,应只让链接成功且验证符合预期的程序进入绘制流程。
前置条件
- 已取得有效的 WebGL 上下文,并保留顶点、片元着色器源码。
- 每个着色器都已检查
COMPILE_STATUS;单个着色器编译失败时应先处理编译错误,不继续链接。 - 调试环境可以查看浏览器开发者工具控制台;程序日志由浏览器和显卡驱动生成,具体措辞不能作为固定断言。
按顺序检查链接与验证
先链接程序并读取 LINK_STATUS。只有链接成功后,才有必要调用 gl.validateProgram(program) 并读取 VALIDATE_STATUS。链接和验证的诊断信息都通过 gl.getProgramInfoLog(program) 获取。
下面的主示例先故意制造 varying 类型不匹配,再创建一个正常程序。可直接粘贴到浏览器开发者工具控制台运行。
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
if (!gl) {
throw new Error('当前浏览器不支持 WebGL');
}
function compile(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
const log = gl.getShaderInfoLog(shader);
gl.deleteShader(shader);
throw new Error(log || '着色器编译失败');
}
return shader;
}
function link(vertexSource, fragmentSource) {
const vertexShader = compile(gl.VERTEX_SHADER, vertexSource);
const fragmentShader = compile(gl.FRAGMENT_SHADER, fragmentSource);
const program = gl.createProgram();
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
// linkProgram 已完成后,可以删除独立 shader 对象;程序仍保留链接结果。
gl.deleteShader(vertexShader);
gl.deleteShader(fragmentShader);
return program;
}
const badProgram = link(
`varying vec3 vColor;
void main() {
vColor = vec3(1.0, 0.0, 0.0);
gl_Position = vec4(0.0, 0.0, 0.0, 1.0);
}`,
`precision mediump float;
varying vec4 vColor;
void main() {
gl_FragColor = vColor;
}`
);
console.log('bad LINK_STATUS =', gl.getProgramParameter(badProgram, gl.LINK_STATUS));
console.log('bad PROGRAM_INFO_LOG =', gl.getProgramInfoLog(badProgram) || '<empty>');
gl.deleteProgram(badProgram);
const goodProgram = link(
`void main() {
gl_Position = vec4(0.0, 0.0, 0.0, 1.0);
}`,
`precision mediump float;
void main() {
gl_FragColor = vec4(0.0, 1.0, 0.0, 1.0);
}`
);
console.log('good LINK_STATUS =', gl.getProgramParameter(goodProgram, gl.LINK_STATUS));
gl.useProgram(goodProgram);
gl.validateProgram(goodProgram);
console.log('good VALIDATE_STATUS =', gl.getProgramParameter(goodProgram, gl.VALIDATE_STATUS));
console.log('good PROGRAM_INFO_LOG =', gl.getProgramInfoLog(goodProgram) || '<empty>');预期输出
bad LINK_STATUS = false
bad PROGRAM_INFO_LOG = <浏览器或显卡驱动返回的 varying 类型不匹配信息>
good LINK_STATUS = true
good VALIDATE_STATUS = true
good PROGRAM_INFO_LOG = <empty 或驱动警告>第一条程序日志的具体文字可能不同,但 bad LINK_STATUS 应为 false;正常程序应成功链接。在这个不依赖纹理、framebuffer 或顶点属性的最小示例中,验证通常也应通过。
判断状态与日志
LINK_STATUS 表示已编译的顶点和片元着色器能否组成完整程序。常见失败原因包括跨阶段 varying 名称、类型或数组长度不一致,以及着色器资源使用超过实现限制。
VALIDATE_STATUS 表示已链接程序在当前 WebGL 状态下是否通过实现的有效性检查。它受当前状态影响,不能代替 LINK_STATUS,也不适合作为每帧固定检查。
PROGRAM_INFO_LOG 可能为空,也可能包含警告。调试时应先判断状态值,再把日志作为诊断信息;不要依赖某个浏览器固定的错误文案。
验证与失败处理
链接失败后立即停止该程序的初始化分支,不要继续查询 attribute、uniform 或调用 gl.useProgram(program)。否则后续调用可能得到无效位置、产生 INVALID_OPERATION,最终表现为黑屏且掩盖最初的链接原因。
排查 varying 错误时,对照两个阶段中的变量名、类型和数组长度;日志为空时重新检查每个 shader 的 COMPILE_STATUS 与 getShaderInfoLog。验证失败时,再检查程序实际使用的纹理单元、纹理目标、采样器以及 framebuffer 等当前状态。
恢复正常绘制
修正着色器接口或相关 WebGL 状态后,重新编译并链接一个新的程序对象,再确认 LINK_STATUS 为 true。如果此前失败的程序仍存在,应调用 gl.deleteProgram 释放它;绘制阶段只保留已经确认可用的程序。
速查:着色器编译看 getShaderInfoLog,程序链接和验证看 getProgramInfoLog;先检查状态,再读取日志。
激活指定着色器程序,并减少渲染过程中的无效程序切换。
切换着色器程序
使用 gl.useProgram(program) 激活已经链接成功的着色器程序。后续的 drawArrays、drawElements、Uniform 写入和顶点属性读取都按当前程序执行;同一程序连续绘制时应避免重复切换。
基本语法
以下为片段示例,依赖已创建的 gl 和已成功链接的 program:
gl.useProgram(program); // 激活程序
gl.useProgram(null); // 取消当前程序program 必须由当前 WebGL 上下文创建并成功链接。切换程序后,Uniform 位置和顶点属性位置也要使用该程序对应的查询结果,不能跨程序复用。
可运行示例
下面创建红色和绿色两个程序,通过缓存当前程序避免无效的 useProgram 调用,并分别绘制到画布左右两侧。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="gl" width="480" height="240"></canvas>
<script>
const gl = document.querySelector("#gl").getContext("webgl");
if (!gl) throw new Error("当前浏览器不支持 WebGL");
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 createProgram(color) {
const vs = compile(gl.VERTEX_SHADER, `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}
`);
const fs = compile(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(${color}, 1.0);
}
`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
return program;
}
const redProgram = createProgram("1.0, 0.1, 0.1");
const greenProgram = createProgram("0.1, 0.8, 0.2");
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([-0.8, -0.7, 0.8, -0.7, 0.0, 0.8]),
gl.STATIC_DRAW
);
let currentProgram = null;
function bindProgram(program) {
if (currentProgram !== program) {
gl.useProgram(program);
currentProgram = program;
}
}
function draw(program, x, width) {
bindProgram(program);
const location = gl.getAttribLocation(program, "a_position");
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
gl.viewport(x, 0, width, gl.canvas.height);
gl.drawArrays(gl.TRIANGLES, 0, 3);
}
gl.clearColor(0.08, 0.08, 0.08, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
draw(redProgram, 0, gl.canvas.width / 2);
draw(greenProgram, gl.canvas.width / 2, gl.canvas.width / 2);
console.log("current program is green:", currentProgram === greenProgram);
</script>
</body>
</html>预期结果:画布左侧显示红色三角形,右侧显示绿色三角形;控制台输出:
current program is green: true高频用法
- 按程序或材质对绘制对象排序,减少 GPU 状态切换。
- 在渲染器中缓存
currentProgram,只有目标程序变化时才调用useProgram。 - 每个程序分别缓存
getUniformLocation和getAttribLocation的结果,链接完成后只查询一次。 - 临时取消程序时使用
gl.useProgram(null),但恢复绘制前必须重新激活程序。
风险与边界
程序尚未成功链接、来自其他 WebGL 上下文,或已经处于不可用状态时调用,可能产生 INVALID_OPERATION,后续绘制不会按预期执行。安全做法是在创建阶段检查 LINK_STATUS,并在开发环境通过 gl.getError() 定位状态错误。
切换程序后继续使用旧程序的 UniformLocation,可能触发错误或写入失败。应按程序保存位置对象,不要仅按变量名全局缓存。
排障清单
- 画面全黑:检查程序的
LINK_STATUS和getProgramInfoLog()。 - 切换后颜色或矩阵不生效:确认 Uniform 位置来自当前程序,并在
useProgram之后写入。 - 顶点错位:确认当前程序的属性位置已启用,且
vertexAttribPointer已重新绑定正确缓冲区。 - 切换次数过多:统计实际
useProgram调用,按程序批量提交绘制命令。
WebGL 1 和 WebGL 2 均支持 useProgram,核心行为一致。
创建缓冲区并上传顶点坐标、颜色、法线或纹理坐标数据。
创建顶点缓冲区
使用 gl.createBuffer()、gl.bindBuffer() 和 gl.bufferData() 创建顶点缓冲区,并上传坐标、颜色、法线或纹理坐标。绘制前再用 vertexAttribPointer 说明每个顶点字段的布局。
基本语法
以下为片段示例,依赖已创建的 WebGL 上下文 gl:
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, typedArray, gl.STATIC_DRAW);createBuffer() 返回 WebGLBuffer,失败时返回 null。ARRAY_BUFFER 常用于顶点属性;索引数据应绑定到 ELEMENT_ARRAY_BUFFER。
可运行示例
下面把二维坐标和 RGB 颜色交错存入一个 VBO。每个顶点占 5 个 float,步长为 5 * 4 = 20 字节。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="gl" width="480" height="320"></canvas>
<script>
const gl = document.querySelector("#gl").getContext("webgl");
if (!gl) throw new Error("当前浏览器不支持 WebGL");
function createShader(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;
}
const vertexShader = createShader(gl.VERTEX_SHADER, `
attribute vec2 a_position;
attribute vec3 a_color;
varying vec3 v_color;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
v_color = a_color;
}
`);
const fragmentShader = createShader(gl.FRAGMENT_SHADER, `
precision mediump float;
varying vec3 v_color;
void main() {
gl_FragColor = vec4(v_color, 1.0);
}
`);
const program = gl.createProgram();
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vertices = new Float32Array([
// x, y, r, g, b
0.0, 0.8, 1.0, 0.0, 0.0,
-0.8, -0.7, 0.0, 1.0, 0.0,
0.8, -0.7, 0.0, 0.0, 1.0
]);
const vbo = gl.createBuffer();
if (!vbo) throw new Error("创建缓冲区失败");
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const stride = 5 * Float32Array.BYTES_PER_ELEMENT;
const position = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, stride, 0);
const color = gl.getAttribLocation(program, "a_color");
gl.enableVertexAttribArray(color);
gl.vertexAttribPointer(
color,
3,
gl.FLOAT,
false,
stride,
2 * Float32Array.BYTES_PER_ELEMENT
);
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.clearColor(0.08, 0.08, 0.08, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log("buffer bytes:", gl.getBufferParameter(
gl.ARRAY_BUFFER,
gl.BUFFER_SIZE
));
</script>
</body>
</html>预期结果:页面显示一个由红、绿、蓝三种顶点颜色插值形成的三角形;控制台输出:
buffer bytes: 6060 来自 3 个顶点 × 每顶点 5 个 float × 每个 float 4 字节。
常用参数
gl.STATIC_DRAW:上传后很少修改,适合静态模型。gl.DYNAMIC_DRAW:数据会重复更新,适合频繁变化但仍被多次绘制的数据。gl.STREAM_DRAW:数据通常只使用少数几次。它只是驱动优化提示,不限制后续更新。gl.bufferSubData():缓冲区大小不变时更新局部数据,避免重复分配。
风险与边界
vertexAttribPointer 的步长和偏移量按字节计算。字段数或类型写错会导致顶点错位、颜色异常或完全不可见;安全做法是统一使用 TypedArray.BYTES_PER_ELEMENT 计算字节数。
在目标缓冲区未绑定时调用 bufferData,或上传超过设备可用资源的大数据,可能产生 WebGL 错误或上下文丢失。应检查 createBuffer() 返回值,分批上传大型模型,并监听 webglcontextlost。
排障清单
BUFFER_SIZE为 0:确认bufferData在正确的ARRAY_BUFFER绑定后执行。- 画面无输出:检查顶点数量、属性是否启用,以及
drawArrays的count是否与数据匹配。 - 属性数据串位:重新核对每顶点字段数、
stride、offset和数据类型。 - 动态更新卡顿:预分配缓冲区后使用
bufferSubData,不要每帧创建新缓冲区。
WebGL 1 和 WebGL 2 都支持以上缓冲区 API;WebGL 2 还可配合 VAO 保存属性和缓冲区绑定状态。
将缓冲区数据绑定到着色器中的顶点属性变量。
配置顶点属性
当缓冲区已经写入顶点数据时,用 gl.vertexAttribPointer() 告诉 WebGL 每个顶点由几个分量组成、数据类型是什么,以及相邻顶点之间如何跨步读取;随后必须启用对应属性位置,绘制时着色器才能收到缓冲区数据。
基本语法
调用顺序是先用 gl.bindBuffer(gl.ARRAY_BUFFER, buffer) 绑定数据源,再执行 gl.vertexAttribPointer(index, size, type, normalized, stride, offset) 定义读取方式,最后调用 gl.enableVertexAttribArray(index) 启用该属性。
参数含义:
index:着色器属性位置,通常来自gl.getAttribLocation(program, name)。size:每个顶点读取的分量数,只能是 1~4。type:底层分量类型,如gl.FLOAT、gl.UNSIGNED_BYTE。normalized:整数数据是否归一化后再传给浮点属性;浮点数据通常为false。stride:相邻顶点同一属性之间的字节数;紧密排列时用0。offset:当前属性在单个顶点记录内的字节偏移。
vertexAttribPointer() 不复制数据,它会记录当前绑定的 ARRAY_BUFFER、读取格式和偏移。之后即使重新绑定其他数组缓冲区,该属性仍引用配置时的缓冲区。
高频用法
下面示例把位置和颜色交错存入同一个缓冲区。每个顶点占 5 个 float:前 2 个是位置,后 3 个是颜色。
<!doctype html>
<meta charset="utf-8">
<canvas id="canvas" width="420" height="260"></canvas>
<script>
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL 2");
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;
}
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
in vec2 a_position;
in vec3 a_color;
out vec3 v_color;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
v_color = a_color;
}`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision mediump float;
in vec3 v_color;
out vec4 outColor;
void main() {
outColor = vec4(v_color, 1.0);
}`);
const program = gl.createProgram();
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.useProgram(program);
const vertices = new Float32Array([
0.0, 0.8, 1.0, 0.0, 0.0,
-0.8, -0.7, 0.0, 1.0, 0.0,
0.8, -0.7, 0.0, 0.0, 1.0
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const positionLocation = gl.getAttribLocation(program, "a_position");
const colorLocation = gl.getAttribLocation(program, "a_color");
const stride = 5 * Float32Array.BYTES_PER_ELEMENT;
// 位置从每条记录开头读取 2 个 float。
gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, stride, 0);
gl.enableVertexAttribArray(positionLocation);
// 颜色跳过前 2 个 float,再读取 3 个 float。
gl.vertexAttribPointer(
colorLocation,
3,
gl.FLOAT,
false,
stride,
2 * Float32Array.BYTES_PER_ELEMENT
);
gl.enableVertexAttribArray(colorLocation);
gl.clearColor(0.08, 0.08, 0.1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log(
`position=${positionLocation}, color=${colorLocation}, glError=${gl.getError()}`
);
</script>预期结果
画布中出现一个红、绿、蓝三色插值的三角形。
控制台输出:position=<LOCATION>, color=<LOCATION>, glError=0<LOCATION> 是链接器分配的非负属性位置,实际数字可能不同;glError=0 表示没有产生 WebGL 错误。
风险与边界
stride 和 offset 的单位都是字节,不是元素个数。把 5 当成步长而不是 5 * 4 会导致顶点读取错位,常见后果是图形拉伸、闪烁或完全不可见。安全做法是始终用 TypedArray.BYTES_PER_ELEMENT 计算字节数。
当着色器属性是整数向量且必须保留整数语义时,WebGL 2 应使用 gl.vertexAttribIPointer();继续使用 vertexAttribPointer() 可能发生浮点转换。属性位置为 -1 表示该变量未激活,不能继续调用启用或指针配置,应先检查着色器是否真正使用了该属性。
排障清单
- 画面为空:确认已调用
gl.enableVertexAttribArray(),并检查顶点数量与绘制模式是否匹配。 - 属性错位:重新计算
stride、offset和每个顶点的字段顺序。 - 颜色全黑或固定:确认颜色属性没有被优化掉,且偏移指向颜色首分量。
- 出现
INVALID_OPERATION:检查配置时是否绑定了有效的ARRAY_BUFFER,属性位置是否大于等于 0。 - 仍无法定位:在配置和绘制后分别读取
gl.getError(),把首次出现错误的位置缩小到具体调用。
使用 VAO 保存顶点属性和索引缓冲区状态,简化重复绘制配置。
创建顶点数组对象
当同一网格需要重复绘制,或场景中频繁切换多套顶点布局时,用顶点数组对象(VAO)保存属性启用状态、属性指针配置和索引缓冲区绑定。绘制前只需绑定对应 VAO,不必每帧重复配置全部属性。
基本语法
WebGL 2 使用 gl.createVertexArray() 创建对象,调用 gl.bindVertexArray(vao) 后配置缓冲区和顶点属性,完成后用 gl.bindVertexArray(null) 解绑。绘制阶段再次绑定该 VAO,再调用 gl.drawArrays() 或 gl.drawElements()。
VAO 会保存 enableVertexAttribArray()、vertexAttribPointer() 或 vertexAttribIPointer() 的结果,以及 ELEMENT_ARRAY_BUFFER 绑定。它不会保存当前着色器程序、uniform、纹理绑定、视口、混合或深度测试状态。
高频用法
下面示例创建一个包含位置属性和索引缓冲区的 VAO,解绑后再通过一次绑定完成绘制。
<!doctype html>
<meta charset="utf-8">
<canvas id="canvas" width="420" height="260"></canvas>
<script>
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL 2");
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;
}
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
layout(location = 0) in vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision mediump float;
out vec4 outColor;
void main() {
outColor = vec4(0.15, 0.75, 0.45, 1.0);
}`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const vertexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, vertexBuffer);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([
0.0, 0.8,
-0.8, -0.7,
0.8, -0.7
]),
gl.STATIC_DRAW
);
gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
gl.enableVertexAttribArray(0);
// 索引缓冲区绑定属于当前 VAO 状态。
const indexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.bufferData(
gl.ELEMENT_ARRAY_BUFFER,
new Uint16Array([0, 1, 2]),
gl.STATIC_DRAW
);
// 配置完成后解绑,避免后续代码误改当前 VAO。
gl.bindVertexArray(null);
gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.useProgram(program);
gl.clearColor(0.08, 0.08, 0.1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.bindVertexArray(vao);
gl.drawElements(gl.TRIANGLES, 3, gl.UNSIGNED_SHORT, 0);
gl.bindVertexArray(null);
console.log(`vaoValid=${gl.isVertexArray(vao)}, glError=${gl.getError()}`);
</script>预期结果
画布中出现一个绿色三角形。
控制台输出:vaoValid=true, glError=0实际项目通常在模型加载阶段创建一次 VAO,在渲染循环中按网格绑定并绘制;只有顶点布局或索引缓冲区发生变化时才重新配置。
风险与边界
绑定某个 VAO 后再绑定新的 ELEMENT_ARRAY_BUFFER,会直接修改该 VAO 保存的索引缓冲区。触发条件通常是资源初始化顺序混乱,后果可能是后续网格使用了错误索引甚至越界。安全做法是配置前明确绑定目标 VAO,完成后立即 gl.bindVertexArray(null)。
VAO 只保存顶点输入状态。切换 VAO 后仍要显式调用 gl.useProgram(),并按需重新绑定纹理、设置 uniform 和渲染状态。删除仍被 VAO 引用的缓冲区会让该 VAO 无法按原布局正常绘制,资源释放应在确认所有相关 VAO 不再使用后进行。
排障清单
drawElements()报错:确认索引缓冲区是在目标 VAO 绑定期间设置的,索引类型与Uint16Array或Uint32Array一致。- 切换模型后画面异常:检查是否在配置期间绑定了错误 VAO,或忘记在绘制前绑定目标 VAO。
- 属性全部失效:确认属性配置发生在
gl.bindVertexArray(vao)之后,并且着色器位置与 VAO 中的位置一致。 gl.isVertexArray(vao)为false:对象可能已删除,或从其他 WebGL 上下文创建。- 状态仍混乱:在每个网格初始化结束后解绑 VAO,并把程序、纹理和 uniform 设置保留在绘制路径中。
兼容性
WebGL 2 直接使用 createVertexArray()、bindVertexArray() 和 deleteVertexArray()。WebGL 1 需要获取 OES_vertex_array_object 扩展,并改用 createVertexArrayOES()、bindVertexArrayOES() 和 deleteVertexArrayOES();扩展不可用时,只能在每次绘制前重新绑定缓冲区并配置属性。
上传顶点索引数据以复用顶点并降低模型数据量。
创建索引缓冲区
当多个三角形共享顶点时,使用索引缓冲区保存顶点编号,再通过 gl.drawElements() 复用顶点。这样可减少重复顶点数据,并保持网格拓扑清晰。
基本语法
const indexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
gl.drawElements(gl.TRIANGLES, indices.length, gl.UNSIGNED_SHORT, 0);ELEMENT_ARRAY_BUFFER 的绑定属于当前顶点数组状态。绘制前必须确保正确的索引缓冲区仍处于绑定状态。
高频用法
下面的代码可直接粘贴到浏览器控制台运行,绘制一个由两个三角形组成的正方形。4 个顶点通过 6 个索引复用,而不是重复上传 6 份顶点坐标。
const canvas = document.createElement("canvas");
canvas.width = 320;
canvas.height = 240;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器未启用 WebGL");
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;
}
const vs = compile(gl.VERTEX_SHADER, `
attribute vec2 aPosition;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
}`);
const fs = compile(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(0.15, 0.65, 0.95, 1.0);
}`);
const program = gl.createProgram();
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.useProgram(program);
const vertices = new Float32Array([
-0.7, -0.7,
0.7, -0.7,
0.7, 0.7,
-0.7, 0.7
]);
const indices = new Uint16Array([
0, 1, 2,
0, 2, 3
]);
const vertexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, vertexBuffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const location = gl.getAttribLocation(program, "aPosition");
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
const indexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawElements(gl.TRIANGLES, indices.length, gl.UNSIGNED_SHORT, 0);
console.log(`vertices=${vertices.length / 2}, indices=${indices.length}`);预期结果
页面新增一个黑色画布,中央显示蓝色正方形。
控制台输出:vertices=4, indices=6关键参数
indices通常使用Uint8Array、Uint16Array或Uint32Array。type必须与索引数组一致:Uint8Array对应gl.UNSIGNED_BYTE,Uint16Array对应gl.UNSIGNED_SHORT。offset是索引缓冲区内的字节偏移,不是索引个数;使用UNSIGNED_SHORT时必须按 2 字节对齐。- 静态模型使用
gl.STATIC_DRAW;频繁整体更新可使用gl.DYNAMIC_DRAW。
风险与边界
索引值一旦超过顶点数量,绘制结果不可用,并可能产生 INVALID_OPERATION。上传前应校验 max(indices) < vertexCount,不要依赖浏览器自动修正。
WebGL 1 默认不能直接使用 Uint32Array 索引。触发条件是模型顶点编号超过 65535;直接传入会绘制失败。安全方案是拆分网格,或先启用 OES_element_index_uint 扩展;WebGL 2 可直接使用 gl.UNSIGNED_INT。
排障清单
- 画面为空:确认
gl.drawElements()的count大于 0,且索引缓冲区绑定到了ELEMENT_ARRAY_BUFFER。 - 图形破碎:检查索引类型与
type是否一致,并确认三角形顶点顺序正确。 - 报
INVALID_OPERATION:检查索引最大值、字节偏移对齐和UNSIGNED_INT扩展支持。 - 修改索引后无变化:重新绑定目标缓冲区并再次调用
gl.bufferData()或gl.bufferSubData()。
速查:顶点数据绑定 ARRAY_BUFFER,索引数据绑定 ELEMENT_ARRAY_BUFFER,索引绘制使用 gl.drawElements()。
使用点、线和三角形模式绘制非索引顶点数据。
绘制基础图元
非索引顶点已经按绘制顺序排列时,使用 gl.drawArrays() 直接绘制点、线或三角形。它不读取索引缓冲区,适合简单几何、调试标记和连续顶点流。
基本语法
gl.drawArrays(mode, first, count);mode 决定顶点如何组装,first 是起始顶点编号,count 是参与绘制的顶点数量。
常用模式
| 模式 | 顶点解释 | 常见用途 |
|---|---|---|
gl.POINTS |
每个顶点一个点 | 粒子、调试位置 |
gl.LINES |
每两个顶点一条独立线段 | 网格线、边框 |
gl.LINE_STRIP |
相邻顶点连续成线 | 折线轨迹 |
gl.TRIANGLES |
每三个顶点一个独立三角形 | 普通面片 |
gl.TRIANGLE_STRIP |
后续每个顶点补成新三角形 | 规则带状网格 |
高频用法
下面的代码可直接粘贴到浏览器控制台运行。它复用同一个顶点缓冲区,先绘制蓝色三角形,再绘制黄色顶点标记。
const canvas = document.createElement("canvas");
canvas.width = 320;
canvas.height = 240;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器未启用 WebGL");
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;
}
const vs = compile(gl.VERTEX_SHADER, `
attribute vec2 aPosition;
uniform float uPointSize;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
gl_PointSize = uPointSize;
}`);
const fs = compile(gl.FRAGMENT_SHADER, `
precision mediump float;
uniform vec4 uColor;
void main() {
gl_FragColor = uColor;
}`);
const program = gl.createProgram();
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.useProgram(program);
const vertices = new Float32Array([
0.0, 0.75,
-0.75, -0.65,
0.75, -0.65
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const position = gl.getAttribLocation(program, "aPosition");
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
const color = gl.getUniformLocation(program, "uColor");
const pointSize = gl.getUniformLocation(program, "uPointSize");
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.uniform4f(color, 0.15, 0.65, 0.95, 1.0);
gl.uniform1f(pointSize, 1.0);
gl.drawArrays(gl.TRIANGLES, 0, 3);
gl.uniform4f(color, 1.0, 0.85, 0.1, 1.0);
gl.uniform1f(pointSize, 10.0);
gl.drawArrays(gl.POINTS, 0, 3);
console.log("drawArrays: TRIANGLES=3, POINTS=3");预期结果
页面新增一个黑色画布,显示蓝色三角形,三个顶点位置带黄色方形点。
控制台输出:drawArrays: TRIANGLES=3, POINTS=3参数与读取方法
first 和 count 都按顶点计数,不按浮点数或字节计数。示例中每个顶点含 2 个浮点数,但 count 仍是 3。
绘制多个区段时可复用缓冲区。例如 gl.drawArrays(gl.LINES, 2, 4) 表示从第 3 个顶点开始,读取 4 个顶点并组成 2 条独立线段。
风险与边界
count 超过缓冲区可提供的顶点数量时,可能触发 INVALID_OPERATION,画面不会按预期生成。安全方案是根据属性步长计算可用顶点数,并在绘制前限制 first + count。
gl.LINES 的奇数个顶点会留下一个无法组成线段的顶点;gl.TRIANGLES 的余数顶点同样会被忽略。上传数据时应保证数量满足模式的组装规则。
点大小受 GPU 实现限制。触发条件是 gl_PointSize 超出 ALIASED_POINT_SIZE_RANGE;结果可能被截断。可用 gl.getParameter(gl.ALIASED_POINT_SIZE_RANGE) 查询范围,较大的圆点应改用两个三角形组成的面片。
排障清单
- 完全不显示:确认当前程序已
useProgram(),属性已启用,且count大于 0。 - 只显示部分图元:检查
first、count和模式所需的顶点分组数量。 - 图形位置错乱:检查
vertexAttribPointer()的分量数、步长和偏移。 - 点不可见:在顶点着色器中设置
gl_PointSize,并确认设备支持该尺寸。
速查:连续顶点使用 gl.drawArrays();需要复用共享顶点时改用索引缓冲区和 gl.drawElements()。
使用索引缓冲区绘制共享顶点的二维或三维几何体。
绘制索引图元
当多个三角形共享顶点时,用索引缓冲区保存顶点编号,再通过 gl.drawElements() 绘制。这样可以避免重复上传相同顶点,并让网格拓扑更清晰。
基本语法
片段示例,依赖已创建并填充的顶点缓冲区与索引缓冲区:
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.drawElements(mode, count, type, offset);count 是要读取的索引数量,不是顶点数量;offset 是索引缓冲区中的字节偏移量,必须与索引类型对齐。调用成功后,当前着色器程序会按索引顺序组装并绘制图元。
高频用法
下面使用 4 个共享顶点和 6 个索引绘制两个三角形组成的矩形。保存为 index.html 后直接用浏览器打开。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="gl" width="320" height="240"></canvas>
<script>
const canvas = document.getElementById("gl");
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器无法创建 WebGL 上下文");
function createShader(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;
}
const vs = createShader(gl.VERTEX_SHADER, `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`);
const fs = createShader(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(0.15, 0.65, 0.95, 1.0);
}`);
const program = gl.createProgram();
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.useProgram(program);
const positions = new Float32Array([
-0.7, -0.6,
0.7, -0.6,
0.7, 0.6,
-0.7, 0.6
]);
const indices = new Uint16Array([
0, 1, 2,
0, 2, 3
]);
const vertexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, vertexBuffer);
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);
const location = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
const indexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.08, 0.08, 0.08, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
// Uint16Array 必须与 gl.UNSIGNED_SHORT 对应,偏移 0 表示从首个索引开始。
gl.drawElements(gl.TRIANGLES, indices.length, gl.UNSIGNED_SHORT, 0);
console.log(`drawElements count=${indices.length}`);
</script>
</body>
</html>预期结果:画布中显示一个蓝色矩形,控制台输出:
drawElements count=6读取方式:6 个索引按每 3 个一组组成两个三角形;索引 0 和 2 被重复使用,但对应顶点只存储一次。
常用参数
| 参数 | 常用值 | 含义 |
|---|---|---|
mode |
gl.TRIANGLES、gl.LINES |
索引如何组装成图元 |
count |
indices.length |
本次读取的索引个数 |
type |
gl.UNSIGNED_BYTE、gl.UNSIGNED_SHORT |
单个索引的数据类型 |
offset |
0 或分段起点 |
从索引缓冲区的哪个字节开始 |
风险与边界
type 与 TypedArray 不匹配时会触发 WebGL 错误并导致图形不显示,例如 Uint16Array 必须配合 gl.UNSIGNED_SHORT。安全做法是让索引数组类型、type 和 offset 对齐规则保持一致。
WebGL 1 默认不能直接用 Uint32Array 配合 gl.UNSIGNED_INT;超过 65535 个顶点时,需要启用 OES_element_index_uint,或拆分网格。WebGL 2 原生支持 32 位索引。
排障清单
- 确认绘制前绑定的是索引缓冲区:
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer)。 - 确认所有索引都小于顶点数量;越界索引会导致绘制失败。
- 确认
count没有误写成顶点数。 - 用
gl.getError()检查INVALID_ENUM、INVALID_VALUE或INVALID_OPERATION。
速查:共享顶点放入 ARRAY_BUFFER,顶点编号放入 ELEMENT_ARRAY_BUFFER,最后调用 drawElements()。
局部或整体更新频繁变化的顶点数据,减少重复创建资源。
更新动态缓冲区
顶点位置、粒子属性或实例数据频繁变化时,保留原缓冲区并用 gl.bufferSubData() 更新全部或局部内容,可减少反复创建和删除 GPU 资源。
基本语法
片段示例,依赖已通过 gl.bufferData() 分配容量的缓冲区:
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferSubData(gl.ARRAY_BUFFER, byteOffset, typedArray);byteOffset 按字节计算,不是元素下标。更新区域必须落在已经分配的缓冲区范围内;重新绘制后才能在画面中看到变化。
高频用法
下面先上传一个三角形,800 毫秒后只更新第三个顶点的两个坐标。保存为 dynamic-buffer.html 后直接用浏览器打开。
<!doctype html>
<html lang="zh-CN">
<body>
<canvas id="gl" width="320" height="240"></canvas>
<script>
const canvas = document.getElementById("gl");
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器无法创建 WebGL 上下文");
function shader(type, source) {
const value = gl.createShader(type);
gl.shaderSource(value, source);
gl.compileShader(value);
if (!gl.getShaderParameter(value, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(value));
}
return value;
}
const program = gl.createProgram();
gl.attachShader(program, shader(gl.VERTEX_SHADER, `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`));
gl.attachShader(program, shader(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(1.0, 0.45, 0.2, 1.0);
}`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const positions = new Float32Array([
-0.7, -0.6,
0.7, -0.6,
0.0, 0.7
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
// DYNAMIC_DRAW 是使用提示;实际性能仍取决于浏览器和驱动。
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.DYNAMIC_DRAW);
const location = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
function draw() {
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.08, 0.08, 0.08, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
}
draw();
console.log("initial top vertex=(0.0, 0.7)");
setTimeout(() => {
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
const changedVertex = new Float32Array([0.35, 0.7]);
// 第三个顶点从第 4 个 float 开始,因此字节偏移为 4 * 4 = 16。
gl.bufferSubData(gl.ARRAY_BUFFER, 4 * Float32Array.BYTES_PER_ELEMENT, changedVertex);
draw();
console.log("updated top vertex=(0.35, 0.7)");
}, 800);
</script>
</body>
</html>预期结果:页面先显示对称三角形,约 800 毫秒后顶部顶点向右移动;控制台依次输出:
initial top vertex=(0.0, 0.7)
updated top vertex=(0.35, 0.7)整体更新与局部更新
整个数组长度不变时,可以从偏移 0 覆盖全部内容。以下为片段示例,依赖已创建的 buffer 和 nextPositions:
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferSubData(gl.ARRAY_BUFFER, 0, nextPositions);生效结果:原容量不变,nextPositions 覆盖对应字节范围;重新绘制后显示新顶点数据。
数据长度或容量变化时,应重新分配。以下为片段示例,依赖已创建的 buffer 和 largerPositions:
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, largerPositions, gl.DYNAMIC_DRAW);生效结果:缓冲区容量变为 largerPositions.byteLength,原内容被新数组替换。
风险与边界
写入范围超过原缓冲区容量会触发 INVALID_VALUE,并且数据不会更新。安全做法是在更新前记录已分配的 byteLength,容量变化时改用 bufferData()。
同一缓冲区被 GPU 使用时连续大范围改写,可能造成 CPU 等待 GPU。高频整块更新可先用相同容量重新分配,再上传新数据。以下为片段示例,依赖现有的 buffer 和 positions:
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, positions.byteLength, gl.DYNAMIC_DRAW);
gl.bufferSubData(gl.ARRAY_BUFFER, 0, positions);生效结果:旧存储被替换,新数据从偏移 0 写入;重新调用绘制命令后画面更新。这种方式可能减少同步阻塞,但应通过性能分析确认实际收益。
排障清单
- 更新前重新绑定正确缓冲区,避免把数据写进其他
ARRAY_BUFFER。 - 把元素下标换算成字节偏移:
元素下标 × BYTES_PER_ELEMENT。 - 确认更新后再次执行绘制;修改缓冲区不会自动触发新帧。
- 若画面完全错位,检查
vertexAttribPointer()的分量数、步长和偏移。 - 若更新无效,调用
gl.getError()检查是否越界。
速查:容量不变优先 bufferSubData();容量改变使用 bufferData();高频整块写入出现卡顿时考虑重新分配存储后再上传。
向着色器传递颜色、时间、分辨率和变换矩阵等全局参数。
设置 Uniform 变量
在绘制前用 Uniform 把颜色、时间、分辨率和矩阵等“整次 draw call 共用”的参数传给着色器。Uniform 值属于当前着色器程序,必须先完成链接并调用 gl.useProgram(program),再用对应的 uniform* 方法写入。
基本语法
先查询位置,再按 GLSL 类型选择写入函数。位置可缓存,不要在每帧重复调用 getUniformLocation。
const location = gl.getUniformLocation(program, "uColor");
gl.useProgram(program);
gl.uniform4f(location, 0.2, 0.65, 1.0, 1.0);常见映射如下:
| GLSL 类型 | WebGL 写入方法 |
|---|---|
float |
uniform1f |
vec2、vec3、vec4 |
uniform2f、uniform3f、uniform4f 或对应 *fv |
int、bool、采样器 |
uniform1i |
mat3、mat4 |
uniformMatrix3fv、uniformMatrix4fv |
矩阵方法的第二个参数 transpose 在 WebGL 中必须传 false。
高频用法
下面代码可直接粘贴到浏览器控制台运行。它创建 WebGL 画布,向片元着色器传入颜色、时间和分辨率,然后绘制一个蓝绿色三角形。
const canvas = document.createElement("canvas");
canvas.width = 320;
canvas.height = 180;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器未提供 WebGL");
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;
}
const vs = compile(gl.VERTEX_SHADER, `
attribute vec2 aPosition;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
}
`);
const fs = compile(gl.FRAGMENT_SHADER, `
precision mediump float;
uniform vec4 uColor;
uniform float uTime;
uniform vec2 uResolution;
void main() {
float pulse = 0.8 + 0.2 * sin(uTime);
vec2 uv = gl_FragCoord.xy / uResolution;
gl_FragColor = vec4(uColor.rgb * pulse * (0.8 + 0.2 * uv.x), uColor.a);
}
`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
const position = gl.getAttribLocation(program, "aPosition");
const colorLoc = gl.getUniformLocation(program, "uColor");
const timeLoc = gl.getUniformLocation(program, "uTime");
const resolutionLoc = gl.getUniformLocation(program, "uResolution");
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([-0.8, -0.7, 0.8, -0.7, 0.0, 0.8]),
gl.STATIC_DRAW
);
gl.viewport(0, 0, canvas.width, canvas.height);
gl.useProgram(program);
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
// Uniform 写入作用于当前 program,且会保留到下次修改或重新链接。
gl.uniform4f(colorLoc, 0.2, 0.65, 1.0, 1.0);
gl.uniform1f(timeLoc, 1.0);
gl.uniform2f(resolutionLoc, canvas.width, canvas.height);
gl.drawArrays(gl.TRIANGLES, 0, 3);
const readColor = Array.from(gl.getUniform(program, colorLoc))
.map(value => Number(value.toFixed(2)));
console.log("uColor =", readColor);
console.log("uResolution =", Array.from(gl.getUniform(program, resolutionLoc)));预期结果:页面出现一个带轻微横向明暗变化的蓝绿色三角形;控制台输出如下。
uColor = [0.2, 0.65, 1, 1]
uResolution = [320, 180]参数与读取规则
uniform4f(location, x, y, z, w) 适合少量标量;已有 Float32Array 时使用 uniform4fv(location, data)。矩阵通常用列主序数组传入,例如 uniformMatrix4fv(location, false, matrix)。
gl.getUniform(program, location) 可用于排障验证,但会产生同步读取开销,不应放进高频渲染循环。生产代码通常在 CPU 侧保存最后一次设置值。
风险与边界
当 Uniform 在着色器中未使用、名称拼错或被编译器优化掉时,getUniformLocation 返回 null;继续写入不会报错但也不会生效。安全做法是初始化阶段检查关键位置,非关键可选项允许为 null。
当切换了程序却仍使用旧程序的位置对象时,会触发 INVALID_OPERATION 或写入失败。应按程序分别缓存位置,并在写入前确认已 useProgram 对应程序。
重新调用 gl.linkProgram(program) 会重置 Uniform 值并使旧位置失效。热更新着色器后必须重新查询位置并重新上传全部参数。
排障清单
- 先检查编译和链接日志,确认程序确实链接成功。
- 用
gl.getError()检查是否出现INVALID_OPERATION。 - 确认 GLSL 类型与
uniform*方法一致,采样器必须使用整数方法。 - 确认画布尺寸、
viewport和传入的分辨率使用同一套像素值。 - 矩阵无效果时,优先检查列主序、乘法顺序以及
transpose是否误传为true。
速查:Uniform 位置按程序缓存,写入前先 useProgram,矩阵转置参数固定为 false。
通过统一缓冲区在多个着色器程序之间共享成组参数。
使用 Uniform 缓冲区
Uniform Buffer Object(UBO)用于把一组参数放进 UNIFORM_BUFFER,再通过绑定点共享给多个 WebGL 2 程序。适合相机矩阵、灯光、时间和分辨率等会被多套着色器重复读取的数据。
工作关系
每个程序把同名 Uniform Block 映射到一个绑定点;缓冲区再绑定到该点。更新一次缓冲区后,所有绑定到该点的程序都能读取新值。

基本语法
UBO 仅适用于 WebGL 2,着色器需使用 GLSL ES 3.00。推荐显式写 layout(std140),获得可预测的对齐规则。
const blockIndex = gl.getUniformBlockIndex(program, "SceneBlock");
gl.uniformBlockBinding(program, blockIndex, 0);
gl.bindBufferBase(gl.UNIFORM_BUFFER, 0, ubo);uniformBlockBinding 建立“程序块索引 → 绑定点”的映射;bindBufferBase 建立“绑定点 → 缓冲区”的映射。两个调用缺一不可。
高频用法
下面代码可直接粘贴到浏览器控制台运行。两个片元着色器程序共享同一个 SceneBlock,左半画布显示原色,右半画布显示互补色。
const canvas = document.createElement("canvas");
canvas.width = 400;
canvas.height = 180;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器未提供 WebGL 2");
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 createProgram(fragmentBody) {
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
layout(location = 0) in vec2 aPosition;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
}
`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision highp float;
layout(std140) uniform SceneBlock {
vec4 uColor;
vec2 uResolution;
float uTime;
};
out vec4 outColor;
void main() {
vec2 uv = gl_FragCoord.xy / uResolution;
float pulse = 0.9 + 0.1 * sin(uTime);
${fragmentBody}
}
`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
return program;
}
const programA = createProgram(
"outColor = vec4(uColor.rgb * pulse * (0.8 + 0.2 * uv.x), uColor.a);"
);
const programB = createProgram(
"outColor = vec4((1.0 - uColor.rgb) * pulse * (0.8 + 0.2 * uv.x), uColor.a);"
);
const vertices = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, vertices);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([-1, -1, 1, -1, 0, 1]),
gl.STATIC_DRAW
);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
// std140:vec4 位于 0,vec2 位于 16,float 位于 24,块大小补齐到 32 字节。
const sceneData = new Float32Array(8);
sceneData.set([0.9, 0.3, 0.2, 1.0], 0);
sceneData.set([canvas.width, canvas.height], 4);
sceneData[6] = 1.0;
const ubo = gl.createBuffer();
gl.bindBuffer(gl.UNIFORM_BUFFER, ubo);
gl.bufferData(gl.UNIFORM_BUFFER, sceneData, gl.DYNAMIC_DRAW);
const bindingPoint = 0;
for (const program of [programA, programB]) {
const blockIndex = gl.getUniformBlockIndex(program, "SceneBlock");
if (blockIndex === gl.INVALID_INDEX) {
throw new Error("未找到 SceneBlock");
}
gl.uniformBlockBinding(program, blockIndex, bindingPoint);
}
gl.bindBufferBase(gl.UNIFORM_BUFFER, bindingPoint, ubo);
gl.viewport(0, 0, canvas.width / 2, canvas.height);
gl.useProgram(programA);
gl.drawArrays(gl.TRIANGLES, 0, 3);
gl.viewport(canvas.width / 2, 0, canvas.width / 2, canvas.height);
gl.useProgram(programB);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log("binding point =", bindingPoint);
console.log("buffer bytes =", sceneData.byteLength);预期结果:画布左侧出现偏红三角形,右侧出现其青色互补色;两者读取同一组分辨率和时间参数。控制台输出:
binding point = 0
buffer bytes = 32更新共享参数时无需重新绑定程序,只需修改缓冲区对应范围。
sceneData[6] = 2.0;
gl.bindBuffer(gl.UNIFORM_BUFFER, ubo);
gl.bufferSubData(gl.UNIFORM_BUFFER, 0, sceneData);预期结果:下一次分别绘制两个程序时,它们都会读取新的 uTime = 2.0。
对齐与查询
std140 会为 vec3、矩阵和数组插入填充,不能按“成员字节数简单相加”计算偏移。复杂块应使用 getUniformIndices 配合 getActiveUniforms(..., gl.UNIFORM_OFFSET) 查询实际偏移,或在 CPU 端固定维护与着色器一致的布局定义。
使用 bindBufferRange 绑定大缓冲区中的一段时,起始偏移必须满足 UNIFORM_BUFFER_OFFSET_ALIGNMENT;不满足会触发 INVALID_VALUE。整块共享优先使用 bindBufferBase,可避免偏移对齐问题。
风险与边界
当浏览器只提供 WebGL 1 时,getContext("webgl2") 返回 null,UBO API 不存在。安全替代方案是回退到普通 Uniform,或减少程序间共享参数数量。
当多个模块误用同一绑定点时,后绑定的缓冲区会覆盖前一个映射,导致程序读取错误数据。应集中分配绑定点常量,并检查 MAX_UNIFORM_BUFFER_BINDINGS。
当写入数据未遵循 std140 对齐时,通常不会报错,但着色器会读到错位值。应使用明确布局、查询偏移,并让缓冲区大小至少等于 UNIFORM_BLOCK_DATA_SIZE。
频繁创建和销毁 UBO 会增加驱动开销。生产代码应长期复用缓冲区,通过 bufferSubData 更新变化区间。
排障清单
- 确认上下文是
webgl2,着色器首行是#version 300 es。 - 检查
getUniformBlockIndex是否返回gl.INVALID_INDEX。 - 确认每个程序都调用了
uniformBlockBinding,且缓冲区已调用bindBufferBase。 - 查询
UNIFORM_BLOCK_DATA_SIZE,确认实际缓冲区不小于块大小。 - 颜色或矩阵错乱时,优先检查
std140偏移、填充和矩阵列主序。 - 使用
bindBufferRange时检查偏移是否满足UNIFORM_BUFFER_OFFSET_ALIGNMENT。
速查:程序负责把块映射到绑定点,缓冲区负责绑定到该点;共享失败通常出在绑定点冲突或 std140 对齐。