WEBGL_depth_texture WEBKIT_WEBGL_depth_texture MOZ_WEBGL_depth_texture WebGL working group (public_webgl 'at' khronos.org) Members of the WebGL working group Florian Bösch (pyalot 'at' gmail.com) 9

This extension exposes the ANGLE_depth_texture functionality to WebGL. ANGLE_depth_texture provides a subset of the functionality from the OpenGL ES 2.0 extensions OES_depth_texture and OES_packed_depth_stencil, with certain restrictions added for portability reasons. Specifically:

Consult the Errors section below for specific restrictions.

The texImage2D entry point is extended to accept the format parameter DEPTH_COMPONENT and DEPTH_STENCIL The texImage2D entry point is extended to accept the internalFormat parameter DEPTH_COMPONENT and DEPTH_STENCIL The texImage2D entry point is extended to accept the type parameter UNSIGNED_SHORT, UNSIGNED_INT, and UNSIGNED_INT_24_8_WEBGL The framebufferTexture2D entry point is extended to accept the target parameter DEPTH_ATTACHMENT and DEPTH_STENCIL_ATTACHMENT The texImage2D entry point is extended to accept ArrayBufferView of type Uint16Array and Uint32Array

The WebGL-specific constraints about Framebuffer Object Attachments are extended:

  • A texture attached to an FBO's DEPTH_ATTACHMENT attachment point must be allocated with the DEPTH_COMPONENT internal format.
  • A texture attached to the DEPTH_STENCIL_ATTACHMENT attachment point must be allocated with the DEPTH_STENCIL internal format.

In the WebGL API, it is an error to concurrently attach either renderbuffers or textures to the following combinations of attachment points:

  • DEPTH_ATTACHMENT + DEPTH_STENCIL_ATTACHMENT
  • STENCIL_ATTACHMENT + DEPTH_STENCIL_ATTACHMENT
  • DEPTH_ATTACHMENT + STENCIL_ATTACHMENT

See the section Framebuffer Object Attachments in the WebGL specification for the behavior if these constraints are violated.

As per the OpenGL ES spec, there is no guarantee that the OpenGL ES implementation will use the texture type to determine how to store the depth texture internally. It may choose to downsample the 32-bit depth values to 16-bit or even 24-bit. When a depth or depth/stencil texture is attached to a framebuffer object, calls to getParameter with the DEPTH_BITS and STENCIL_BITS enums return the following:
Texture Type DEPTH_BITS (GLint) STENCIL_BITS (GLint)
UNSIGNED_SHORT >= 16 0
UNSIGNED_INT >= 16 0
UNSIGNED_INT_24_8_WEBGL >= 24 >= 8

[NoInterfaceObject] interface WEBGL_depth_texture { const GLenum UNSIGNED_INT_24_8_WEBGL = 0x84FA; }; The error INVALID_OPERATION is generated by texImage2D if the format parameter is DEPTH_COMPONENT or DEPTH_STENCIL and the target is TEXTURE_CUBE_MAP_{POSITIVE,NEGATIVE}_{X,Y,Z}. The error INVALID_OPERATION is generated by texImage2D if format and internalformat are DEPTH_COMPONENT and type is not UNSIGNED_SHORT or UNSIGNED_INT. The error INVALID_OPERATION is generated by texImage2D if format and internalformat are not DEPTH_COMPONENT and type is UNSIGNED_SHORT or UNSIGNED_INT. The error INVALID_OPERATION is generated by texImage2D if format and internalformat are DEPTH_STENCIL and type is not UNSIGNED_INT_24_8_WEBGL. The error INVALID_OPERATION is generated by texImage2D if format and internalformat are not DEPTH_STENCIL and type is UNSIGNED_INT_24_8_WEBGL. The error INVALID_OPERATION is generated in the following situations:
  • texImage2D is called with format and internalformat of DEPTH_COMPONENT or DEPTH_STENCIL and
    • target is not TEXTURE_2D,
    • data is not NULL, or
    • level is not zero.
  • texSubImage2D is called with format of DEPTH_COMPONENT or DEPTH_STENCIL.
  • copyTexImage2D is called with an internalformat that has a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL.
  • copyTexSubImage2D is called with a target texture that has a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL.
  • generateMipmap is called on a texture that has a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL.

As per the ANGLE_depth_texture specification, when a depth texture is sampled, the value is stored into the RED channel. The contents of the GREEN, BLUE and ALPHA channels are implementation dependent. It is therefore recommended to use only the r component of variables in GLSL shaders that are used to reference depth textures.

Initial revision. Added provisions to exclude cube depth textures. Changed referenced WebGL API version from 2.0 to 1.0 Removed the enumerants from the IDL which are contained in the context and added aliases to the extension name Renamed with OES prefix and removed the addendum due to expected harmonization between OES_depth_texture and ARB_depth_texture (depth cube maps). Renamed to WEBGL prefix, and changed to reference ANGLE_depth_texture, because of limitations preventing the current ANGLE library from loading of image data to depth textures. Incorporated errors from ANGLE_depth_texure extension specification. Incorporated depth/stencil support and UNSIGNED_INT_24_8_WEBGL enum after discussion on public_webgl mailing list, including supported behavior and additional error behavior. Extended rules in Section 6.5 ("Framebuffer Object Attachments") to handle texture attachments. Updated references to texSubImage2D. Added DEPTH_STENCIL_ATTACHMENT to framebufferTexture2D. Moved from draft to community approved status Updated to track ANGLE_depth_texture, indicating that only red channel is guaranteed. Ratified by Khronos Board of Promoters. Added NoInterfaceObject extended attribute.