Web 图形与 3D / 知识点
WebGL 开发速查手册
手册条目
通过平移、旋转和缩放矩阵控制模型在世界空间中的位置和姿态。
执行模型变换
模型矩阵把顶点从模型空间变换到世界空间。常见组合是先缩放、再旋转、最后平移,并通过 uniform mat4 传给顶点着色器。

基本语法
顶点着色器通常按 gl_Position = projection * view * model * position 计算。WebGL 的矩阵数据按列主序传入,uniformMatrix4fv 的第二个参数必须为 false。
attribute vec3 aPosition;
uniform mat4 uModel;
uniform mat4 uView;
uniform mat4 uProjection;
void main() {
gl_Position = uProjection * uView * uModel * vec4(aPosition, 1.0);
}片段示例:以上代码依赖已链接的 WebGL 程序,以及已绑定的顶点属性和三个矩阵 uniform。生效后,顶点会按模型、观察、投影的顺序进入裁剪空间。
可运行示例
下面代码可直接粘贴到浏览器开发者工具控制台。它构造 T × R × S 模型矩阵,并计算模型原点和点 (1, 0, 0) 的世界坐标。
function multiply(a, b) {
const out = new Float32Array(16);
for (let col = 0; col < 4; col++) {
for (let row = 0; row < 4; row++) {
let sum = 0;
for (let k = 0; k < 4; k++) {
sum += a[k * 4 + row] * b[col * 4 + k];
}
out[col * 4 + row] = sum;
}
}
return out;
}
function translation(x, y, z) {
return new Float32Array([
1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
x, y, z, 1
]);
}
function rotationZ(rad) {
const c = Math.cos(rad);
const s = Math.sin(rad);
return new Float32Array([
c, s, 0, 0,
-s, c, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1
]);
}
function scaling(x, y, z) {
return new Float32Array([
x, 0, 0, 0,
0, y, 0, 0,
0, 0, z, 0,
0, 0, 0, 1
]);
}
function transformPoint(m, [x, y, z]) {
return [
m[0] * x + m[4] * y + m[8] * z + m[12],
m[1] * x + m[5] * y + m[9] * z + m[13],
m[2] * x + m[6] * y + m[10] * z + m[14]
].map(v => Number(v.toFixed(3)));
}
const scale = scaling(2, 1, 1);
const rotate = rotationZ(Math.PI / 2);
const move = translation(3, 4, 0);
// 列向量约定:最右侧的缩放最先执行。
const model = multiply(move, multiply(rotate, scale));
console.log("origin:", transformPoint(model, [0, 0, 0]));
console.log("point:", transformPoint(model, [1, 0, 0]));预期输出
origin: [3, 4, 0]
point: [3, 6, 0]原点只受平移影响;点 (1, 0, 0) 先沿 X 轴放大为 (2, 0, 0),再旋转到 (0, 2, 0),最后平移到 (3, 6, 0)。
接入 WebGL
片段示例:以下代码假设 gl、当前程序和 uModel 已准备完成。
const uModel = gl.getUniformLocation(program, "uModel");
gl.useProgram(program);
gl.uniformMatrix4fv(uModel, false, model);验证时可读取 gl.getError();返回 0 表示本次调用未产生 WebGL 错误。画面位置不正确时,优先打印 model[12]、model[13]、model[14] 检查平移分量。
风险与边界
- 触发条件:把组合写成
S × R × T。后果:平移向量也会被缩放或旋转,模型位置明显偏离。安全替代:先明确列向量约定,并固定使用T × R × S。 - 触发条件:把角度直接传给三角函数。后果:旋转结果错误。安全替代:使用
degrees * Math.PI / 180转为弧度。 - 触发条件:对模型做非均匀缩放后仍直接用模型矩阵变换法线。后果:光照方向失真。安全替代:使用模型矩阵左上角
3×3的逆转置矩阵处理法线。
兼容性
WebGL 1 和 WebGL 2 都支持 uniformMatrix4fv。两者都要求 transpose 为 false;矩阵库若采用行主序或行向量约定,必须先统一布局和乘法顺序。
根据相机位置、观察目标和上方向构造观察矩阵。
配置观察矩阵
观察矩阵把世界空间转换到相机空间。给定相机位置 eye、观察目标 target 和上方向 up,可用 lookAt 构造矩阵,再在顶点着色器中放到模型矩阵之后。

基本语法
lookAt 的核心是建立相机的三个正交轴,并把相机位置投影到这些轴上。常见右手坐标约定中,相机前方对应相机空间的负 Z 轴。
attribute vec3 aPosition;
uniform mat4 uModel;
uniform mat4 uView;
uniform mat4 uProjection;
void main() {
gl_Position = uProjection * uView * uModel * vec4(aPosition, 1.0);
}片段示例:以上代码依赖已初始化的 WebGL 程序。uView 应在相机位置或朝向变化后重新上传。
可运行示例
下面代码可直接粘贴到浏览器开发者工具控制台。相机位于 (0, 0, 5),观察世界原点,结果应把原点变换到相机前方 5 个单位的位置。
function subtract(a, b) {
return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
}
function dot(a, b) {
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
}
function cross(a, b) {
return [
a[1] * b[2] - a[2] * b[1],
a[2] * b[0] - a[0] * b[2],
a[0] * b[1] - a[1] * b[0]
];
}
function normalize(v) {
const length = Math.hypot(v[0], v[1], v[2]);
if (length < 1e-8) {
throw new Error("无法归一化零向量");
}
return [v[0] / length, v[1] / length, v[2] / length];
}
function lookAt(eye, target, up) {
// z 轴从目标指向相机,因此相机观察方向是 -Z。
const zAxis = normalize(subtract(eye, target));
const xAxis = normalize(cross(up, zAxis));
const yAxis = cross(zAxis, xAxis);
return new Float32Array([
xAxis[0], yAxis[0], zAxis[0], 0,
xAxis[1], yAxis[1], zAxis[1], 0,
xAxis[2], yAxis[2], zAxis[2], 0,
-dot(xAxis, eye), -dot(yAxis, eye), -dot(zAxis, eye), 1
]);
}
function transformPoint(m, [x, y, z]) {
return [
m[0] * x + m[4] * y + m[8] * z + m[12],
m[1] * x + m[5] * y + m[9] * z + m[13],
m[2] * x + m[6] * y + m[10] * z + m[14]
].map(v => Number(v.toFixed(3)));
}
const eye = [0, 0, 5];
const target = [0, 0, 0];
const up = [0, 1, 0];
const view = lookAt(eye, target, up);
console.log("world origin in camera space:", transformPoint(view, [0, 0, 0]));
console.log("camera position in camera space:", transformPoint(view, eye));预期输出
world origin in camera space: [0, 0, -5]
camera position in camera space: [0, 0, 0]第一行表示世界原点位于相机前方 5 个单位;第二行验证相机自身被变换到相机空间原点。
接入 WebGL
片段示例:以下代码假设 program 已链接,且顶点着色器声明了 uView。
const uView = gl.getUniformLocation(program, "uView");
gl.useProgram(program);
gl.uniformMatrix4fv(uView, false, view);相机移动时更新 eye 并重新计算 view。仅模型移动时不必重算观察矩阵。
风险与边界
- 触发条件:
eye与target相同。后果:观察方向为零向量,矩阵会出现NaN。安全替代:调用前检查两点距离,并拒绝小于容差的输入。 - 触发条件:
up与观察方向平行或近似平行。后果:叉积接近零,左右轴无法确定,画面可能翻转或抖动。安全替代:改用不共线的上方向,例如在俯视极点附近切换到[0, 0, 1]。 - 触发条件:把相机自身的平移、旋转矩阵直接作为观察矩阵。后果:场景会向错误方向移动。安全替代:使用相机世界矩阵的逆矩阵,或直接用经过验证的
lookAt。 - 触发条件:项目同时混用左手和右手坐标约定。后果:前后方向、绕序和背面剔除可能相反。安全替代:统一相机、投影、模型和资源导入的坐标约定。
排障清单
- 画面全黑:检查目标是否位于相机负 Z 方向,并确认近裁剪面、远裁剪面覆盖目标距离。
- 相机左右移动反向:确认观察矩阵是相机世界矩阵的逆,而不是相机矩阵本身。
- 接近正上方或正下方时抖动:检查
up与观察方向的点积是否接近±1。 - 矩阵上传无效:确认当前程序正确、uniform 未被优化掉,并检查
gl.getError()是否返回0。
兼容性
WebGL 1 和 WebGL 2 的观察矩阵用法一致,uniformMatrix4fv 的 transpose 都必须为 false。若使用 glMatrix、Three.js 等库,应确认其 lookAt 返回的是观察矩阵、相机世界矩阵还是需要再求逆的矩阵。
设置视野角、宽高比和裁剪面以生成具有远近效果的三维画面。
配置透视投影
透视投影让近处物体看起来更大、远处物体更小。配置时确定垂直视野角、画布宽高比、近裁剪面和远裁剪面,再把矩阵上传给顶点着色器。
基本语法
顶点变换顺序通常写成 projection × view × model × position。WebGL 的矩阵按列主序传入,gl.uniformMatrix4fv 的 transpose 必须为 false。

下面的纯 JavaScript 示例生成 WebGL 可直接使用的透视矩阵:
function createPerspective(fovyRad, aspect, near, far) {
if (!(fovyRad > 0 && fovyRad < Math.PI)) throw new RangeError('fovy must be between 0 and PI');
if (!(aspect > 0)) throw new RangeError('aspect must be greater than 0');
if (!(near > 0 && far > near)) throw new RangeError('require 0 < near < far');
const out = new Float32Array(16);
// 由垂直视野角计算焦距缩放系数。
const f = 1 / Math.tan(fovyRad / 2);
const nf = 1 / (near - far);
out[0] = f / aspect;
out[5] = f;
// 深度项按 WebGL 的 -1 到 1 裁剪空间构造。
out[10] = (far + near) * nf;
out[11] = -1;
out[14] = 2 * far * near * nf;
return out;
}
const projection = createPerspective(Math.PI / 4, 16 / 9, 0.1, 100);
console.log(Array.from(projection, value => Number(value.toFixed(4))));
// 已取得 uniform 位置时上传:gl.uniformMatrix4fv(uProjection, false, projection);预期输出:
[1.358, 0, 0, 0, 0, 2.4142, 0, 0, 0, 0, -1.002, -1, 0, 0, -0.2002, 0]数组是列主序矩阵。1.358 和 2.4142 控制水平、垂直缩放;-1.002 与 -0.2002 将观察空间深度映射到裁剪空间。
常用参数
fovy:垂直视野角,常用 45°~60°。值越小越像长焦,值越大广角变形越明显。aspect:通常取canvas.width / canvas.height,画布尺寸变化后必须重新计算。near、far:使用正距离且满足0 < near < far。尽量增大near、减小far,可提升深度缓冲精度。
高频用法
窗口缩放时同步更新画布像素尺寸、gl.viewport 和 aspect;只改 CSS 宽高而不改绘图缓冲区会造成拉伸或模糊。
需要镜头缩放时优先调整 fovy,不要同时随意修改模型缩放和相机距离,否则交互手感难以保持一致。
风险与排障
near 设得极小且 far 很大时,深度精度集中在近处,远处共面物体可能闪烁。安全做法是缩短裁剪范围,必要时分层渲染。
画面完全消失时依次检查:物体是否位于相机前方、矩阵乘法顺序是否正确、near/far 是否有效、uniform 位置是否为 null、上传后是否使用了对应 program。
兼容性
WebGL 1 和 WebGL 2 都支持 mat4 与 uniformMatrix4fv。WebGL 裁剪空间深度范围是 -1 到 1,从使用 0 到 1 深度范围的图形 API 迁移矩阵时不能直接照搬。
创建无透视缩放的投影矩阵,用于二维界面和工程视图。
配置正交投影
正交投影不会因距离改变物体大小,适合二维界面、地图、CAD 视图和固定比例的工程展示。配置时定义左、右、下、上边界以及近、远裁剪面。
基本语法
顶点仍按 projection × view × model × position 变换,但投影视体是长方体,不会产生近大远小效果。矩阵上传方式与透视投影相同:gl.uniformMatrix4fv(uProjection, false, projection)。

