Web 图形与 3D / 系统课时

排查黑屏、NaN 和精度伪影

排查黑屏、NaN 和精度伪影

Shader 画面全黑、出现孤立亮点或在手机上产生条带,可能分别来自绘制管线、非法浮点运算和精度不足。这里用可运行的 WebGL2 样例,将编译检查、固定色测试、中间变量可视化和数值保护串成一套可复现的排障顺序。

学习目标

  • 利用编译日志、固定色输出和像素回读判断黑屏发生在哪一层。
  • 通过可视化中间变量与保护分母排除 NaN、Inf 等异常值。
  • 根据数值范围和设备差异排查 mediump 引起的条带与抖动。

先判断黑屏发生在哪一层

按以下顺序操作,不要一开始就重写颜色公式:

  1. 检查 canvas.getContext("webgl2") 是否成功,使用 gl.COMPILE_STATUS、gl.LINK_STATUS 和对应的 getShaderInfoLog()、getProgramInfoLog() 查明编译或链接失败。
  2. 暂时将片元输出改为固定洋红色 vec4(1.0, 0.0, 1.0, 1.0)。能看到洋红色,说明至少当前片元绘制和颜色输出链路工作;仍是黑屏,优先检查 gl.useProgram()、gl.viewport()、VAO、深度/裁剪状态和帧缓冲绑定。
  3. 如果使用离屏 Pass,先绑定目标 FBO,再检查 gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;最终显示到画布前应绑定默认帧缓冲 null。
  4. 固定色正常后,再把 UV、距离、噪声或遮罩单独输出为灰度图,找到第一个与预期不符的变量。

WebGL2 黑屏、非法数值与精度伪影的排查分支

运行可观察的最小例子

把下面代码保存为 debug.html,用支持 WebGL2 的浏览器打开,按 F12 查看 Console。它用 gl_VertexID 画覆盖整个视口的三角形,不依赖顶点缓冲或外部纹理;片元颜色展示中心距离生成的亮度。

html
<!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):

text
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 的相对精度约为 2−102^{-10},而 4096 像素宽画面中相邻 UV 的水平间隔仅为 1/4096=0.0002441/4096=0.000244;相邻值可能被量化为相同结果,出现条带、台阶或细节闪烁。桌面 GPU 可能对 mediump 使用更高精度,因此桌面正常不等于移动端正常。

排查时先将距离、UV 计算、累计时间及噪声坐标统一设为 highp,并检查跨顶点与片元阶段的 out/in 插值变量精度是否一致。若变量数值增大,例如以秒累计的时间达到 20000,已超出 mediump 最低保证的约 2142^{14} 量级,更应避免用它承载计时或大世界坐标。

如果切换 highp 后仍出现沿几何轮廓的锯齿,问题可能是像素覆盖与采样频率,而非浮点精度;程序化边缘可考虑用 fwidth() 自适应过渡,纹理需检查过滤与 mipmap。不要把精度提升当作所有闪烁的通用修复。

做一次可复现的回归检查

  1. 在最小例子中临时把片元输出改成固定洋红色,再刷新页面:画布应为洋红色,中心回读应为 [255, 0, 255, 255]。恢复原赋值后应重新出现径向图和 [255, 255, 255, 255]。
  2. 在真实项目中逐个恢复纹理采样、噪声、遮罩及最终混合;每恢复一层就记录首次异常的中间值范围和对应的 uniform。
  3. 分别在桌面与目标移动设备上观察 640×360 和实际渲染分辨率,检查中心异常点、条带、时间增长后的跳变;若使用离屏 FBO,还要逐个确认完整性和 Pass 顺序。

getError()、readPixels() 与部分编译状态查询可能触发 GPU 同步,适合初始化或故障定位,不应作为每帧常驻检查。保留有明确开关的调试输出,在验证通过后关闭同步回读。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查黑屏、NaN 和精度伪影

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

登录哪都通