Web 图形与 3D / 系统课时

读取着色器日志定位黑屏

读取着色器日志定位黑屏

WebGL 2 场景黑屏,可能是 GLSL 编译失败,也可能是画布尺寸、顶点布局、矩阵、纹理或深度状态出了问题。先运行一个可见的最小三角形,读取 Shader、Program 和 WebGL 错误信息,再按渲染链路逐层恢复,避免一次修改多个位置。

学习目标

  • 使用 COMPILE_STATUS、LINK_STATUS 和 getError() 区分三类错误。
  • 按视口、清屏、Program、顶点属性、矩阵、纹理、深度的顺序定位模型缺失。
  • 通过固定颜色和受控故障验证排查结论。

建立能独立运行的诊断场景

在支持 WebGL 2 的浏览器中打开开发者工具 Console,粘贴并执行以下 JavaScript。脚本自行创建 480×270 的 Canvas,绘制一个不依赖矩阵和纹理的蓝色三角形,并报告编译、链接和绘制阶段的检查结果。

js
(() => {
  const canvas = document.createElement('canvas');
  canvas.width = 480;
  canvas.height = 270;
  canvas.style.border = '1px solid #64748b';
  document.body.appendChild(canvas);
  const gl = canvas.getContext('webgl2');
  if (!gl) throw new Error('当前环境不支持 WebGL 2');

  const vertexSource = `#version 300 es
layout(location = 0) in vec2 aPosition;
void main() {
  gl_Position = vec4(aPosition, 0.0, 1.0);
}`;
  const fragmentSource = `#version 300 es
precision highp float;
out vec4 outColor;
void main() {
  outColor = vec4(0.2, 0.7, 1.0, 1.0);
}`;

  // 以状态位判定成功与否,日志即使为空也不能代替状态位。
  function compile(type, source, label) {
    const shader = gl.createShader(type);
    if (!shader) throw new Error(label + '创建失败');
    gl.shaderSource(shader, source);
    gl.compileShader(shader);
    const ok = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
    const info = gl.getShaderInfoLog(shader);
    console.log(label + '编译: ' + (ok ? '成功' : '失败'));
    if (info) console.log(info);
    if (!ok) throw new Error(label + '编译失败');
    return shader;
  }

  const vertex = compile(gl.VERTEX_SHADER, vertexSource, '顶点着色器');
  const fragment = compile(gl.FRAGMENT_SHADER, fragmentSource, '片元着色器');
  const program = gl.createProgram();
  if (!program) throw new Error('Program 创建失败');
  gl.attachShader(program, vertex);
  gl.attachShader(program, fragment);
  gl.linkProgram(program);
  const linked = gl.getProgramParameter(program, gl.LINK_STATUS);
  const linkInfo = gl.getProgramInfoLog(program);
  console.log('Program 链接: ' + (linked ? '成功' : '失败'));
  if (linkInfo) console.log(linkInfo);
  if (!linked) throw new Error('Program 链接失败');
  gl.deleteShader(vertex);
  gl.deleteShader(fragment);
  gl.useProgram(program);

  // VAO 保存 location 0 的顶点属性配置。
  const vao = gl.createVertexArray();
  const vbo = gl.createBuffer();
  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
    -0.7, -0.7, 0.7, -0.7, 0.0, 0.7
  ]), gl.STATIC_DRAW);
  gl.enableVertexAttribArray(0);
  gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);

  // 先关闭深度测试,用最少状态确认基本绘制可见。
  gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
  gl.disable(gl.DEPTH_TEST);
  gl.clearColor(0.06, 0.08, 0.12, 1);
  gl.clear(gl.COLOR_BUFFER_BIT);
  gl.drawArrays(gl.TRIANGLES, 0, 3);
  const error = gl.getError();
  console.log('getError: ' + (error === gl.NO_ERROR ? 'NO_ERROR' : error));
})();

预期 Console 至少出现以下四行,页面新增的画布显示深色背景和蓝色三角形;部分浏览器或驱动还可能输出额外提示。

text
顶点着色器编译: 成功
片元着色器编译: 成功
Program 链接: 成功
getError: NO_ERROR

根据日志判断失败发生在哪里

Shader 编译失败:gl.getShaderParameter(shader, gl.COMPILE_STATUS) 返回 false,立即查看该 Shader 的 gl.getShaderInfoLog(shader)。重点检查 #version 300 es、变量类型、语法与 in/out 声明。日志中的行号指向传给 shaderSource 的源码,不一定对应 HTML 文件行号。