下面的纯 JavaScript 示例生成列主序正交矩阵:
function createOrthographic(left, right, bottom, top, near, far) {
if (right === left || top === bottom || far === near) {
throw new RangeError('projection bounds must have non-zero size');
}
const out = new Float32Array(16);
// 对角项把指定宽、高、深度缩放到裁剪空间。
out[0] = 2 / (right - left);
out[5] = 2 / (top - bottom);
out[10] = -2 / (far - near);
// 平移项把投影视体中心移动到裁剪空间原点。
out[12] = -(right + left) / (right - left);
out[13] = -(top + bottom) / (top - bottom);
out[14] = -(far + near) / (far - near);
out[15] = 1;
return out;
}
const projection = createOrthographic(-4, 4, -3, 3, 0.1, 100);
console.log(Array.from(projection, value => Number(value.toFixed(4))));
// 已取得 uniform 位置时上传:gl.uniformMatrix4fv(uProjection, false, projection);预期输出:
[0.25, 0, 0, 0, 0, 0.3333, 0, 0, 0, 0, -0.02, 0, 0, 0, -1.002, 1]0.25 和 0.3333 分别把宽度 8、高度 6 映射到裁剪空间;平移项为 0,说明当前视体以原点为中心。
常用参数
left/right:控制水平可见范围;范围越大,同一物体在屏幕上越小。bottom/top:控制垂直可见范围。二维界面若希望 Y 轴向下,可交换上下边界。near/far:控制可见深度范围。即使二维绘制也应设置合理范围,避免元素被意外裁剪。
高频用法
像素坐标界面可使用 left = 0、right = canvas.width、top = 0、bottom = canvas.height,这样顶点坐标可直接对应画布像素。
工程视图常围绕原点设置对称边界,例如 [-width/2, width/2] 与 [-height/2, height/2],缩放时只改变边界范围。
画布宽高比变化时,应同步调整水平或垂直范围;固定两边范围不变会让图形在非等比例窗口中被拉伸。
风险与排障
左右、上下或远近边界相等会产生除零,矩阵出现 Infinity 或 NaN,最终画面消失。安全做法是在创建矩阵前校验每组边界差值。
二维元素顺序异常时检查 Z 值、深度测试和混合状态。纯 UI 可关闭深度测试并按顺序绘制;混合三维内容时应保留深度测试并明确层级。
兼容性
WebGL 1 和 WebGL 2 的正交矩阵格式一致。外部数学库可能采用不同坐标约定,接入前应确认列主序、右手或左手坐标系以及深度范围,不能只看函数名相同就直接替换。
配置深度比较和深度写入,正确处理三维物体的前后遮挡。
启用深度测试
绘制多个三维物体或同一网格的重叠三角形时启用深度测试,让离相机更近的片元覆盖更远的片元。每帧开始时必须同时清空颜色缓冲和深度缓冲,否则上一帧深度值会干扰当前帧。
基本配置
<!doctype html>
<meta charset="utf-8">
<canvas id="canvas" width="320" height="180"></canvas>
<script>
const canvas = document.querySelector("#canvas");
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器不支持 WebGL");
gl.enable(gl.DEPTH_TEST);
gl.depthFunc(gl.LEQUAL); // 深度更小或相等时通过
gl.depthMask(true); // 允许写入深度缓冲
gl.clearDepth(1.0); // 远平面对应的默认清除值
gl.clearColor(0.08, 0.08, 0.1, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
console.log({
enabled: gl.isEnabled(gl.DEPTH_TEST),
func: gl.getParameter(gl.DEPTH_FUNC),
writeEnabled: gl.getParameter(gl.DEPTH_WRITEMASK),
clearValue: gl.getParameter(gl.DEPTH_CLEAR_VALUE)
});
</script>预期输出:
{ enabled: true, func: 515, writeEnabled: true, clearValue: 1 }515 对应 gl.LEQUAL。实际控制台可能将对象展开显示,但四个字段的值应一致。
常用设置
gl.LESS 是默认比较方式,当前片元深度小于缓冲值时通过;gl.LEQUAL 允许深度相等的片元通过,常用于减少共享边界上的缺口。正常实体绘制通常保持 gl.depthMask(true)。
绘制透明物体时通常仍保留深度测试,但临时关闭深度写入:
gl.enable(gl.DEPTH_TEST);
gl.depthMask(false);
// 按从远到近顺序绘制透明物体
drawTransparentObjects();
gl.depthMask(true);这是片段示例,依赖已创建的 gl 和项目中的 drawTransparentObjects()。
预期结果:
透明片元会接受已有深度遮挡,但不会覆盖深度缓冲;恢复 depthMask(true) 后,后续实体绘制可正常写入深度。风险与边界
只调用 gl.enable(gl.DEPTH_TEST) 却未清空 gl.DEPTH_BUFFER_BIT,会在动画中出现物体随机缺块或上一帧残影。安全做法是每帧绘制前统一清空颜色和深度缓冲。
关闭深度写入后忘记恢复,会导致后续物体都无法更新深度,遮挡关系失真。透明阶段结束后应立即执行 gl.depthMask(true),不要把状态恢复分散到其他函数。
深度测试不能解决透明物体的排序问题。透明物体通常需要关闭深度写入并按相机距离从远到近绘制。
排障清单
- 远处物体覆盖近处物体:确认已启用
DEPTH_TEST,并检查投影矩阵的近远裁剪面。 - 动画第二帧开始缺面:确认每帧都清除
DEPTH_BUFFER_BIT。 - 全部物体深度相同或闪烁:检查顶点着色器是否正确输出裁剪空间位置,并避免近远裁剪面比例过大。
- 透明物体互相遮挡异常:保留深度测试,关闭深度写入,并重新排序透明绘制顺序。
速查:实体绘制默认使用“启用深度测试、允许深度写入、每帧清空深度缓冲”。
剔除不可见的正面或背面三角形以减少片元处理量。
启用面剔除
封闭三维网格通常只需要绘制朝向观察者的一侧。启用面剔除可跳过背向三角形,减少光栅化和片元处理;若模型绕序不一致,则会直接出现整面消失。
基本配置
<!doctype html>
<meta charset="utf-8">
<canvas id="canvas" width="320" height="180"></canvas>
<script>
const canvas = document.querySelector("#canvas");
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器不支持 WebGL");
gl.enable(gl.CULL_FACE);
gl.cullFace(gl.BACK); // 剔除背面
gl.frontFace(gl.CCW); // 屏幕空间逆时针顶点为正面
console.log({
enabled: gl.isEnabled(gl.CULL_FACE),
cullMode: gl.getParameter(gl.CULL_FACE_MODE),
frontFace: gl.getParameter(gl.FRONT_FACE)
});
</script>预期输出:
{ enabled: true, cullMode: 1029, frontFace: 2305 }1029 对应 gl.BACK,2305 对应 gl.CCW。浏览器控制台的对象展示格式可能不同。
常用设置
常规封闭模型使用:
gl.enable(gl.CULL_FACE);
gl.frontFace(gl.CCW);
gl.cullFace(gl.BACK);预期结果:
逆时针三角形被视为正面并保留,顺时针三角形作为背面被剔除。镜像缩放会反转三角形绕序。若模型矩阵包含单轴负缩放,可在该批次临时切换正面定义:
gl.frontFace(gl.CW);
drawMirroredMesh();
gl.frontFace(gl.CCW);这是片段示例,依赖已创建的 gl 和项目中的 drawMirroredMesh()。
预期结果:
镜像网格按顺时针绕序识别正面;绘制结束后恢复 CCW,避免影响其他模型。双面材质、树叶、纸张或开放曲面需要同时显示两侧,可针对该批次临时关闭剔除,再立即恢复。
风险与边界
顶点索引绕序与 gl.frontFace() 不一致时,触发条件是三角形在屏幕空间被判断为背面,后果是模型局部或整体消失。安全替代方案是统一导出工具和索引生成逻辑的绕序,而不是长期关闭剔除。
对双面材质强制启用背面剔除,会导致从背面观察时完全不可见。应仅对该材质关闭剔除,或为正反面分别提供几何与法线。
使用 gl.cullFace(gl.FRONT_AND_BACK) 会剔除所有三角形,页面可能只剩清屏颜色。除调试外不要使用;常规场景应选择 gl.BACK。
排障清单
- 模型完全不见:临时禁用
CULL_FACE,确认是否为绕序问题。 - 只有部分三角形消失:检查索引缓冲中各三角形的顶点顺序是否一致。
- 镜像模型消失:检查模型矩阵是否包含负缩放,并在该批次切换
frontFace。 - 开放曲面背面不可见:确认材质是否应为双面,再决定是否局部关闭剔除。
- 法线方向正确但仍消失:面剔除依据顶点屏幕绕序,不依据法线方向。
速查:标准封闭网格通常使用 gl.enable(gl.CULL_FACE)、gl.cullFace(gl.BACK) 和 gl.frontFace(gl.CCW)。
配置混合函数,实现透明物体、粒子和半透明界面的合成。
启用透明混合
透明物体、粒子和半透明界面需要把当前片元颜色与帧缓冲中的已有颜色合成。常规透明度通常使用 SRC_ALPHA 与 ONE_MINUS_SRC_ALPHA,并把透明物体放在不透明物体之后绘制。
基本语法
片段示例,依赖已成功创建的 WebGLRenderingContext gl:
gl.enable(gl.BLEND);
gl.blendEquation(gl.FUNC_ADD);
gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);颜色通道的常规合成可理解为 。源颜色来自当前片元着色器,目标颜色来自帧缓冲;片元着色器必须实际输出小于 1.0 的 alpha,混合才会呈现半透明效果。

