michael@0: Name michael@0: michael@0: ANGLE_depth_texture michael@0: michael@0: Name Strings michael@0: michael@0: GL_ANGLE_depth_texture michael@0: michael@0: Contributors michael@0: michael@0: Nicolas Capens, TransGaming michael@0: Daniel Koch, TransGaming michael@0: Shannon Woods, TransGaming michael@0: Kenneth Russell, Google michael@0: Vangelis Kokkevis, Google michael@0: Gregg Tavares, Google michael@0: Contributors to OES_depth_texture michael@0: Contributors to OES_packed_depth_stencil michael@0: michael@0: Contact michael@0: michael@0: Shannon Woods, TransGaming (shannon 'dot' woods 'at' transgaming.com) michael@0: michael@0: Status michael@0: michael@0: Implemented in ANGLE. michael@0: michael@0: Version michael@0: michael@0: Last Modified Date: February 25, 2013 michael@0: Revision: #4 michael@0: michael@0: Number michael@0: michael@0: TBD michael@0: michael@0: Dependencies michael@0: michael@0: OpenGL ES 2.0 is required. michael@0: This extension is written against the OpenGL ES 2.0.25 specification michael@0: michael@0: OES_packed_depth_stencil affects the definition of this extension. michael@0: michael@0: EXT_texture_storage affects the definition of this extension. michael@0: michael@0: Overview michael@0: michael@0: This extension defines support for 2D depth and depth-stencil michael@0: textures in an OpenGL ES implementation. michael@0: michael@0: This extension incorporates the depth texturing functionality of michael@0: OES_depth_texture and OES_packed_depth_stencil, but does not michael@0: provide the ability to load existing data via TexImage2D or michael@0: TexSubImage2D. This extension also allows implementation michael@0: variability in which components from a sampled depth texture michael@0: contain the depth data. Depth textures created with this michael@0: extension only support 1 level. michael@0: michael@0: New Procedures and Functions michael@0: michael@0: None michael@0: michael@0: New Tokens michael@0: michael@0: Accepted by the parameter of TexImage2D and TexSubImage2D and michael@0: parameter of TexImage2D: michael@0: michael@0: DEPTH_COMPONENT 0x1902 michael@0: DEPTH_STENCIL_OES 0x84F9 michael@0: michael@0: Accepted by the parameter of TexImage2D, TexSubImage2D: michael@0: michael@0: UNSIGNED_SHORT 0x1403 michael@0: UNSIGNED_INT 0x1405 michael@0: UNSIGNED_INT_24_8_OES 0x84FA michael@0: michael@0: Accepted by the parameter of TexStorage2DEXT: michael@0: michael@0: DEPTH_COMPONENT16 0x81A5 michael@0: DEPTH_COMPONENT32_OES 0x81A7 michael@0: DEPTH24_STENCIL8_OES 0x88F0 michael@0: michael@0: Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) michael@0: michael@0: Update Section 2.10.5 "Shader Execution" in the subsection titled michael@0: "Texture Access" add a new paragraph before the last paragraph add michael@0: this line: michael@0: michael@0: "The stencil index texture internal component is ignored if the base michael@0: internal format is DEPTH_STENCIL_OES. michael@0: michael@0: If a vertex shader uses..." michael@0: michael@0: Additions to Chapter 3 of the OpenGL ES 2.0 specification (Rasterization) michael@0: michael@0: Add the following rows to Table 3.2 (page 62): michael@0: michael@0: type Parameter GL Data Type Special michael@0: ------------------------------------------------ michael@0: ... ... ... michael@0: UNSIGNED_SHORT ushort No michael@0: UNSIGNED_INT uint No michael@0: UNSIGNED_INT_24_8_OES uint Yes michael@0: michael@0: Add the following rows to Table 3.3 (page 62): michael@0: michael@0: Format Name Element Meaning and Order Target Buffer michael@0: ------------------------------------------------------------------ michael@0: ... ... ... michael@0: DEPTH_COMPONENT Depth Depth michael@0: DEPTH_STENCIL_OES Depth and Stencil Index Depth and Stencil michael@0: ... ... ... michael@0: michael@0: Add a row to Table 3.5 "Packed pixel formats" (page 64): michael@0: michael@0: type Parameter GL Type Components Pixel Formats michael@0: ------------------------------------------------------------------ michael@0: ... ... ... ... michael@0: UNSIGNED_INT_24_8_OES uint 2 DEPTH_STENCIL_OES michael@0: michael@0: Add a new table after Table 3.6 (page 64): michael@0: michael@0: UNSIGNED_INT_24_8_OES michael@0: michael@0: 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 michael@0: +----------------------------------+---------------+ michael@0: | 1st Component | 2nd Component | michael@0: +----------------------------------+---------------+ michael@0: michael@0: Table 3.6.B: UNSIGNED_INT formats michael@0: michael@0: Add a row to Table 3.7 "Packed pixel field assignments" (page 65): michael@0: michael@0: Format | 1st 2nd 3rd 4th michael@0: ------------------+------------------------------- michael@0: ... | ... ... ... ... michael@0: DEPTH_STENCIL_OES | depth stencil N/A N/A michael@0: michael@0: Add the following paragraph to the end of the section "Conversion to michael@0: floating-point" (page 65): michael@0: michael@0: "For groups of components that contain both standard components and index michael@0: elements, such as DEPTH_STENCIL_OES, the index elements are not converted." michael@0: michael@0: In section 3.7.1 "Texture Image Specification", update page 67 to michael@0: say: michael@0: michael@0: "The selected groups are processed as described in section 3.6.2, stopping michael@0: just before final conversion. Each R, G, B, A, or depth value so generated michael@0: is clamped to [0, 1], while the stencil index values are masked by 2^n-1, michael@0: where n is the number of stencil bits in the internal format resolution michael@0: (see below). michael@0: michael@0: Components are then selected from the resulting R, G, B, A, depth, or michael@0: stencil index values to obtain a texture with the base internal format michael@0: specified by . Table 3.8 summarizes the mapping of R, G, michael@0: B, A, depth, or stencil values to texture components, as a function of the michael@0: base internal format of the texture image. may be michael@0: specified as one of the internal format symbolic constants listed in michael@0: table 3.8. Specifying a value for that is not one of the michael@0: above values generates the error INVALID_VALUE. If does michael@0: not match , the error INVALID_OPERATION is generated. michael@0: michael@0: Textures with a base internal format of DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES are supported by texture image specification commands michael@0: only if is TEXTURE_2D. Using these formats in conjunction with michael@0: any other will result in an INVALID_OPERATION error. michael@0: michael@0: Textures with a base internal format of DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES only support one level of image data. Specifying a michael@0: non-zero value for will result in an INVALID_OPERATION error. michael@0: michael@0: Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES michael@0: require either depth component data or depth/stencil component data. michael@0: Textures with other base internal formats require RGBA component data. The michael@0: error INVALID_OPERATION is generated if the base internal format is michael@0: DEPTH_COMPONENT or DEPTH_STENCIL_OES and is not DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES and is DEPTH_COMPONENT or DEPTH_STENCIL_OES. michael@0: michael@0: Textures with a base internal format of DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES do not support loading image data via the TexImage michael@0: commands. They can only have their contents specified by rendering michael@0: to them. The INVALID_OPERATION error is generated by the TexImage2D michael@0: command if is not NULL for such textures." michael@0: michael@0: Add a row to table 3.8 (page 68), and update the title of the michael@0: second column: michael@0: michael@0: Base Internal Format RGBA, Depth and Stencil Values Internal Components michael@0: ------------------------------------------------------------------------- michael@0: ... ... ... michael@0: DEPTH_COMPONENT Depth D michael@0: DEPTH_STENCIL_OES Depth,Stencil D,S michael@0: ... ... ... michael@0: michael@0: Update the caption for table 3.8 (page 68) michael@0: michael@0: "Table 3.8: Conversion from RGBA, depth, and stencil pixel components to michael@0: internal texture components. Texture components R, G, B, A, and L are michael@0: converted back to RGBA colors during filtering as shown in table 3.12. michael@0: Texture components D are converted to RGBA colors as described in michael@0: section 3.7.8-1/2." michael@0: michael@0: Add the following to section 3.7.2 "Alternate Texture Image Specification michael@0: Commands": michael@0: michael@0: "CopyTexImage2D and CopyTexSubImage2D generate the INVALID_OPERATION michael@0: error if the base internal format of the destination texture is michael@0: DEPTH_COMPONENT or DEPTH_STENCIL_OES. michael@0: michael@0: TexSubImage2D generates the INVALID_OPERATION error if the base internal michael@0: format of the texture is DEPTH_COMPONENT or DEPTH_STENCIL_OES." michael@0: michael@0: Add a new section between sections 3.7.8 and 3.7.9: michael@0: michael@0: "3.7.8-1/2 Depth/Stencil Textures michael@0: michael@0: If the currently bound texture's base internal format is DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES, then the output of the texture unit is as described michael@0: below. Otherwise, the texture unit operates in the normal manner. michael@0: michael@0: Let be the depth texture value, provided by the shader's texture lookup michael@0: function. Then the effective texture value is computed as follows: michael@0: = michael@0: michael@0: If the texture image has a base internal format of DEPTH_STENCIL_OES, then michael@0: the stencil index texture component is ignored. The texture value does michael@0: not include a stencil index component, but includes only the depth michael@0: component. michael@0: michael@0: The resulting is assigned to . In some implementations, is michael@0: also assigned to , , or . Thus in table 3.12, textures with michael@0: depth component data behave as if their base internal format is RGBA, with michael@0: values in , , and being implementation dependent." michael@0: michael@0: Add the following to section 3.7.11 "Mipmap Generation": michael@0: michael@0: "If the level zero array contains depth or depth-stencil data, the michael@0: error INVALID_OPERATION is generated." michael@0: michael@0: Insert a new paragraph after the first paragraph of the "Texture Access" michael@0: subsection of section 3.8.2 on page 87, which says: michael@0: michael@0: "Texture lookups involving textures with depth component data generate michael@0: a texture source color by using depth data directly, as described in michael@0: section 3.7.8-1/2. The stencil texture internal component is ignored michael@0: if the base internal format is DEPTH_STENCIL_OES." michael@0: michael@0: Additions to Chapter 4 of the OpenGL ES 2.0 specification (Per-Fragment michael@0: Operations and the Framebuffer) michael@0: michael@0: In section 4.4.5 "Framebuffer Completeness", replace the the 3rd michael@0: paragraph with the following text: michael@0: michael@0: "* An internal format is color-renderable if it is one of the formats michael@0: from table 4.5 noted as color-renderable or if it is unsized format michael@0: RGBA or RGB. No other formats, including compressed internal formats, michael@0: are color-renderable. michael@0: michael@0: * An internal format is depth-renderable if it is one of the sized michael@0: internal formats from table 4.5 noted as depth-renderable, if it michael@0: is the unsized format DEPTH_COMPONENT or if it is the internal michael@0: format value of DEPTH24_STENCIL8_OES. No other formats are michael@0: depth-renderable. michael@0: michael@0: * An internal format is stencil-renderable if it is one of the sized michael@0: internal formats from table 4.5 noted as stencil-renderable or if it michael@0: is DEPTH24_STENCIL8_OES. No other formats are stencil-renderable." michael@0: michael@0: Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special michael@0: Functions) michael@0: michael@0: None. michael@0: michael@0: Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State michael@0: Requests) michael@0: michael@0: None. michael@0: michael@0: Interactions with OES_packed_depth_stencil michael@0: michael@0: If OES_packed_depth_stencil is not supported, mentions of michael@0: DEPTH_STENCIL_OES and UNSIGNED_INT_24_8_OES as a format/type combinations michael@0: for TexImage2D and TexSubImage2D are omitted. Mentions of michael@0: the internal format DEPTH24_STENCIL8_OES are also omitted. michael@0: michael@0: Interactions with EXT_texture_storage michael@0: michael@0: If EXT_texture_storage is supported the following internalformat michael@0: to format/type mappings are used: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: DEPTH_COMPONENT16 DEPTH_COMPONENT UNSIGNED_SHORT michael@0: DEPTH_COMPONENT32_OES DEPTH_COMPONENT UNSIGNED_INT michael@0: DEPTH24_STENCIL8_OES DEPTH_STENCIL_OES UNSIGNED_INT michael@0: michael@0: Textures with the above only support one level of michael@0: image data. Specifying a value other than one for the parameter michael@0: to TexStorage2DEXT will result in an INVALID_OPERATION error. michael@0: michael@0: If EXT_texture_storage is not supported, ignore any references michael@0: to TexStorage2DEXT. michael@0: michael@0: Errors michael@0: michael@0: The error INVALID_OPERATION is generated by TexImage2D if and michael@0: are DEPTH_COMPONENT and is not UNSIGNED_SHORT, michael@0: or UNSIGNED_INT. michael@0: michael@0: The error INVALID_OPERATION is generated by TexSubImage2D if is michael@0: DEPTH_COMPONENT and is not UNSIGNED_SHORT, or UNSIGNED_INT. michael@0: michael@0: The error INVALID_OPERATION is generated by TexImage2D if and michael@0: are not DEPTH_COMPONENT and is UNSIGNED_SHORT, michael@0: or UNSIGNED_INT. michael@0: michael@0: The error INVALID_OPERATION is generated by TexSubImage2D if is michael@0: not DEPTH_COMPONENT and is UNSIGNED_SHORT, or UNSIGNED_INT. michael@0: michael@0: The error INVALID_OPERATION is generated by TexImage2D if and michael@0: are DEPTH_STENCIL_OES and is not michael@0: UNSIGNED_INT_24_8_OES. michael@0: michael@0: The error INVALID_OPERATION is generated by TexSubImage2D if michael@0: is DEPTH_STENCIL_OES and is not UNSIGNED_INT_24_8_OES. michael@0: michael@0: The error INVALID_OPERATION is generated by TexImage2D if and michael@0: is not DEPTH_STENCIL_OES and is michael@0: UNSIGNED_INT_24_8_OES. michael@0: michael@0: The error INVALID_OPERATION is generated by TexSubImage2D if michael@0: is not DEPTH_STENCIL_OES and is UNSIGNED_INT_24_8_OES. michael@0: michael@0: The error INVALID_OPERATION is generated in the following situations: michael@0: - TexImage2D is called with and of michael@0: DEPTH_COMPONENT or DEPTH_STENCIL_OES and michael@0: - is not TEXTURE_2D, michael@0: - is not NULL, or michael@0: - is not zero. michael@0: - TexSubImage2D is called with of DEPTH_COMPONENT or michael@0: DEPTH_STENCIL_OES. michael@0: - TexStorage2DEXT is called with of DEPTH_COMPONENT16, michael@0: DEPTH_COMPONENT32_OES, or DEPTH24_STENCIL8_OES, and michael@0: - is not TEXTURE_2D, or michael@0: - is not one. michael@0: - CopyTexImage2D is called with an that has a base michael@0: internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES. michael@0: - CopyTexSubImage2D is called with a target texture that has a base michael@0: internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES. michael@0: - GenerateMipmap is called on a texture that has a base internal format michael@0: of DEPTH_COMPONENT or DEPTH_STENCIL_OES. michael@0: michael@0: New State michael@0: michael@0: None. michael@0: michael@0: Issues michael@0: michael@0: 1) What are the differences between this extension and OES_depth_texture michael@0: and OES_packed_depth_stencil? michael@0: michael@0: RESOLVED: This extension: michael@0: - does not support loading pre-baked depth stencil data via michael@0: TexImage2D or TexSubImage2D. michael@0: - allows variability in the y-, z-, and w-components of the sample michael@0: results from depth textures. michael@0: - only supports one level textures. michael@0: - explicitly lists the errors for unsupported functionality. michael@0: Since these were not clearly specified in the OES_depth_texture michael@0: extension there may be differences in error values between michael@0: implementations of OES_depth_texture and ANGLE_depth_texture. michael@0: This specification was also rebased to apply against the OpenGL ES 2.0 michael@0: specification instead of the OpenGL specification, making it more michael@0: obvious what all the functionality changes are. michael@0: michael@0: 2) Why does TexSubImage2D accept the new format/type combinations even michael@0: though it does not actually support loading data? michael@0: michael@0: RESOLVED: This was done to be more consistent with the OES_depth_texture michael@0: extension and to make it easier to add support for loading texture michael@0: data if it is possible to support in the future. michael@0: michael@0: 3) Why are only 1-level depth textures supported? michael@0: michael@0: RESOLVED: The only use for multiple levels of depth textures would michael@0: be for fitlered texturing. However since it is not possible to michael@0: render to non-zero-level texture levels in OpenGL ES 2.0, and since michael@0: this extension forbids loading existing data and GenerateMipmap on michael@0: depth textures, it is impossible to initialize or specify contents michael@0: for non-zero levels of depth textures. michael@0: michael@0: Revision History michael@0: michael@0: 02/25/2013 swoods revise to allow texture lookup to guarantee depth values michael@0: only in red channel of sample result. michael@0: 06/04/2012 dgkoch fix errors, disallow multi-level depth textures. michael@0: 05/30/2012 dgkoch minor updates and add issues. michael@0: 05/23/2012 dgkoch intial revision based on OES_depth_texture and michael@0: OES_packed_depth_stencil and rebased against the ES 2.0 spec michael@0: