WebGL2渲染至3D纹理失败排查：无报错但纹理值为空

我之前踩过WebGL2渲染3D纹理的坑，这种“没报错但输出全空”的情况，十有八九是某个细节没做到位，咱们一步步来排查：

1. 帧缓冲附加3D纹理层的方式是否正确 #

你得用gl.framebufferTextureLayer()而非普通的gl.framebufferTexture2D()，而且每次切换渲染层时，都要重新附加并检查帧缓冲状态——别嫌麻烦，某些GPU对层切换的状态缓存有坑：

// 补全你的伪代码逻辑
this.fbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);

// 循环处理每一层3D纹理
for (let layer = 0; layer < 64; layer++) {
  // 附加当前要写入的纹理层
  gl.framebufferTextureLayer(
    gl.FRAMEBUFFER, 
    gl.COLOR_ATTACHMENT0, 
    your3DTexture, 
    0, // mip级别，这里用0级即可
    layer // 目标纹理层索引
  );
  
  // 必须检查帧缓冲状态！很多人会忽略这步
  const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
  if (status !== gl.FRAMEBUFFER_COMPLETE) {
    console.error(`Layer ${layer} 帧缓冲不完整: ${status}`);
    break;
  }
  
  // 设置对应尺寸的视口（关键！不然渲染会被裁剪）
  gl.viewport(0, 0, 64, 64);
  
  // 执行当前层的渲染绘制
  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
}

gl.bindFramebuffer(gl.FRAMEBUFFER, null);

2. 3D纹理的初始化参数是否正确 #

你的gl.RGBA8内部格式和gl.RGBA格式是没问题的，但初始化时必须正确分配存储空间：

const your3DTexture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_3D, your3DTexture);

// 推荐用texStorage3D一次性分配所有层的空间（WebGL2支持）
gl.texStorage3D(
  gl.TEXTURE_3D,
  1, // mip层级数，这里只用1级
  gl.RGBA8,
  64, 64, 64 // 宽、高、深度
);

// 设置过滤和环绕参数（避免采样异常）
gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_R, gl.CLAMP_TO_EDGE);

如果用gl.texImage3D初始化，一定要传入null作为数据，不然预填充的内容会覆盖后续渲染结果。

3. 着色器输出是否正常 #

先写个最简单的测试着色器排除逻辑问题：

#version 300 es
precision highp float;
out vec4 fragColor;

void main() {
  fragColor = vec4(1.0, 0.0, 0.0, 1.0); // 固定输出红色
}

如果这样读取纹理还是空，那问题肯定在帧缓冲或纹理设置上；如果能读到红色，再回头排查你的业务着色器逻辑。

4. 读取纹理的方式是否正确 #

WebGL2不能直接读取绑定的3D纹理，必须先把目标层附加到帧缓冲，再用gl.readPixels读取：

const pixelData = new Uint8Array(64 * 64 * 4);
gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);

// 附加要读取的纹理层
gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, your3DTexture, 0, 0);
// 读取像素数据
gl.readPixels(0, 0, 64, 64, gl.RGBA, gl.UNSIGNED_BYTE, pixelData);

console.log(pixelData); // 如果用测试着色器，应该全是255,0,0,255

内容的提问来源于stack exchange，提问作者novalain