可运行示例
下面的页面先绘制不透明蓝色矩形,再启用混合绘制 alpha 为 0.5 的红色矩形。保存为 blend.html 后直接用浏览器打开。
<!doctype html>
<meta charset="utf-8">
<canvas id="c" width="480" height="280"></canvas>
<script>
const gl = document.querySelector("#c").getContext("webgl");
if (!gl) throw new Error("WebGL unavailable");
const vsSource = `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`;
const fsSource = `
precision mediump float;
uniform vec4 u_color;
void main() {
gl_FragColor = u_color;
}`;
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vsSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
// 复用一个动态顶点缓冲区绘制两个矩形。
const position = gl.getAttribLocation(program, "a_position");
const color = gl.getUniformLocation(program, "u_color");
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.useProgram(program);
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
function drawRect(x1, y1, x2, y2, rgba) {
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
x1, y1, x2, y1, x2, y2, x1, y2
]), gl.STREAM_DRAW);
gl.uniform4fv(color, rgba);
gl.drawArrays(gl.TRIANGLE_FAN, 0, 4);
}
gl.clearColor(0.08, 0.08, 0.1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
// 先画不透明物体,建立背景颜色。
drawRect(-0.85, -0.65, 0.35, 0.65, [0.1, 0.35, 1.0, 1.0]);
gl.enable(gl.BLEND);
gl.blendEquation(gl.FUNC_ADD);
gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
// 再画透明物体,重叠区域会与蓝色背景合成。
drawRect(-0.2, -0.8, 0.85, 0.8, [1.0, 0.15, 0.1, 0.5]);
console.log("BLEND:", gl.isEnabled(gl.BLEND));
console.log("SRC/DST:", gl.getParameter(gl.BLEND_SRC_RGB),
gl.getParameter(gl.BLEND_DST_RGB));
</script>预期结果:画布中红色矩形与蓝色矩形的重叠区域呈紫红色;控制台显示混合已启用,常量值分别对应 SRC_ALPHA 和 ONE_MINUS_SRC_ALPHA。
BLEND: true
SRC/DST: 770 771常用组合
| 场景 | 配置 | 读取方式 |
|---|---|---|
| 普通透明 | SRC_ALPHA, ONE_MINUS_SRC_ALPHA |
适合非预乘 alpha 的颜色和纹理 |
| 加法粒子 | SRC_ALPHA, ONE |
亮部累加,适合火焰、光晕;不适合普通 UI |
| 预乘 alpha | ONE, ONE_MINUS_SRC_ALPHA |
纹理 RGB 已乘 alpha 时使用,可减少边缘黑边 |
绘制顺序与深度
先绘制不透明物体,再把透明物体按相机距离从远到近排序。透明阶段通常保留深度测试,但关闭深度写入,完成后恢复状态。
片段示例,依赖已启用深度缓冲并准备好透明对象列表:
gl.enable(gl.DEPTH_TEST);
gl.depthMask(false);
// drawTransparentObjectsBackToFront();
gl.depthMask(true);该片段依赖已完成排序的透明对象列表。关闭深度写入可避免较近透明物体提前占据深度缓冲,但无法解决相交几何体或单个网格内部三角形顺序错误。
风险与排障
当纹理采用预乘 alpha,却仍使用普通透明混合时,边缘可能发黑;安全做法是统一纹理上传方式与 blendFunc。当多个透明物体未排序时,结果会随绘制顺序变化;复杂相交场景应考虑拆分网格、顺序无关透明或专用后处理。
排查时依次确认:片元 alpha 是否小于 1.0、BLEND 是否启用、混合因子是否匹配纹理格式、透明对象是否后绘制并从远到近排序、透明阶段后是否恢复 depthMask(true)。
通过模板缓冲区限制渲染区域,实现遮罩、描边和镜面效果。
使用模板测试
模板测试用模板缓冲区中的整数标记决定片元是否继续写入颜色和深度,适合遮罩、轮廓、镜面区域和局部后处理。它通常分为“写入模板”和“按模板绘制”两个阶段。
前置条件
创建上下文时显式申请模板缓冲区,并检查实际位数。若 STENCIL_BITS 为 0,后续模板配置不会产生预期效果。
片段示例,依赖已取得 canvas 元素:
const gl = canvas.getContext("webgl", { stencil: true });
console.log(gl.getContextAttributes().stencil);
console.log(gl.getParameter(gl.STENCIL_BITS));预期输出中的位数取决于浏览器和设备;常见值为 8,但判断条件应是大于 0。
true
<BITS><BITS> 是实际模板位数。
两阶段流程
第一阶段关闭颜色写入,把遮罩区域写成模板值 1;第二阶段恢复颜色写入,只允许模板值等于 1 的片元通过。每次清理模板缓冲区前应把写掩码恢复为 0xFF。

可运行示例
下面的页面先写入一个矩形遮罩,再绘制更大的绿色矩形。最终只有落在遮罩内的部分可见。
<!doctype html>
<meta charset="utf-8">
<canvas id="c" width="480" height="280"></canvas>
<script>
const canvas = document.querySelector("#c");
const gl = canvas.getContext("webgl", { stencil: true });
if (!gl) throw new Error("WebGL unavailable");
if (gl.getParameter(gl.STENCIL_BITS) === 0) {
throw new Error("Stencil buffer unavailable");
}
const vsSource = `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`;
const fsSource = `
precision mediump float;
uniform vec4 u_color;
void main() {
gl_FragColor = u_color;
}`;
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vsSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
// 复用一个动态顶点缓冲区绘制遮罩和被裁剪对象。
const position = gl.getAttribLocation(program, "a_position");
const color = gl.getUniformLocation(program, "u_color");
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.useProgram(program);
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
function drawRect(x1, y1, x2, y2, rgba) {
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
x1, y1, x2, y1, x2, y2, x1, y2
]), gl.STREAM_DRAW);
gl.uniform4fv(color, rgba);
gl.drawArrays(gl.TRIANGLE_FAN, 0, 4);
}
gl.enable(gl.STENCIL_TEST);
gl.stencilMask(0xFF);
gl.clearStencil(0);
gl.clearColor(0.08, 0.08, 0.1, 1);
gl.clear(gl.COLOR_BUFFER_BIT | gl.STENCIL_BUFFER_BIT);
// 阶段一:不写颜色,只把遮罩区域的模板值替换为 1。
gl.colorMask(false, false, false, false);
gl.stencilFunc(gl.ALWAYS, 1, 0xFF);
gl.stencilOp(gl.KEEP, gl.KEEP, gl.REPLACE);
drawRect(-0.75, -0.55, 0.25, 0.55, [1, 1, 1, 1]);
// 阶段二:锁定模板写入,只在模板值等于 1 的位置写颜色。
gl.colorMask(true, true, true, true);
gl.stencilMask(0x00);
gl.stencilFunc(gl.EQUAL, 1, 0xFF);
gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
drawRect(-0.2, -0.8, 0.85, 0.8, [0.1, 0.9, 0.45, 1]);
console.log("STENCIL_BITS:", gl.getParameter(gl.STENCIL_BITS));
console.log("STENCIL_TEST:", gl.isEnabled(gl.STENCIL_TEST));
</script>预期结果:绿色矩形只显示在左侧遮罩矩形与它重叠的区域;控制台中的 <BITS> 为设备实际模板位数。
STENCIL_BITS: <BITS>
STENCIL_TEST: true常用配置
| 目标 | stencilFunc |
stencilOp |
说明 |
|---|---|---|---|
| 写入遮罩 | ALWAYS, ref, mask |
KEEP, KEEP, REPLACE |
通过深度测试后写入 ref |
| 仅遮罩内绘制 | EQUAL, ref, mask |
KEEP, KEEP, KEEP |
模板值相等时通过 |
| 仅遮罩外绘制 | NOTEQUAL, ref, mask |
KEEP, KEEP, KEEP |
常用于放大模型描边 |
| 计数重叠层 | 按目标选择 | INCR 或 DECR |
位数有限,需防止溢出或使用环绕版本 |
stencilOp 的三个参数分别对应模板测试失败、深度测试失败、两者都通过。描边通常先把原模型写入模板,再以 NOTEQUAL 绘制略微放大的同一模型。
风险与排障
未申请模板缓冲区时,模板测试可能始终无效;安全做法是启动时检查 STENCIL_BITS 并提供无模板降级路径。若写入遮罩后忘记恢复 colorMask(true, true, true, true),后续画面会完全不可见;若 stencilMask(0x00) 状态下清理模板缓冲区,旧值可能残留,应先恢复 0xFF 再执行 clear。
排查时确认:清理是否包含 STENCIL_BUFFER_BIT、参考值与比较函数是否一致、写阶段是否使用 REPLACE、读阶段是否关闭模板写入、颜色写掩码是否恢复。多轮渲染结束后可调用 gl.disable(gl.STENCIL_TEST),避免状态泄漏到后续绘制。
创建纹理对象并上传图片、Canvas、视频或像素数组。
创建二维纹理
用于把像素数据上传到 GPU,得到可在片元着色器中通过 sampler2D 读取的纹理。创建顺序固定为:创建对象、绑定目标、上传数据、设置完整性参数,再把纹理单元编号写入采样器。
基本语法
WebGL 1 常用两组 texImage2D 重载。像素数组需要显式传入宽高;图片、Canvas、视频和 ImageBitmap 直接作为数据源。
// Uint8Array / null:显式给出宽高
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA,
width, height, 0,
gl.RGBA, gl.UNSIGNED_BYTE, pixels
);
// HTMLImageElement / HTMLCanvasElement / HTMLVideoElement / ImageBitmap
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA,
gl.RGBA, gl.UNSIGNED_BYTE, source
);level 通常从 0 开始,border 在 WebGL 中必须为 0。当前绑定到 TEXTURE_2D 的纹理对象接收上传数据。
可运行示例
把下面内容保存为 texture.html 后直接用浏览器打开。示例上传 2×2 RGBA 像素,并用最近邻采样放大到整个画布。
<!doctype html>
<meta charset="utf-8">
<canvas id="glcanvas" width="256" height="256"></canvas>
<script>
const gl = document.getElementById("glcanvas").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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, `
attribute vec2 aPosition;
attribute vec2 aTexCoord;
varying vec2 vTexCoord;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
vTexCoord = aTexCoord;
}
`));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, `
precision mediump float;
varying vec2 vTexCoord;
uniform sampler2D uTexture;
void main() {
gl_FragColor = texture2D(uTexture, vTexCoord);
}
`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
function bindAttribute(name, values) {
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(values), gl.STATIC_DRAW);
const location = gl.getAttribLocation(program, name);
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
}
bindAttribute("aPosition", [-1, -1, 1, -1, -1, 1, 1, 1]);
bindAttribute("aTexCoord", [0, 0, 1, 0, 0, 1, 1, 1]);
const pixels = new Uint8Array([
255, 0, 0, 255, 0, 255, 0, 255,
0, 0, 255, 255, 255, 255, 0, 255
]);
const texture = gl.createTexture();
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA,
2, 2, 0,
gl.RGBA, gl.UNSIGNED_BYTE, pixels
);
// 纹理尺寸很小,使用最近邻能清楚看到四个色块
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.uniform1i(gl.getUniformLocation(program, "uTexture"), 0);
gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
console.log("texture ready", texture !== null, gl.getError() === gl.NO_ERROR);
</script>预期结果:画布显示放大的 2×2 四色纹理;控制台输出如下。
texture ready true true两个 true 分别表示纹理对象创建成功、当前 WebGL 错误码为 NO_ERROR。
常见数据源
- 图片或
ImageBitmap:适合静态素材;图片加载完成后再上传。 - Canvas:适合程序绘制、文字排版或离屏合成;内容变化后需再次调用
texImage2D或texSubImage2D。 - 视频:在
readyState >= HTMLMediaElement.HAVE_CURRENT_DATA后上传,并在需要更新画面时重复提交当前帧。 - 像素数组:适合调试纹理、数据纹理和运行时生成内容;数组长度至少为
width × height × 每像素字节数。
风险与边界
跨域图片未返回允许源站的 CORS 响应时,上传可能抛出安全异常。安全做法是在设置 src 前写入 image.crossOrigin = "anonymous",并让资源服务器返回匹配的 Access-Control-Allow-Origin。
图片坐标原点通常与纹理坐标方向相反,结果可能上下颠倒。上传前按需要调用 gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true),不要在着色器和上传阶段同时翻转。
纹理对象只属于创建它的 WebGL 上下文,不能跨 Canvas 或跨上下文复用。释放长期不用的纹理时调用 gl.deleteTexture(texture),避免 GPU 内存持续增长。
排障清单
- 采样结果全黑:确认纹理已绑定、采样器写入的是纹理单元编号
0而不是TEXTURE0常量。 INVALID_VALUE:检查宽高、数组长度和border是否为0。- 图片未显示:确认异步加载已完成,且上传时绑定的是目标纹理。
- 颜色或行错位:检查
format、type、每像素字节数以及UNPACK_ALIGNMENT。
设置纹理过滤、环绕方式和 mipmap 以控制缩放采样效果。
配置纹理采样
用于控制纹理放大、缩小和超出坐标范围时的取样方式。配置必须作用在当前绑定的纹理对象上;使用 mipmap 时还要生成完整的多级纹理。
采样参数
| 参数 | 常用值 | 作用 |
|---|---|---|
TEXTURE_MAG_FILTER |
NEAREST、LINEAR |
纹理被放大时的采样方式 |
TEXTURE_MIN_FILTER |
NEAREST、LINEAR、四种 mipmap 过滤 |
纹理被缩小时的采样方式 |
TEXTURE_WRAP_S |
CLAMP_TO_EDGE、REPEAT、MIRRORED_REPEAT |
水平方向超出 [0, 1] 后如何取样 |
TEXTURE_WRAP_T |
同上 | 垂直方向超出 [0, 1] 后如何取样 |
NEAREST 保留硬边和像素感;LINEAR 混合邻近纹素,画面更平滑。LINEAR_MIPMAP_LINEAR 会在相邻 mip 层之间再插值,远距离纹理通常更稳定,但占用更多显存并增加生成成本。

