WebGL2深度纹理texImage2D参数错误及帧缓冲绑定问题求助

问题背景 #

在基于glmatrix的WebGL项目中实现深度纹理时，遇到以下报错：

• 初始报错：WebGL: INVALID_VALUE: texImage2D: invalid internalformat - depthTexture
• 调整参数后出现新报错：

  GL_INVALID_OPERATION: Invalid combination of format, type and internalFormat.
  GL_INVALID_OPERATION: Only array uniforms may have count > 1.
  

初始实现代码：

const depthTextures = gl => {
  const depthTexture = gl.createTexture();
  const depthTextureSize = 512;
  gl.bindTexture(gl.TEXTURE_2D, depthTexture);
  gl.texImage2D(gl.TEXTURE_2D, // target
  0, // mip level
  gl.DEPTH_COMPONENT, // internal format
  depthTextureSize, // width
  depthTextureSize, // height
  0, // border
  gl.DEPTH_COMPONENT, // format
  gl.UNSIGNED_INT, // type
  null); // data

  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_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);
  const depthFramebuffer = gl.createFramebuffer();
  gl.bindFramebuffer(gl.FRAMEBUFFER, depthFramebuffer);
  gl.framebufferTexture2D(gl.FRAMEBUFFER, // target
  gl.DEPTH_ATTACHMENT, // attachment point
  gl.TEXTURE_2D, // texture target
  depthTexture, // texture
  0); // mip level
  // create a color texture of the same size as the depth texture
  // see article why this is needed_

  const unusedTexture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, unusedTexture);
  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, depthTextureSize, depthTextureSize, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_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); // attach it to the framebuffer

  gl.framebufferTexture2D(gl.FRAMEBUFFER, // target
  gl.COLOR_ATTACHMENT0, // attachment point
  gl.TEXTURE_2D, // texture target
  unusedTexture, // texture
  0); // mip level

  return [depthFramebuffer, unusedTexture];
};

查阅资料得知：

Note: This extension is only available to WebGL1 contexts. In WebGL2,
the functionality of this extension is available on the WebGL2 context
by default. The constant in WebGL2 is gl.UNSIGNED_INT_24_8.

尝试将DEPTH_COMPONENT替换为RGBA后仍无法绑定帧缓冲，调整为以下参数组合后出现新错误：

gl.texImage2D(
    gl.TEXTURE_2D,      // target
    0,                  // mip level
    gl.RGBA, // internal format
    depthTextureSize,   // width
    depthTextureSize,   // height
    0,                  // border
    gl.RGBA, // format
    gl.UNSIGNED_INT_24_8,    // type
    null);              // data

解决建议 #

1. 区分WebGL版本处理深度纹理 #

• WebGL2环境：原生支持深度纹理，无需扩展。使用正确的参数组合创建：

  // 纯深度纹理
  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    gl.DEPTH_COMPONENT24,
    depthTextureSize,
    depthTextureSize,
    0,
    gl.DEPTH_COMPONENT,
    gl.UNSIGNED_INT,
    null
  );
  // 绑定深度附件
  gl.framebufferTexture2D(
    gl.FRAMEBUFFER,
    gl.DEPTH_ATTACHMENT,
    gl.TEXTURE_2D,
    depthTexture,
    0
  );
  

  或者使用深度模板组合格式：

  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    gl.DEPTH_STENCIL,
    depthTextureSize,
    depthTextureSize,
    0,
    gl.DEPTH_STENCIL,
    gl.UNSIGNED_INT_24_8,
    null
  );
  // 绑定深度模板附件
  gl.framebufferTexture2D(
    gl.FRAMEBUFFER,
    gl.DEPTH_STENCIL_ATTACHMENT,
    gl.TEXTURE_2D,
    depthTexture,
    0
  );
  

• WebGL1环境：必须先启用WEBGL_depth_texture扩展，否则无法使用深度纹理：

  const ext = gl.getExtension('WEBGL_depth_texture');
  if (!ext) {
    console.error('WEBGL_depth_texture extension not supported');
    return;
  }
  

  启用后使用扩展提供的格式常量创建：

  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    ext.DEPTH_COMPONENT,
    depthTextureSize,
    depthTextureSize,
    0,
    ext.DEPTH_COMPONENT,
    gl.UNSIGNED_SHORT, // 或gl.UNSIGNED_INT，根据浏览器支持选择
    null
  );
  

2. 修正参数组合错误 #

你之前尝试的gl.RGBA+gl.UNSIGNED_INT_24_8是无效组合，UNSIGNED_INT_24_8仅对应DEPTH_STENCIL格式，不能和RGBA混用。必须保证三者匹配：

• 纯深度纹理：internalformat为DEPTH_COMPONENT/DEPTH_COMPONENT24，format对应DEPTH_COMPONENT，type为UNSIGNED_SHORT或UNSIGNED_INT
• 深度模板纹理：internalformat为DEPTH_STENCIL，format对应DEPTH_STENCIL，type为UNSIGNED_INT_24_8

3. 移除不必要的颜色附件（可选） #

WebGL2中可直接创建仅含深度附件的帧缓冲，无需附加无用颜色纹理；WebGL1中若启用WEBGL_depth_texture，可尝试仅绑定深度附件，若帧缓冲状态为gl.FRAMEBUFFER_COMPLETE则无需颜色纹理。

4. 排查uniform相关错误 #

第二个错误Only array uniforms may have count > 1与深度纹理无关，检查着色器代码：是否有非数组uniform被传入多个值，比如调用gl.uniform1fv时，目标uniform不是数组类型但传入了长度大于1的数组。

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