Program 链接失败:两个 Shader 可能都编译成功,但 gl.getProgramParameter(program, gl.LINK_STATUS) 仍为 false。这时读取 gl.getProgramInfoLog(program),检查跨阶段 out/in 类型和名称是否匹配;不能因为两个 Shader 编译成功就跳过链接检查。

WebGL 状态错误:gl.getError() 返回 gl.NO_ERROR 表示当前没有待报告的 GL 错误;若返回 gl.INVALID_OPERATION 等枚举值,应在 useProgram、属性设置和绘制调用之后分别检查,以定位出错的调用。一次 getError() 只取走一个错误标志,需要时重复读取直至 NO_ERROR。编译或链接失败应以各自状态位为准,而不是依赖 getError()。

按画面层级缩小故障范围

工程中先尝试把画布清成亮紫色,再逐层恢复绘制。每次只调整一项,确认画面变化后才继续。

WebGL 2 黑屏逐层排查流程

  1. 视口与画布:先确认 canvas.width、canvas.height 以及 gl.drawingBufferWidth、gl.drawingBufferHeight 均大于零;同时排除 CSS 隐藏或显示尺寸为零。画布调整尺寸后调用 gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight)。
  2. 清屏:临时调用 gl.disable(gl.SCISSOR_TEST)、gl.colorMask(true, true, true, true)、gl.clearColor(1, 0, 1, 1),再执行 gl.clear(gl.COLOR_BUFFER_BIT)。若仍看不到紫色,先查 Canvas 显示、当前绑定的帧缓冲及清屏区域,而不是修改光照公式。使用自建 FBO 时还要核对 gl.checkFramebufferStatus(gl.FRAMEBUFFER) 是否为 gl.FRAMEBUFFER_COMPLETE。
  3. Program:确认 LINK_STATUS 为 true,绘制时用 gl.getParameter(gl.CURRENT_PROGRAM) 检查当前绑定的是目标 Program。Program 链接成功却没有 gl.useProgram(program),仍可能无法按预期渲染。
  4. 顶点属性:检查 VAO 是否已绑定、layout(location = 0) 是否对应 gl.enableVertexAttribArray(0) 和 gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0)。本例 gl.drawArrays(gl.TRIANGLES, 0, 3) 必须提交三个顶点;顶点数写成 0 不会产生三角形。
  5. 矩阵与裁剪:先使用本例直接输出裁剪空间位置的顶点着色器;恢复场景时再检查 Projection × View × Model 的乘法顺序、Uniform 上传和近远裁剪面。顶点进入裁剪空间后,只有满足 -w ≤ x,y,z ≤ w(并且 w 有效)的部分才可能可见。
  6. 纹理与透明度:先让片元着色器输出固定不透明颜色;若这样可见而贴图后消失,检查 activeTexture 对应的纹理单元、uniform1i 的单元索引和纹理完整性。未生成 Mipmap 时可暂将 TEXTURE_MIN_FILTER 设为 LINEAR,并排查采样结果是否为黑色或 Alpha 是否为零。
  7. 深度与剔除:暂时关闭 gl.DEPTH_TEST 和 gl.CULL_FACE。若模型出现,再逐个恢复;常见深度初始化是 gl.depthMask(true)、gl.clearDepth(1)、gl.depthFunc(gl.LESS),并在绘制前清除 gl.DEPTH_BUFFER_BIT。前后面绕序错误则检查剔除设置。

故意制造故障验证排查方法

在最小示例上一次只做一处修改,重新运行并观察现象:

  • 将片元着色器里的 vec4(0.2, 0.7, 1.0, 1.0) 改成不存在的 vec5(0.2, 0.7, 1.0, 1.0):应看到“片元着色器编译: 失败”,具体错误日志措辞随浏览器和驱动变化。
  • 将视口设置改为 gl.viewport(0, 0, 0, 0):编译、链接仍成功,getError 仍可为 NO_ERROR,但只有清屏背景,没有三角形。
  • 将绘制调用改成 gl.drawArrays(gl.TRIANGLES, 0, 0):同样不会产生三角形,且不一定报告错误;这说明还必须核对提交的顶点数量。

实际项目中,先保留编译和链接日志,再从可见清屏色开始逐项恢复复杂状态。只要明确找到第一个由正常变为不可见的步骤,就能把黑屏范围收敛到一组具体 API、数据或渲染状态。

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

目录与阅读设置

阅读设置

17

记录一个想法

读取着色器日志定位黑屏

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

登录哪都通