可运行示例
下面示例创建 4×4 纹理,启用三线性 mipmap 过滤、水平重复和垂直镜像重复,并读取参数验证是否生效。
<!doctype html>
<meta charset="utf-8">
<canvas id="glcanvas" width="1" height="1"></canvas>
<script>
const gl = document.getElementById("glcanvas").getContext("webgl");
if (!gl) throw new Error("当前浏览器不可用 WebGL");
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
// 4×4 是 2 的幂,WebGL 1 可安全使用 REPEAT 和 mipmap
const pixels = new Uint8Array(4 * 4 * 4);
for (let i = 0; i < pixels.length; i += 4) {
const white = ((i / 4) + Math.floor(i / 16)) % 2 === 0;
pixels.set(white ? [255, 255, 255, 255] : [30, 30, 30, 255], i);
}
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA,
4, 4, 0,
gl.RGBA, gl.UNSIGNED_BYTE, pixels
);
gl.texParameteri(
gl.TEXTURE_2D,
gl.TEXTURE_MIN_FILTER,
gl.LINEAR_MIPMAP_LINEAR
);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.MIRRORED_REPEAT);
gl.generateMipmap(gl.TEXTURE_2D);
console.log({
minFilter:
gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER) ===
gl.LINEAR_MIPMAP_LINEAR,
magFilter:
gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER) === gl.LINEAR,
wrapS:
gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S) === gl.REPEAT,
wrapT:
gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T) ===
gl.MIRRORED_REPEAT,
noError: gl.getError() === gl.NO_ERROR
});
</script>预期输出:
{minFilter: true, magFilter: true, wrapS: true, wrapT: true, noError: true}所有字段为 true 表示参数已写入当前纹理,且生成 mipmap 时没有产生 WebGL 错误。
高频配置
像素画、图标和调试贴图使用 NEAREST 放大,可避免边缘被插值模糊。普通照片或 UI 素材通常使用 LINEAR 放大。
远距离会明显缩小的地面、墙面或模型纹理,优先使用 LINEAR_MIPMAP_LINEAR,并在基础层上传完成后调用 generateMipmap。
纹理坐标必须限制在 [0, 1] 时使用 CLAMP_TO_EDGE;需要平铺材质时使用 REPEAT,需要减少接缝感时可用 MIRRORED_REPEAT。
风险与边界
TEXTURE_MAG_FILTER 只接受 NEAREST 或 LINEAR。传入 mipmap 枚举会触发 INVALID_ENUM,安全替代是把 mipmap 模式仅设置给 TEXTURE_MIN_FILTER。
WebGL 1 的非 2 次幂纹理不能使用 REPEAT、MIRRORED_REPEAT 或 mipmap;触发时纹理会变为不完整,采样常表现为黑色。安全配置是两轴都用 CLAMP_TO_EDGE,缩小过滤用 NEAREST 或 LINEAR,或者把素材缩放到 2 的幂尺寸。WebGL 2 已放宽这项限制。
纹理默认缩小过滤为 NEAREST_MIPMAP_LINEAR。只上传基础层却未生成 mipmap 时,纹理可能不完整。若暂时不需要 mipmap,应显式把 TEXTURE_MIN_FILTER 设为 LINEAR 或 NEAREST。
纹理内容更新后,旧 mip 层不会自动同步。基础层变化后重新调用 generateMipmap;高频视频纹理通常关闭 mipmap,避免每帧生成造成额外开销。
排障清单
- 参数似乎未生效:确认调用
texParameteri前绑定的是正确纹理。 - 缩小时闪烁:检查是否使用 mipmap,以及基础纹理是否已完整上传。
- 边缘出现接缝:检查纹理坐标、环绕模式和素材边缘像素是否连续。
- 画面全黑:优先检查 WebGL 1 非 2 次幂限制和 mipmap 完整性。
在图片资源加载完成后安全上传纹理并触发重新渲染。
异步加载纹理
用于图片尚未下载完成时先创建可用纹理,加载成功后再上传真实像素并重新绘制,避免首帧黑屏、纹理不完整或回调绑定错对象。
安全加载顺序
先上传一个 1×1 占位像素,使纹理立即完整;再注册 onload、onerror 后设置 src。图片完成时必须重新选择纹理单元并绑定目标纹理,因为异步回调执行时 WebGL 全局状态可能已被其他绘制修改。
可运行示例
下面页面先绘制蓝色占位纹理,再异步加载由 Canvas 生成的 2×2 图片。加载完成后重新上传、生成 mipmap,并主动调用 render()。
<!doctype html>
<meta charset='utf-8'>
<canvas id='c' width='320' height='240'></canvas>
<script>
const gl = document.querySelector('#c').getContext('webgl');
if (!gl) throw new Error('WebGL unavailable');
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, `
attribute vec2 aPos;
attribute vec2 aUv;
varying vec2 vUv;
void main() {
gl_Position = vec4(aPos, 0.0, 1.0);
vUv = aUv;
}`));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, `
precision mediump float;
varying vec2 vUv;
uniform sampler2D uTexture;
void main() {
gl_FragColor = texture2D(uTexture, vUv);
}`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vertices = new Float32Array([
-1,-1, 0,0, 1,-1, 1,0, -1,1, 0,1,
-1, 1, 0,1, 1,-1, 1,0, 1,1, 1,1
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const stride = 4 * Float32Array.BYTES_PER_ELEMENT;
const aPos = gl.getAttribLocation(program, 'aPos');
const aUv = gl.getAttribLocation(program, 'aUv');
gl.enableVertexAttribArray(aPos);
gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, stride, 0);
gl.enableVertexAttribArray(aUv);
gl.vertexAttribPointer(aUv, 2, gl.FLOAT, false, stride, 8);
const texture = gl.createTexture();
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
// 占位像素保证真实图片到达前纹理也处于 complete 状态。
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0,
gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([40, 100, 255, 255])
);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.uniform1i(gl.getUniformLocation(program, 'uTexture'), 0);
function render() {
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 6);
}
render();
const source = document.createElement('canvas');
source.width = source.height = 2;
const ctx = source.getContext('2d');
ctx.fillStyle = 'red'; ctx.fillRect(0, 0, 1, 1);
ctx.fillStyle = 'green'; ctx.fillRect(1, 0, 1, 1);
ctx.fillStyle = 'yellow'; ctx.fillRect(0, 1, 1, 1);
ctx.fillStyle = 'blue'; ctx.fillRect(1, 1, 1, 1);
const image = new Image();
image.onload = () => {
// 回调中重新选择单元和纹理,不能依赖之前残留的全局状态。
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA,
gl.UNSIGNED_BYTE, image
);
gl.generateMipmap(gl.TEXTURE_2D);
gl.texParameteri(
gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR
);
console.log('texture uploaded', image.naturalWidth, image.naturalHeight, gl.getError());
render();
};
image.onerror = () => console.error('texture load failed');
image.src = source.toDataURL('image/png');
</script>预期输出
texture uploaded 2 2 0页面先显示蓝色矩形,随后变为红、绿、黄、蓝四块组成的纹理;末尾 0 表示 gl.NO_ERROR。
关键边界
WebGL 1 中,非 2 的幂尺寸纹理不能使用 mipmap,且环绕方式必须为 CLAMP_TO_EDGE。检测到 NPOT 图片时不要调用 generateMipmap(),改用 LINEAR 和 CLAMP_TO_EDGE。
跨域图片若响应缺少允许当前站点的 CORS 头,texImage2D() 会拒绝上传。安全做法是使用同源资源,或在设置 src 前配置 image.crossOrigin = 'anonymous',并让资源服务器返回正确 CORS 响应。
同一材质连续切换 URL 时,较慢的旧请求可能覆盖新纹理。可为每次加载保存递增版本号,只允许最新版本的 onload 上传。
排障清单
- 首帧全黑:确认已上传占位像素,并设置了可用的
TEXTURE_MIN_FILTER。 - 图片加载后仍不变化:确认成功回调内调用了
render(),并重新绑定了正确纹理。 INVALID_OPERATION或INVALID_VALUE:检查图片跨域、纹理目标、像素格式及上下文是否已丢失。- 图像上下颠倒:在上传前设置
UNPACK_FLIP_Y_WEBGL;该状态是全局状态,后续不需要时应恢复为false。
速查:异步回调中始终执行“选择纹理单元 → 绑定纹理 → 上传像素 → 设置采样参数 → 重新渲染”。
将多张纹理绑定到不同纹理单元并在着色器中组合采样。
使用多个纹理单元
用于在一次绘制中同时读取多张纹理,例如底图叠加遮罩、颜色纹理乘光照纹理,或按权重混合两张图片。关键是把每个纹理对象绑定到独立纹理单元,再把采样器 uniform 指向对应的单元索引。
绑定关系
gl.activeTexture(gl.TEXTURE0 + i) 选择纹理单元,随后 bindTexture() 把纹理对象绑定到该单元;uniform1i() 接收的是整数索引 i,不是 gl.TEXTURE0 + i。

