WebGL WEBGL_depth_texture Khronos Ratified Extension Specification

Name

WEBGL_depth_texture

Contact

WebGL working group (public_webgl 'at' khronos.org)

Contributors

Members of the WebGL working group

Florian Bösch (pyalot 'at' gmail.com)

Version

Last modified date: March 15, 2020
Revision: 13

Number

WebGL extension #9

Dependencies

Written against the WebGL API 1.0 specification.

No longer available as of the WebGL API 2.0 specification.

Overview

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:

ANGLE_depth_texture provides both depth and depth/stencil textures.
ANGLE_depth_texture does not provide the DEPTH24_STENCIL8_OES renderbuffer internal format from the OES_packed_depth_stencil extension. The core WebGL specification already supports allocation of depth/stencil renderbuffers.
ANGLE_depth_texture does not support loading image data via the TexImage or TexSubImage commands. Depth and depth/stencil textures created via this extension can only have their contents specified by rendering to them.

Consult the Errors section below for specific restrictions.

When this extension is enabled:

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

Alias Name Strings (for draft extensions)

WEBKIT_WEBGL_depth_texture
MOZ_WEBGL_depth_texture

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_depth_texture {
  const GLenum UNSIGNED_INT_24_8_WEBGL = 0x84FA;
};

Errors

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.

Issues

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.

Revision History

Revision 1, 2012/01/23

Initial revision.

Revision 2, 2012/01/25

Added provisions to exclude cube depth textures.

Revision 3, 2012/02/06

Changed referenced WebGL API version from 2.0 to 1.0

Revision 4, 2012/02/24

Removed the enumerants from the IDL which are contained in the context and added aliases to the extension name

Revision 5, 2012/03/01

Renamed with OES prefix and removed the addendum due to expected harmonization between OES_depth_texture and ARB_depth_texture (depth cube maps).

Revision 6, 2012/06/04

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.

Revision 7, 2012/06/20

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.

Revision 8, 2012/06/27

Updated references to texSubImage2D. Added DEPTH_STENCIL_ATTACHMENT to framebufferTexture2D.

Revision 9, 2013/01/26

Moved from draft to community approved status

Revision 10, 2013/02/28

Updated to track ANGLE_depth_texture, indicating that only red channel is guaranteed.

Revision 11, 2013/05/15

Ratified by Khronos Board of Promoters.

Revision 12, 2014/07/15

Added NoInterfaceObject extended attribute.

Revision 13, 2020/03/15

Update ANGLE_depth_texture link.