Web 图形与 3D / 系统课时
排查黑屏、NaN 和精度伪影
排查黑屏、NaN 和精度伪影
Shader 画面全黑、出现孤立亮点或在手机上产生条带,可能分别来自绘制管线、非法浮点运算和精度不足。这里用可运行的 WebGL2 样例,将编译检查、固定色测试、中间变量可视化和数值保护串成一套可复现的排障顺序。
学习目标
- 利用编译日志、固定色输出和像素回读判断黑屏发生在哪一层。
- 通过可视化中间变量与保护分母排除 NaN、Inf 等异常值。
- 根据数值范围和设备差异排查
mediump引起的条带与抖动。
先判断黑屏发生在哪一层
按以下顺序操作,不要一开始就重写颜色公式:
- 检查
canvas.getContext("webgl2")是否成功,使用gl.COMPILE_STATUS、gl.LINK_STATUS和对应的getShaderInfoLog()、getProgramInfoLog()查明编译或链接失败。 - 暂时将片元输出改为固定洋红色
vec4(1.0, 0.0, 1.0, 1.0)。能看到洋红色,说明至少当前片元绘制和颜色输出链路工作;仍是黑屏,优先检查gl.useProgram()、gl.viewport()、VAO、深度/裁剪状态和帧缓冲绑定。 - 如果使用离屏 Pass,先绑定目标 FBO,再检查
gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;最终显示到画布前应绑定默认帧缓冲null。 - 固定色正常后,再把 UV、距离、噪声或遮罩单独输出为灰度图,找到第一个与预期不符的变量。

运行可观察的最小例子
把下面代码保存为 debug.html,用支持 WebGL2 的浏览器打开,按 F12 查看 Console。它用 gl_VertexID 画覆盖整个视口的三角形,不依赖顶点缓冲或外部纹理;片元颜色展示中心距离生成的亮度。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>WebGL2 Shader Debug</title>
<canvas id="view" width="640" height="360"></canvas>
<script>
const canvas = document.getElementById("view");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器或设备未提供 WebGL2");
const vertexSource = `#version 300 es
void main() {
// 全屏三角形:不需要上传顶点属性
vec2 p = vec2(gl_VertexID == 1 ? 3.0 : -1.0,
gl_VertexID == 2 ? 3.0 : -1.0);
gl_Position = vec4(p, 0.0, 1.0);
}`;
const fragmentSource = `#version 300 es
precision highp float;
uniform vec2 u_resolution;
out vec4 outColor;
void main() {
vec2 uv = gl_FragCoord.xy / u_resolution;
float d = length(uv - vec2(0.5));
// 先保护分母,再计算亮度,避免中心区域发生零除
float brightness = clamp(0.15 / max(d, 1e-4), 0.0, 1.0);
outColor = vec4(vec3(brightness), 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) || "Shader 编译失败");
}
return shader;
}
const vs = compile(gl.VERTEX_SHADER, vertexSource);
const fs = compile(gl.FRAGMENT_SHADER, fragmentSource);
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) || "Program 链接失败");
}
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.bindVertexArray(gl.createVertexArray());
gl.useProgram(program);
gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
gl.uniform2f(gl.getUniformLocation(program, "u_resolution"),
gl.drawingBufferWidth, gl.drawingBufferHeight);
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
// 立即回读中心像素,不依赖肉眼判断画布是否被其他元素遮挡
const pixel = new Uint8Array(4);
gl.readPixels(320, 180, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
console.log("shader/program OK");
console.log("center RGBA:", JSON.stringify(Array.from(pixel)));
console.log("gl error:", gl.getError());
</script>
</html>预期输出(浏览器 Console):
shader/program OK
center RGBA: [255,255,255,255]
gl error: 0画布应显示中心白、向边缘逐渐变暗的径向亮度图。若这一样例正常而项目黑屏,问题通常位于项目特有的 uniform、纹理、状态切换或后处理 Pass;不要据此认定项目里的数值计算也正确。readPixels 得到的是当前帧缓冲的像素,gl.getError() === 0 也不代表 Shader 内没有 NaN。
用中间量找到非法数值
保持顶点程序不变,逐次替换片元中的 outColor 赋值:先用 vec4(uv, 0.0, 1.0) 检查坐标是否从左下向右上渐变,再用 vec4(vec3(d), 1.0) 看距离场是否从中心向外增亮。对于原本在 [-1, 1] 的值,先映射为 0.5 + 0.5 * value,否则简单截断为 [0, 1] 会把负数误看成纯黑。
常见问题要在产生异常值之前拦截:
- 零除:
0.15 / d在d = 0时不安全;本例以max(d, 1e-4)设置最小分母。阈值使用的是归一化 UV 单位,不宜未经换算直接用于世界坐标。 - 零向量归一化: 对可能为零的
v,用v / max(length(v), 1e-4)代替无条件normalize(v)。 - 函数定义域: 对可能为负的开方输入使用
sqrt(max(x, 0.0));对角度反余弦输入使用acos(clamp(x, -1.0, 1.0))。 - 已经污染的输入: GLSL ES 3.00 提供
isnan()、isinf(),可辅助将异常位置标记为洋红;但零除等非法运算的具体结果具有实现差异,不应假定每台 GPU 都生成可检测的 NaN。
区分精度伪影与采样锯齿
GLSL ES 3.00 的片元浮点变量可声明 precision highp float;。在只达到最低精度要求的实现上,mediump 的相对精度约为 ,而 4096 像素宽画面中相邻 UV 的水平间隔仅为 ;相邻值可能被量化为相同结果,出现条带、台阶或细节闪烁。桌面 GPU 可能对 mediump 使用更高精度,因此桌面正常不等于移动端正常。
排查时先将距离、UV 计算、累计时间及噪声坐标统一设为 highp,并检查跨顶点与片元阶段的 out/in 插值变量精度是否一致。若变量数值增大,例如以秒累计的时间达到 20000,已超出 mediump 最低保证的约 量级,更应避免用它承载计时或大世界坐标。
如果切换 highp 后仍出现沿几何轮廓的锯齿,问题可能是像素覆盖与采样频率,而非浮点精度;程序化边缘可考虑用 fwidth() 自适应过渡,纹理需检查过滤与 mipmap。不要把精度提升当作所有闪烁的通用修复。
做一次可复现的回归检查
- 在最小例子中临时把片元输出改成固定洋红色,再刷新页面:画布应为洋红色,中心回读应为
[255, 0, 255, 255]。恢复原赋值后应重新出现径向图和[255, 255, 255, 255]。 - 在真实项目中逐个恢复纹理采样、噪声、遮罩及最终混合;每恢复一层就记录首次异常的中间值范围和对应的 uniform。
- 分别在桌面与目标移动设备上观察 640×360 和实际渲染分辨率,检查中心异常点、条带、时间增长后的跳变;若使用离屏 FBO,还要逐个确认完整性和 Pass 顺序。
getError()、readPixels() 与部分编译状态查询可能触发 GPU 同步,适合初始化或故障定位,不应作为每帧常驻检查。保留有明确开关的调试输出,在验证通过后关闭同步回读。