可运行示例
示例把红色纹理绑定到单元 0、蓝色纹理绑定到单元 1,并在片元着色器中各取 50%,最终得到紫色。
<!doctype html>
<meta charset='utf-8'>
<canvas id='c' width='320' height='240'></canvas>
<script>
const gl = document.querySelector('#c').getContext('webgl');
if (!gl) throw new Error('WebGL unavailable');
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, `
attribute vec2 aPos;
attribute vec2 aUv;
varying vec2 vUv;
void main() {
gl_Position = vec4(aPos, 0.0, 1.0);
vUv = aUv;
}`));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, `
precision mediump float;
varying vec2 vUv;
uniform sampler2D uTex0;
uniform sampler2D uTex1;
void main() {
vec4 base = texture2D(uTex0, vUv);
vec4 overlay = texture2D(uTex1, vUv);
gl_FragColor = mix(base, overlay, 0.5);
}`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vertices = new Float32Array([
-1,-1, 0,0, 1,-1, 1,0, -1,1, 0,1,
-1, 1, 0,1, 1,-1, 1,0, 1,1, 1,1
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const stride = 4 * Float32Array.BYTES_PER_ELEMENT;
for (const [name, offset] of [['aPos', 0], ['aUv', 8]]) {
const location = gl.getAttribLocation(program, name);
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, stride, offset);
}
function createSolidTexture(unit, rgba) {
const texture = gl.createTexture();
gl.activeTexture(gl.TEXTURE0 + unit);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0,
gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array(rgba)
);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
return texture;
}
createSolidTexture(0, [255, 0, 0, 255]);
createSolidTexture(1, [0, 0, 255, 255]);
// 采样器保存的是纹理单元编号,不是 TEXTURE0 枚举值。
gl.uniform1i(gl.getUniformLocation(program, 'uTex0'), 0);
gl.uniform1i(gl.getUniformLocation(program, 'uTex1'), 1);
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.drawArrays(gl.TRIANGLES, 0, 6);
console.log(
'MAX_TEXTURE_IMAGE_UNITS=' +
gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS)
);
console.log('gl.getError()=' + gl.getError());
</script>预期输出
MAX_TEXTURE_IMAGE_UNITS=<N>
gl.getError()=0<N> 由设备决定,实际值可能不同;画布显示均匀紫色,说明两个采样器分别读取了红色与蓝色纹理并完成混合。
高频用法
底图与透明遮罩组合时,分别采样颜色和 mask,并用 mask 控制 mix();光照贴图通常与底色逐分量相乘;法线贴图则与颜色纹理同时采样,但需要额外的切线空间计算。
纹理单元数量应按当前着色器阶段查询。片元着色器常用 MAX_TEXTURE_IMAGE_UNITS,不要把开发机的数量写死到资源系统中。
风险与边界
忘记再次调用 activeTexture() 会把新纹理覆盖到当前单元,结果通常是两个采样器读到同一张图。安全做法是把“选择单元、绑定纹理、设置采样器”封装为一次明确的材质绑定过程。
当采样器数量超过设备上限时,程序可能链接失败或绘制结果异常。应减少同时采样数量、合并纹理图集,或拆分为多次渲染。
不能在一次绘制中采样当前 framebuffer 正在写入的同一纹理,这会形成反馈回路。应使用两个纹理或两个 framebuffer 做 ping-pong 交换。
排障清单
- 只看到最后绑定的纹理:检查每次
bindTexture()前是否选择了不同的TEXTURE0 + i。 - 采样器全黑:检查
uniform1i()是否传入单元索引、纹理是否完整、类型是否与sampler2D匹配。 - 混合结果不符合预期:确认两张纹理的颜色空间、alpha 语义和 UV 坐标一致。
- 设备上失败:记录
MAX_TEXTURE_IMAGE_UNITS与程序链接日志,避免依赖固定上限。
兼容性提示:WebGL 1 着色器使用 texture2D();WebGL 2 通常改用 texture(),但纹理单元与采样器索引的绑定方式不变。
加载六个方向的纹理,用于天空盒、环境映射和反射效果。
创建立方体纹理
立方体纹理把六张正方形图像绑定到 +X、-X、+Y、-Y、+Z、-Z 六个方向,适合天空盒、环境映射和反射采样。创建成功的关键是六个面全部存在、尺寸一致,并在完整上传后再生成 mipmap。
六个面的方向

六个面必须使用相同宽高,通常为正方形。面方向由采样向量决定,不是普通二维纹理的前后顺序;图片朝向不一致时,会出现天空盒旋转错误或接缝。
| 方向 | WebGL 目标 |
|---|---|
+X |
gl.TEXTURE_CUBE_MAP_POSITIVE_X |
-X |
gl.TEXTURE_CUBE_MAP_NEGATIVE_X |
+Y |
gl.TEXTURE_CUBE_MAP_POSITIVE_Y |
-Y |
gl.TEXTURE_CUBE_MAP_NEGATIVE_Y |
+Z |
gl.TEXTURE_CUBE_MAP_POSITIVE_Z |
-Z |
gl.TEXTURE_CUBE_MAP_NEGATIVE_Z |
可运行示例
下面的完整 HTML 先生成六张演示图片的数据地址,再通过 Image 异步加载并上传,可直接保存为 cubemap.html 后打开。生产中只需把数据地址替换为六个真实图片 URL。
<!doctype html>
<meta charset="utf-8">
<title>WebGL Cubemap</title>
<canvas id="glcanvas" width="320" height="180"></canvas>
<script>
const gl = document.getElementById("glcanvas").getContext("webgl");
if (!gl) throw new Error("WebGL unavailable");
function makeFaceUrl(label, color) {
const canvas = document.createElement("canvas");
canvas.width = canvas.height = 128;
const ctx = canvas.getContext("2d");
ctx.fillStyle = color;
ctx.fillRect(0, 0, 128, 128);
ctx.fillStyle = "#fff";
ctx.font = "bold 36px sans-serif";
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillText(label, 64, 64);
return canvas.toDataURL("image/png");
}
function loadImage(url) {
return new Promise((resolve, reject) => {
const image = new Image();
image.onload = () => resolve(image);
image.onerror = () => reject(new Error(`failed to load ${url}`));
image.src = url;
});
}
const faces = [
[gl.TEXTURE_CUBE_MAP_POSITIVE_X, "+X", "#d33"],
[gl.TEXTURE_CUBE_MAP_NEGATIVE_X, "-X", "#933"],
[gl.TEXTURE_CUBE_MAP_POSITIVE_Y, "+Y", "#3a3"],
[gl.TEXTURE_CUBE_MAP_NEGATIVE_Y, "-Y", "#173"],
[gl.TEXTURE_CUBE_MAP_POSITIVE_Z, "+Z", "#36c"],
[gl.TEXTURE_CUBE_MAP_NEGATIVE_Z, "-Z", "#135"]
];
async function createCubeMap() {
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_CUBE_MAP, texture);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
// 异步加载期间先补齐六个面,避免纹理处于不完整状态。
const placeholder = new Uint8Array([0, 0, 0, 255]);
for (const [target] of faces) {
gl.texImage2D(
target,
0,
gl.RGBA,
1,
1,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
placeholder
);
}
const loadedFaces = await Promise.all(
faces.map(async ([target, label, color]) => ({
target,
label,
image: await loadImage(makeFaceUrl(label, color))
}))
);
for (const { target, label, image } of loadedFaces) {
gl.texImage2D(
target,
0,
gl.RGBA,
gl.RGBA,
gl.UNSIGNED_BYTE,
image
);
console.log(`uploaded ${label}`);
}
// 六个真实面全部就绪后再生成 mipmap。
gl.generateMipmap(gl.TEXTURE_CUBE_MAP);
gl.texParameteri(
gl.TEXTURE_CUBE_MAP,
gl.TEXTURE_MIN_FILTER,
gl.LINEAR_MIPMAP_LINEAR
);
gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
console.log(
"cube map ready",
gl.getError() === gl.NO_ERROR,
loadedFaces.length
);
return texture;
}
createCubeMap().catch(console.error);
</script>预期输出:
uploaded +X
uploaded -X
uploaded +Y
uploaded -Y
uploaded +Z
uploaded -Z
cube map ready true 6输出中的 true 表示本次上传未产生 WebGL 错误,6 表示六个面都已处理。此例只验证纹理创建;渲染时将其绑定到纹理单元,并让 samplerCube 使用归一化方向向量采样。
常用参数
TEXTURE_MIN_FILTER 决定缩小时的过滤方式。静态天空盒可在六面全部就绪后使用 LINEAR_MIPMAP_LINEAR;持续更新或尺寸不满足要求时使用 LINEAR,避免依赖 mipmap。
TEXTURE_WRAP_S 与 TEXTURE_WRAP_T 通常设为 CLAMP_TO_EDGE,防止边缘重复。立方体纹理没有单独的 R 环绕参数可在 WebGL 1 中配置,采样跨面由实现处理。
高频用法
静态天空盒应并行加载六张图,等待全部完成后一次生成 mipmap。环境反射把法线和视线计算出的反射向量传给 samplerCube。动态环境映射则把场景分别渲染到六个面,成本约为一次主场景之外再渲染六次,应降低分辨率或更新频率。
风险与边界
任一面缺失、尺寸不同或格式不一致时,纹理会处于不完整状态,采样常表现为黑色。安全做法是先为六个面上传同尺寸占位像素,待所有真实图片完成后再替换。
在 WebGL 1 中,对非 2 次幂尺寸使用 mipmap 会导致纹理不完整。可改用 2 次幂正方形图片,或关闭 mipmap 并设置 LINEAR 与 CLAMP_TO_EDGE。
跨域图片没有正确的 CORS 响应头时,上传可能抛出安全异常。应使用同源资源,或让资源服务器返回允许当前站点的 Access-Control-Allow-Origin,不要通过禁用浏览器安全策略规避。
排障清单
- 确认六个目标各上传一次,且宽高完全一致。
- 在最后一次上传后检查
gl.getError(),不要只看页面是否变黑。 - 核对
UNPACK_FLIP_Y_WEBGL与素材朝向,重点检查+Y、-Y和前后面。 - 渲染前确认活动纹理单元、
samplerCubeuniform 和绑定的纹理对象一致。 - 接缝明显时检查六张图边缘是否连续,并避免对单个面做不同裁剪或缩放。
速查:六面齐全、尺寸一致、完整后生成 mipmap,是立方体纹理可用的三项最低条件。
持续将视频帧更新到纹理,实现视频滤镜和实时画面合成。
渲染视频纹理
视频纹理需要把解码后的当前视频帧持续上传到二维纹理,再由片元着色器采样。稳定实现应在首帧或分辨率变化时重新分配纹理,后续帧使用 texSubImage2D 更新,避免每帧重复分配显存。
帧更新链路

只有当 video.readyState >= video.HAVE_CURRENT_DATA 时才上传帧。视频未解码、跨域策略不满足或播放未启动时,纹理通常保持黑色或停在首帧。
可运行示例
将一段同源视频命名为 demo.mp4,与下面文件放在同一目录,并通过本地 HTTP 服务打开。示例绘制一个全屏矩形,优先使用 requestVideoFrameCallback,不支持时回退到 requestAnimationFrame。
<!doctype html>
<meta charset="utf-8">
<title>WebGL Video Texture</title>
<video id="video" src="./demo.mp4" muted loop playsinline></video>
<button id="start" disabled>开始播放</button>
<canvas id="glcanvas" width="640" height="360"></canvas>
<script>
const video = document.getElementById("video");
const startButton = document.getElementById("start");
video.style.display = "none";
const gl = document.getElementById("glcanvas").getContext("webgl");
if (!gl) throw new Error("WebGL unavailable");
const vertexSource = `
attribute vec2 aPosition;
attribute vec2 aTexCoord;
varying vec2 vTexCoord;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
vTexCoord = aTexCoord;
}`;
const fragmentSource = `
precision mediump float;
uniform sampler2D uVideo;
varying vec2 vTexCoord;
void main() {
gl_FragColor = texture2D(uVideo, vTexCoord);
}`;
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vertexSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fragmentSource));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vertices = new Float32Array([
-1, -1, 0, 0,
1, -1, 1, 0,
-1, 1, 0, 1,
-1, 1, 0, 1,
1, -1, 1, 0,
1, 1, 1, 1
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const stride = 4 * Float32Array.BYTES_PER_ELEMENT;
const position = gl.getAttribLocation(program, "aPosition");
const texCoord = gl.getAttribLocation(program, "aTexCoord");
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, stride, 0);
gl.enableVertexAttribArray(texCoord);
gl.vertexAttribPointer(
texCoord,
2,
gl.FLOAT,
false,
stride,
2 * Float32Array.BYTES_PER_ELEMENT
);
const texture = gl.createTexture();
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.uniform1i(gl.getUniformLocation(program, "uVideo"), 0);
let textureWidth = 0;
let textureHeight = 0;
function scheduleNextFrame() {
if ("requestVideoFrameCallback" in video) {
video.requestVideoFrameCallback(uploadAndDraw);
} else {
requestAnimationFrame(uploadAndDraw);
}
}
function uploadAndDraw() {
if (video.readyState < video.HAVE_CURRENT_DATA) {
scheduleNextFrame();
return;
}
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
// 分辨率首次确定或发生变化时重新分配,普通帧只覆盖已有纹理。
if (
video.videoWidth !== textureWidth ||
video.videoHeight !== textureHeight
) {
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
gl.RGBA,
gl.UNSIGNED_BYTE,
video
);
textureWidth = video.videoWidth;
textureHeight = video.videoHeight;
} else {
gl.texSubImage2D(
gl.TEXTURE_2D,
0,
0,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
video
);
}
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.drawArrays(gl.TRIANGLES, 0, 6);
scheduleNextFrame();
}
video.addEventListener("loadeddata", () => {
startButton.disabled = false;
}, { once: true });
startButton.addEventListener("click", async () => {
await video.play();
startButton.disabled = true;
console.log(
`video texture started ${video.videoWidth}x${video.videoHeight}`
);
scheduleNextFrame();
}, { once: true });
</script>预期输出:
video texture started <WIDTH>x<HEIGHT><WIDTH> 和 <HEIGHT> 取决于实际视频。点击“开始播放”后,页面中的 WebGL 画布会持续显示视频画面;按钮触发的用户手势也能避开常见的自动播放限制。
关键参数
UNPACK_FLIP_Y_WEBGL 常设为 true,用于修正视频坐标原点与纹理坐标的上下方向。若顶点纹理坐标已经翻转,则保持 false,两处不要同时翻转。
视频尺寸经常不是 2 次幂。WebGL 1 中应使用 LINEAR 过滤和 CLAMP_TO_EDGE 环绕,不要为每帧调用 generateMipmap。WebGL 2 虽支持更完整的非 2 次幂纹理规则,实时视频通常仍不值得每帧生成 mipmap。
高频用法
视频滤镜直接在片元着色器中调整颜色、卷积或查表。实时合成可同时绑定视频纹理、遮罩纹理和背景纹理,再按 alpha 混合。摄像头画面可把 getUserMedia() 返回的 MediaStream 赋给 video.srcObject,后续上传逻辑保持不变。
风险与边界
每帧使用 texImage2D 会反复分配纹理存储,触发显存抖动和掉帧。安全替代是仅在首帧或分辨率改变时调用它,其余帧使用 texSubImage2D。
跨域视频没有正确 CORS 响应头时,上传到纹理可能被浏览器拒绝。应设置 video.crossOrigin = "anonymous",并让视频服务器允许当前来源;不要把关闭浏览器安全策略作为生产方案。
在视频尚未有当前帧时上传,会出现黑屏或 INVALID_VALUE。应检查 readyState、videoWidth 和 videoHeight,并在 loadeddata、playing 或视频帧回调之后开始更新。
持续在隐藏标签页或视频暂停后上传会浪费 CPU 与 GPU。页面不可见、视频暂停或播放结束时应停止调度,恢复播放后再继续。
排障清单
- 确认
video.currentTime持续变化,且videoWidth、videoHeight大于 0。 - 检查控制台是否有播放、媒体解码或 CORS 错误。
- 上传后检查
gl.getError(),重点关注INVALID_VALUE和INVALID_OPERATION。 - 核对活动纹理单元、
uVideo的整数值以及TEXTURE_2D绑定对象。 - 画面倒置时只在纹理坐标或
UNPACK_FLIP_Y_WEBGL中选择一处翻转。 - 画面卡顿时确认没有每帧重新创建纹理、缓冲区或着色器。
兼容性
requestVideoFrameCallback 能按视频真实解码节奏更新,但旧浏览器可能不支持,需回退到 requestAnimationFrame。移动端尤其是 iOS 浏览器应保留 muted 和 playsinline,并准备用户手势触发播放。
速查:首帧分配、后续覆盖、仅在视频帧可用时上传,是实时视频纹理稳定运行的核心。
结合顶点法线和光源参数实现环境光、漫反射与高光效果。
实现基础光照
需要快速给 WebGL 物体增加立体感时,可先组合环境光、Lambert 漫反射和 Blinn-Phong 高光。关键是把法线、光照方向和观察方向放在同一坐标空间,并在参与点积前归一化。
基本语法
三个分量可以直接理解为:环境光提供最低亮度,漫反射由 max(dot(N, L), 0.0) 决定,高光由法线、光线和视线共同决定。Blinn-Phong 使用半程向量 H = normalize(L + V),通常比直接计算反射向量更简洁。

可运行示例
下面的单文件示例可直接保存为 lighting.html 后用支持 WebGL2 的浏览器打开。三角形法线统一朝向屏幕外,通过方向光计算三种基础光照分量。
<!doctype html>
<meta charset="utf-8">
<canvas id="c" width="420" height="280"></canvas>
<script>
const gl = document.querySelector('#c').getContext('webgl2');
if (!gl) throw new Error('需要支持 WebGL2 的浏览器');
const vs = `#version 300 es
layout(location=0) in vec3 aPosition;
layout(location=1) in vec3 aNormal;
out vec3 vPos;
out vec3 vNormal;
void main() {
vPos = aPosition;
vNormal = aNormal;
gl_Position = vec4(aPosition, 1.0);
}`;
const fs = `#version 300 es
precision highp float;
in vec3 vPos;
in vec3 vNormal;
uniform vec3 uLightDir;
uniform vec3 uViewPos;
out vec4 outColor;
void main() {
vec3 N = normalize(vNormal);
vec3 L = normalize(uLightDir);
vec3 V = normalize(uViewPos - vPos);
vec3 H = normalize(L + V);
vec3 base = vec3(0.18, 0.55, 1.0);
vec3 ambient = 0.18 * base;
float diff = max(dot(N, L), 0.0);
vec3 diffuse = diff * base;
float spec = diff > 0.0 ? pow(max(dot(N, H), 0.0), 32.0) : 0.0;
vec3 color = ambient + diffuse + vec3(0.45) * spec;
outColor = vec4(color, 1.0);
}`;
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 program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vs));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fs));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
// 每个顶点依次存 position.xyz 和 normal.xyz。
const vertices = new Float32Array([
-0.8, -0.7, 0, 0, 0, 1,
0.8, -0.7, 0, 0, 0, 1,
0.0, 0.8, 0, 0, 0, 1
]);
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 24, 0);
gl.enableVertexAttribArray(1);
gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 24, 12);
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.clearColor(0.04, 0.04, 0.06, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(program);
// 所有方向和位置都处在同一个简化的世界空间中。
gl.uniform3f(gl.getUniformLocation(program, 'uLightDir'), 0.4, 0.3, 1.0);
gl.uniform3f(gl.getUniformLocation(program, 'uViewPos'), 0.0, 0.0, 2.0);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log('drawn', gl.getError() === gl.NO_ERROR);
</script>预期结果
drawn true
页面中央显示一个蓝色三角形:整体保留环境亮度,朝向光源部分更亮,并叠加较集中的白色高光。如果控制台为 drawn true 但物体全黑,优先检查法线是否归一化、N 与 L 是否方向相反,以及各向量是否混用了模型空间、世界空间或观察空间。
高频调节
- 环境光系数常从
0.05~0.25起调;过大时物体会失去明暗层次。 pow(..., shininess)的指数越大,高光越小越锐;常见起点为16、32或64。- 高光颜色或强度应独立于基础颜色调节,否则深色材质可能完全看不到高光。
- 模型发生旋转或非等比缩放后,应先正确变换法线,再进入上述计算。
风险与边界
最常见错误是把世界空间光源与模型空间法线直接点乘,结果会随物体变换出现错误明暗。安全做法是明确选定世界空间或观察空间,并把位置、法线、光线和视线统一转换到该空间。
该示例使用 WebGL2 与 GLSL ES 3.00;WebGL1 需要将 in/out 改为 attribute/varying,并通过 gl_FragColor 输出颜色。生产渲染还应考虑材质参数、线性颜色空间以及多光源累加。
在模型存在非等比缩放时正确变换法线方向。
计算法线矩阵
模型包含非等比缩放或错切时,不能直接用模型矩阵的左上角 3×3 部分变换法线,否则法线可能不再垂直于表面。应使用该线性变换的逆转置矩阵,并在变换后重新归一化。
基本语法
若光照在世界空间计算,法线矩阵为 transpose(inverse(mat3(modelMatrix)));若光照在观察空间计算,则应从 modelViewMatrix 计算。纯旋转或等比缩放经过归一化后通常不会暴露问题,非等比缩放和错切才是必须使用逆转置的典型场景。

可运行示例
下面代码不依赖第三方库,可直接在浏览器控制台或 Node.js 中运行。示例组合了 Z 轴旋转与 X/Y/Z = 2/1/0.5 的非等比缩放,并比较正确法线矩阵和直接使用模型矩阵的结果。
function inverse3(m) {
const [a,b,c,d,e,f,g,h,i] = m;
const det = a*(e*i-f*h) - b*(d*i-f*g) + c*(d*h-e*g);
// 零缩放等情况会产生奇异矩阵,此时不存在逆矩阵。
if (Math.abs(det) < 1e-8) throw new Error('singular matrix');
const k = 1 / det;
return [
(e*i-f*h)*k, (c*h-b*i)*k, (b*f-c*e)*k,
(f*g-d*i)*k, (a*i-c*g)*k, (c*d-a*f)*k,
(d*h-e*g)*k, (b*g-a*h)*k, (a*e-b*d)*k
];
}
function transpose3(m) {
return [m[0],m[3],m[6], m[1],m[4],m[7], m[2],m[5],m[8]];
}
function mul3v(m, v) {
return [
m[0]*v[0] + m[1]*v[1] + m[2]*v[2],
m[3]*v[0] + m[4]*v[1] + m[5]*v[2],
m[6]*v[0] + m[7]*v[1] + m[8]*v[2]
];
}
function normalize(v) {
const len = Math.hypot(...v);
return v.map(x => x / len);
}
const c = Math.SQRT1_2;
const s = Math.SQRT1_2;
// Rz(45°) * Scale(2, 1, 0.5) 的左上 3×3,按行存储。
const model3 = [
2*c, -s, 0,
2*s, c, 0,
0, 0, 0.5
];
const normal = normalize([1, 1, 0]);
const normalMatrix = transpose3(inverse3(model3));
const correct = normalize(mul3v(normalMatrix, normal));
const wrong = normalize(mul3v(model3, normal));
const round = v => v.map(x => Number(x.toFixed(4)));
console.log('correct', round(correct));
console.log('wrong ', round(wrong));预期输出
correct [ -0.3162, 0.9487, 0 ]
wrong [ 0.3162, 0.9487, 0 ]两组结果即使都经过归一化仍不同,说明问题不是法线长度,而是非等比缩放改变了方向关系。正确结果应来自逆转置矩阵。
高频用法
在 WebGL 渲染中,通常在 CPU 侧每个物体计算一次 mat3 法线矩阵并作为 uniform 上传,而不是在每个顶点执行矩阵求逆。如果模型只改变平移,法线矩阵无需受平移分量影响。
着色器中的核心片段通常只有两步:先乘法线矩阵,再归一化。
uniform mat3 uNormalMatrix;
vec3 N = normalize(uNormalMatrix * aNormal);该代码为片段示例,依赖顶点着色器中已声明的 aNormal 和 JavaScript 侧上传的 uNormalMatrix;生效后,非等比缩放模型的光照方向仍与真实表面方向一致。
风险与边界
当某个缩放轴为 0 或矩阵行列式接近 0 时,逆矩阵不存在或数值极不稳定,继续计算可能得到 NaN 并污染后续光照。安全做法是避免用零缩放表达隐藏状态;需要隐藏对象时直接跳过绘制,或在业务层保证几何变换保持可逆。
还要确保法线矩阵与光照空间一致:世界空间光照使用模型矩阵的逆转置,观察空间光照使用模型视图矩阵的逆转置。WebGL2 的 GLSL ES 3.00 可使用矩阵 inverse,但为性能和兼容性考虑,生产代码通常仍在 CPU 侧预计算后上传。
将渲染结果输出到纹理或渲染缓冲区,而不是直接显示到画布。
创建帧缓冲区
帧缓冲区用于把一轮渲染写入纹理或渲染缓冲区,常见于后处理、阴影贴图、拾取和多阶段渲染。核心顺序是:绑定帧缓冲区、创建附件存储、挂载附件、检查完整性、设置视口并绘制。

基本语法
创建离屏目标时通常按以下顺序执行:
createFramebuffer()创建对象,bindFramebuffer()设为当前目标。- 为颜色纹理或渲染缓冲区分配非零尺寸的存储。
- 使用
framebufferTexture2D()或framebufferRenderbuffer()挂载附件。 - 调用
checkFramebufferStatus(),只有返回FRAMEBUFFER_COMPLETE才开始绘制。 - 切换到离屏目标后重新设置
viewport;完成后绑定null返回画布。
可运行示例
下面代码可直接粘贴到浏览器开发者工具控制台。它创建一个 64×64 的颜色纹理和深度渲染缓冲区,清空离屏目标,再读取一个像素验证结果。
const canvas = document.createElement('canvas');
canvas.width = 64;
canvas.height = 64;
const gl = canvas.getContext('webgl');
if (!gl) throw new Error('WebGL is unavailable');
const width = 64;
const height = 64;
// 颜色纹理保存离屏结果,后续可交给另一个绘制阶段采样。
const colorTexture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, colorTexture);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
width,
height,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
null
);
// 不需要读取深度值时,渲染缓冲区通常比深度纹理更直接。
const depthBuffer = gl.createRenderbuffer();
gl.bindRenderbuffer(gl.RENDERBUFFER, depthBuffer);
gl.renderbufferStorage(
gl.RENDERBUFFER,
gl.DEPTH_COMPONENT16,
width,
height
);
// 先完成附件存储分配,再把它们挂载到帧缓冲区。
const framebuffer = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
gl.framebufferTexture2D(
gl.FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
colorTexture,
0
);
gl.framebufferRenderbuffer(
gl.FRAMEBUFFER,
gl.DEPTH_ATTACHMENT,
gl.RENDERBUFFER,
depthBuffer
);
// 附件全部挂载后再检查,避免把未完成状态带入绘制阶段。
const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
if (status !== gl.FRAMEBUFFER_COMPLETE) {
throw new Error(`Framebuffer incomplete: 0x${status.toString(16)}`);
}
// 视口必须匹配当前离屏目标,而不是沿用画布尺寸。
gl.viewport(0, 0, width, height);
gl.clearColor(1, 0, 0, 1);
gl.clearDepth(1);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
const pixel = new Uint8Array(4);
gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
console.log('framebuffer complete:', true);
console.log('pixel:', Array.from(pixel).join(','));
gl.bindFramebuffer(gl.FRAMEBUFFER, null);预期输出:
framebuffer complete: true
pixel: 255,0,0,255第一行表示附件组合完整;第二行表示清屏颜色已经写入离屏纹理。实际项目中应在切回默认帧缓冲区后,把该纹理绑定到后处理着色器采样。
风险与边界
当同一纹理既挂在当前帧缓冲区上,又被当前绘制调用采样时会形成读写反馈环,可能触发 INVALID_OPERATION 或产生不可用结果。安全做法是使用两个纹理或两个帧缓冲区交替读写。
附件尺寸为 0、格式不可渲染或 WebGL 1 中附件尺寸不一致时,帧缓冲区不会完整。浮点颜色附件、深度纹理和多重采样还可能依赖 WebGL 版本或扩展;优先从 RGBA/UNSIGNED_BYTE 颜色纹理和 DEPTH_COMPONENT16 渲染缓冲区开始验证。
离屏目标和画布尺寸可能不同。绑定帧缓冲区后若仍沿用画布的 viewport,常见后果是只渲染局部区域或所有像素被裁剪;每次切换目标都应按目标尺寸重设视口。
排障清单
- 绘制前确认
checkFramebufferStatus()返回FRAMEBUFFER_COMPLETE。 - 创建或重设附件后检查宽高均大于 0,并确认颜色、深度附件尺寸一致。
- 在每次附件调用后临时读取
gl.getError(),定位非法格式、目标或 mipmap 层级。 - 读取结果全黑时,先验证
viewport、清屏颜色、绘制缓冲区绑定状态,再检查着色器。 - 画布缩放或纹理重建后重新分配附件存储,并再次检查完整性。
兼容性
示例使用 WebGL 1 可直接支持的单颜色附件。WebGL 2 可使用多个颜色附件、drawBuffers() 和多重采样渲染缓冲区;WebGL 1 的多渲染目标需要 WEBGL_draw_buffers 扩展。
验证附件格式和尺寸是否匹配,定位离屏渲染不完整问题。
检查帧缓冲区状态
checkFramebufferStatus() 用于验证当前绑定帧缓冲区的附件是否可共同作为渲染目标。它应在创建附件、调整尺寸或更换格式后调用,先解决完整性错误,再排查着色器和绘制逻辑。

基本语法
调用形式为 gl.checkFramebufferStatus(gl.FRAMEBUFFER)。检查前必须先用 bindFramebuffer() 绑定目标对象;返回值等于 gl.FRAMEBUFFER_COMPLETE 才能继续绘制。记录故障时同时输出十六进制状态码和常量名称,便于跨浏览器比对。
可运行诊断示例
下面代码先挂载一个尚未分配图像存储的纹理,得到不完整状态;随后调用 texImage2D() 分配存储,再次检查应变为完整。
const gl = document.createElement('canvas').getContext('webgl');
if (!gl) throw new Error('WebGL is unavailable');
// 将数值状态转换为可检索的常量名称。
function statusName(gl, status) {
const known = [
[gl.FRAMEBUFFER_COMPLETE, 'FRAMEBUFFER_COMPLETE'],
[gl.FRAMEBUFFER_INCOMPLETE_ATTACHMENT, 'FRAMEBUFFER_INCOMPLETE_ATTACHMENT'],
[gl.FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT, 'FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT'],
[gl.FRAMEBUFFER_UNSUPPORTED, 'FRAMEBUFFER_UNSUPPORTED']
];
if ('FRAMEBUFFER_INCOMPLETE_DIMENSIONS' in gl) {
known.push([
gl.FRAMEBUFFER_INCOMPLETE_DIMENSIONS,
'FRAMEBUFFER_INCOMPLETE_DIMENSIONS'
]);
}
return known.find(([value]) => value === status)?.[1] ?? 'UNKNOWN_STATUS';
}
function report(label) {
const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
console.log(
`${label}: 0x${status.toString(16)} ${statusName(gl, status)}`
);
}
// 先挂载一个未分配图像存储的纹理,主动制造不完整状态。
const framebuffer = gl.createFramebuffer();
const texture = gl.createTexture();
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.framebufferTexture2D(
gl.FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
texture,
0
);
report('before allocation');
// 为同一个纹理层级分配存储后,再检查状态是否恢复。
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
32,
32,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
null
);
report('after allocation');预期输出:
before allocation: 0x8cd6 FRAMEBUFFER_INCOMPLETE_ATTACHMENT
after allocation: 0x8cd5 FRAMEBUFFER_COMPLETE第一行说明附件对象存在,但其图像层级尚未定义;第二行说明分配 32×32 存储后,颜色附件已满足完整性要求。
状态读取
FRAMEBUFFER_COMPLETE:附件组合可用于渲染。FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT:没有挂载任何有效附件。FRAMEBUFFER_INCOMPLETE_ATTACHMENT:至少一个附件未定义、尺寸为 0、格式不可渲染或挂载方式非法。FRAMEBUFFER_INCOMPLETE_DIMENSIONS:WebGL 1 附件尺寸不一致。FRAMEBUFFER_UNSUPPORTED:实现不支持当前格式组合。FRAMEBUFFER_INCOMPLETE_MULTISAMPLE:WebGL 2 多重采样附件的样本数或固定采样位置不一致。
排障清单
- 确认检查前绑定的是目标帧缓冲区,而不是
null或另一个对象。 - 对每个纹理附件确认目标、mipmap 层级、内部格式、宽高和数据类型与创建调用一致。
- 对每个渲染缓冲区确认已经调用
renderbufferStorage()或 WebGL 2 的renderbufferStorageMultisample()。 - WebGL 1 中统一所有附件尺寸;WebGL 2 多重采样附件统一样本数。
- 浮点颜色、深度纹理或额外颜色附件失败时,检查对应扩展或改回基础格式验证。
- 调整画布或重建纹理后再次检查,旧的完整状态不能代表新附件仍然有效。
风险与边界
FRAMEBUFFER_COMPLETE 只证明附件配置可作为渲染目标,不代表绘制一定正确。错误的视口、着色器、深度状态、读写反馈环或上下文丢失仍会导致黑屏或 INVALID_OPERATION。
状态检查可能触发驱动侧验证,不应每帧重复调用。安全做法是在创建、重分配和恢复 WebGL 上下文时检查一次,并把状态码和附件尺寸写入诊断日志。
兼容性
WebGL 1 常见状态包含尺寸不一致;WebGL 2 增加多重采样相关检查,并允许更丰富的颜色附件格式。跨版本排障时优先使用基础 RGBA/UNSIGNED_BYTE 颜色纹理验证,再逐步恢复浮点、深度纹理或多渲染目标。
将场景渲染到纹理后执行模糊、灰度、描边或色彩调整。
实现后处理效果
当同一场景需要灰度、模糊、描边或统一调色时,先把场景渲染到离屏纹理,再用全屏三角形读取该纹理并执行第二次着色。这样效果与场景材质解耦,也便于继续串联多个后处理 pass。
基本语法
核心链路是 场景 → FBO 颜色纹理 → 后处理着色器 → 默认帧缓冲。单个效果只需一个离屏纹理;多个相互依赖的效果通常使用两组纹理/FBO 交替读写,避免同一纹理同时作为采样源和渲染目标。

高频用法
灰度、曝光、对比度和 LUT 调色通常可在一个全屏 pass 中完成;高斯模糊常拆成横向、纵向两个 pass;描边若依赖场景几何信息,通常还要额外输出深度、法线或对象 ID 纹理。
下面示例可直接放进浏览器页面的 <script> 中运行:第一遍把彩色渐变写入纹理,第二遍读取纹理并转成灰度,完整覆盖“渲染到纹理 → 后处理 → 输出屏幕”的主流程。
const canvas = document.createElement("canvas");
canvas.width = 640;
canvas.height = 360;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("WebGL2 unavailable");
function makeProgram(vsSource, fsSource) {
const compile = (type, source) => {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(s));
}
return s;
};
const p = gl.createProgram();
gl.attachShader(p, compile(gl.VERTEX_SHADER, vsSource));
gl.attachShader(p, compile(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(p);
if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(p));
}
return p;
}
const vs = `#version 300 es
out vec2 vUv;
void main() {
vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);
vUv = p;
gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
}`;
const sceneProgram = makeProgram(vs, `#version 300 es
precision highp float;
in vec2 vUv;
out vec4 outColor;
void main() {
outColor = vec4(vUv, 0.25, 1.0);
}`);
const postProgram = makeProgram(vs, `#version 300 es
precision highp float;
uniform sampler2D uScene;
in vec2 vUv;
out vec4 outColor;
void main() {
vec3 c = texture(uScene, vUv).rgb;
float y = dot(c, vec3(0.2126, 0.7152, 0.0722));
outColor = vec4(vec3(y), 1.0);
}`);
const tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA8,
canvas.width, canvas.height, 0,
gl.RGBA, gl.UNSIGNED_BYTE, null
);
const fbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
gl.framebufferTexture2D(
gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D, tex, 0
);
if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
throw new Error("offscreen framebuffer incomplete");
}
// Pass 1:写入离屏纹理。
gl.viewport(0, 0, canvas.width, canvas.height);
gl.useProgram(sceneProgram);
gl.drawArrays(gl.TRIANGLES, 0, 3);
// Pass 2:采样离屏纹理并输出灰度结果。
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.useProgram(postProgram);
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.uniform1i(gl.getUniformLocation(postProgram, "uScene"), 0);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log("postprocess ready: grayscale pass rendered");预期输出
postprocess ready: grayscale pass rendered画布应显示一张灰度渐变图。若仍是彩色,重点检查第二遍是否已绑定默认帧缓冲、uScene 是否指向纹理单元 0,以及离屏 FBO 是否为 FRAMEBUFFER_COMPLETE。
风险与边界
后处理每增加一个全屏 pass,通常就增加一次整屏纹理读取和写入;在高分辨率或移动 GPU 上可能明显增加带宽和显存占用。安全替代方案是降低中间纹理分辨率、合并可合并的颜色变换,或只对局部区域执行昂贵效果。
排障清单
若画面全黑,先检查 FBO 完整性、纹理尺寸与视口是否一致,再确认第二遍确实绑定了源纹理。出现上下颠倒时,统一纹理坐标约定或在后处理顶点/片元着色器中翻转 vUv.y;模糊出现采样越界时,应明确设置 TEXTURE_WRAP_S/T 为 CLAMP_TO_EDGE。
使用多重采样渲染缓冲区并解析结果以减少边缘锯齿。
启用多重采样抗锯齿
当离屏渲染结果需要更平滑的几何边缘时,可在 WebGL2 中把颜色先写入多重采样 renderbuffer,再用 blitFramebuffer 解析到普通单采样纹理或默认帧缓冲。多重采样缓冲不能直接作为普通 sampler2D 采样源。
基本语法
关键 API 是 renderbufferStorageMultisample(target, samples, internalFormat, width, height)。samples 不能超过 gl.getParameter(gl.MAX_SAMPLES);解析阶段把多采样 FBO 绑定到 READ_FRAMEBUFFER,把单采样 FBO 绑定到 DRAW_FRAMEBUFFER,再执行 blitFramebuffer。

常用参数
| 参数 | 含义 | 常用约束 |
|---|---|---|
samples |
每像素样本数 | 常用 2 或 4,必须不大于 MAX_SAMPLES |
internalFormat |
renderbuffer 格式 | 颜色常用 RGBA8,需与解析目标兼容 |
width / height |
多采样缓冲尺寸 | 应与当前渲染区域一致 |
解析多采样颜色缓冲时,blitFramebuffer 的过滤参数必须使用 NEAREST;不要用 LINEAR。
高频用法
下面示例创建 4x MSAA(若设备上限不足则自动降级),把三角形渲染到多采样 FBO,解析到普通纹理 FBO,再复制到屏幕。
const canvas = document.createElement("canvas");
canvas.width = 640;
canvas.height = 360;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("WebGL2 unavailable");
function program(vsSource, fsSource) {
const shader = (type, source) => {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(s));
}
return s;
};
const p = gl.createProgram();
gl.attachShader(p, shader(gl.VERTEX_SHADER, vsSource));
gl.attachShader(p, shader(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(p);
if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(p));
}
return p;
}
const p = program(
`#version 300 es
void main() {
vec2 pos[3] = vec2[3](
vec2(-0.8, -0.7),
vec2( 0.8, -0.7),
vec2( 0.0, 0.8)
);
gl_Position = vec4(pos[gl_VertexID], 0.0, 1.0);
}`,
`#version 300 es
precision highp float;
out vec4 outColor;
void main() { outColor = vec4(0.1, 0.7, 1.0, 1.0); }`
);
const w = canvas.width;
const h = canvas.height;
const samples = Math.min(4, gl.getParameter(gl.MAX_SAMPLES));
const msaaColor = gl.createRenderbuffer();
gl.bindRenderbuffer(gl.RENDERBUFFER, msaaColor);
gl.renderbufferStorageMultisample(
gl.RENDERBUFFER, samples, gl.RGBA8, w, h
);
const msaaFbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, msaaFbo);
gl.framebufferRenderbuffer(
gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0,
gl.RENDERBUFFER, msaaColor
);
if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
throw new Error("MSAA framebuffer incomplete");
}
const resolvedTex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, resolvedTex);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA8, w, h, 0,
gl.RGBA, gl.UNSIGNED_BYTE, null
);
const resolveFbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, resolveFbo);
gl.framebufferTexture2D(
gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D, resolvedTex, 0
);
if (
gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE
) {
throw new Error("resolve framebuffer incomplete");
}
// 先在多采样缓冲中绘制。
gl.bindFramebuffer(gl.FRAMEBUFFER, msaaFbo);
gl.viewport(0, 0, w, h);
gl.clearColor(0.06, 0.06, 0.08, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(p);
gl.drawArrays(gl.TRIANGLES, 0, 3);
// 再解析到单采样纹理,最后复制到默认帧缓冲。
gl.bindFramebuffer(gl.READ_FRAMEBUFFER, msaaFbo);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, resolveFbo);
gl.blitFramebuffer(0, 0, w, h, 0, 0, w, h, gl.COLOR_BUFFER_BIT, gl.NEAREST);
gl.bindFramebuffer(gl.READ_FRAMEBUFFER, resolveFbo);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, null);
gl.blitFramebuffer(0, 0, w, h, 0, 0, w, h, gl.COLOR_BUFFER_BIT, gl.NEAREST);
console.log(`MSAA samples: ${samples}, resolve complete`);预期输出
MSAA samples: <SAMPLES>, resolve complete<SAMPLES> 的实际值由 Math.min(4, MAX_SAMPLES) 决定,可能小于 4。画布应显示边缘经过多重采样处理的蓝色三角形。
风险与边界
MSAA 会按样本数增加颜色、深度等 renderbuffer 的存储和带宽开销;大尺寸离屏缓冲配 4x/8x MSAA 时,移动设备容易出现帧率下降或显存压力。若只需要最终画布抗锯齿,可先尝试 getContext("webgl2", { antialias: true }) 并通过 getContextAttributes().antialias 验证实际是否启用;性能敏感时也可改用 FXAA/SMAA 后处理。
排障清单
出现 INVALID_OPERATION 时,先确认解析源确实是多采样 FBO、目标是单采样 FBO,并使用 NEAREST。解析后仍有锯齿时,检查 samples 是否实际大于 1;画面黑屏则分别检查两个 FBO 的完整性和宽高是否一致。窗口尺寸变化后要重新分配 renderbuffer 与纹理,否则解析区域可能与真实画布不匹配。
兼容性
上述流程依赖 WebGL2 的 renderbufferStorageMultisample、READ_FRAMEBUFFER、DRAW_FRAMEBUFFER 和 blitFramebuffer。WebGL1 没有这些核心 API;必须改用浏览器支持的多重采样扩展,或退回默认帧缓冲抗锯齿/后处理抗锯齿方案。