1 Name 2 3 ANGLE_depth_texture 4 5 Name Strings 6 7 GL_ANGLE_depth_texture 8 9 Contributors 10 11 Nicolas Capens, TransGaming 12 Daniel Koch, TransGaming 13 Shannon Woods, TransGaming 14 Kenneth Russell, Google 15 Vangelis Kokkevis, Google 16 Gregg Tavares, Google 17 Contributors to OES_depth_texture 18 Contributors to OES_packed_depth_stencil 19 20 Contact 21 22 Shannon Woods, TransGaming (shannon 'dot' woods 'at' transgaming.com) 23 24 Status 25 26 Implemented in ANGLE. 27 28 Version 29 30 Last Modified Date: February 25, 2013 31 Revision: #4 32 33 Number 34 35 TBD 36 37 Dependencies 38 39 OpenGL ES 2.0 is required. 40 This extension is written against the OpenGL ES 2.0.25 specification 41 42 OES_packed_depth_stencil affects the definition of this extension. 43 44 EXT_texture_storage affects the definition of this extension. 45 46 Overview 47 48 This extension defines support for 2D depth and depth-stencil 49 textures in an OpenGL ES implementation. 50 51 This extension incorporates the depth texturing functionality of 52 OES_depth_texture and OES_packed_depth_stencil, but does not 53 provide the ability to load existing data via TexImage2D or 54 TexSubImage2D. This extension also allows implementation 55 variability in which components from a sampled depth texture 56 contain the depth data. Depth textures created with this 57 extension only support 1 level. 58 59 New Procedures and Functions 60 61 None 62 63 New Tokens 64 65 Accepted by the <format> parameter of TexImage2D and TexSubImage2D and 66 <internalformat> parameter of TexImage2D: 67 68 DEPTH_COMPONENT 0x1902 69 DEPTH_STENCIL_OES 0x84F9 70 71 Accepted by the <type> parameter of TexImage2D, TexSubImage2D: 72 73 UNSIGNED_SHORT 0x1403 74 UNSIGNED_INT 0x1405 75 UNSIGNED_INT_24_8_OES 0x84FA 76 77 Accepted by the <internalformat> parameter of TexStorage2DEXT: 78 79 DEPTH_COMPONENT16 0x81A5 80 DEPTH_COMPONENT32_OES 0x81A7 81 DEPTH24_STENCIL8_OES 0x88F0 82 83 Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) 84 85 Update Section 2.10.5 "Shader Execution" in the subsection titled 86 "Texture Access" add a new paragraph before the last paragraph add 87 this line: 88 89 "The stencil index texture internal component is ignored if the base 90 internal format is DEPTH_STENCIL_OES. 91 92 If a vertex shader uses..." 93 94 Additions to Chapter 3 of the OpenGL ES 2.0 specification (Rasterization) 95 96 Add the following rows to Table 3.2 (page 62): 97 98 type Parameter GL Data Type Special 99 ------------------------------------------------ 100 ... ... ... 101 UNSIGNED_SHORT ushort No 102 UNSIGNED_INT uint No 103 UNSIGNED_INT_24_8_OES uint Yes 104 105 Add the following rows to Table 3.3 (page 62): 106 107 Format Name Element Meaning and Order Target Buffer 108 ------------------------------------------------------------------ 109 ... ... ... 110 DEPTH_COMPONENT Depth Depth 111 DEPTH_STENCIL_OES Depth and Stencil Index Depth and Stencil 112 ... ... ... 113 114 Add a row to Table 3.5 "Packed pixel formats" (page 64): 115 116 type Parameter GL Type Components Pixel Formats 117 ------------------------------------------------------------------ 118 ... ... ... ... 119 UNSIGNED_INT_24_8_OES uint 2 DEPTH_STENCIL_OES 120 121 Add a new table after Table 3.6 (page 64): 122 123 UNSIGNED_INT_24_8_OES 124 125 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 126 +----------------------------------+---------------+ 127 | 1st Component | 2nd Component | 128 +----------------------------------+---------------+ 129 130 Table 3.6.B: UNSIGNED_INT formats 131 132 Add a row to Table 3.7 "Packed pixel field assignments" (page 65): 133 134 Format | 1st 2nd 3rd 4th 135 ------------------+------------------------------- 136 ... | ... ... ... ... 137 DEPTH_STENCIL_OES | depth stencil N/A N/A 138 139 Add the following paragraph to the end of the section "Conversion to 140 floating-point" (page 65): 141 142 "For groups of components that contain both standard components and index 143 elements, such as DEPTH_STENCIL_OES, the index elements are not converted." 144 145 In section 3.7.1 "Texture Image Specification", update page 67 to 146 say: 147 148 "The selected groups are processed as described in section 3.6.2, stopping 149 just before final conversion. Each R, G, B, A, or depth value so generated 150 is clamped to [0, 1], while the stencil index values are masked by 2^n-1, 151 where n is the number of stencil bits in the internal format resolution 152 (see below). 153 154 Components are then selected from the resulting R, G, B, A, depth, or 155 stencil index values to obtain a texture with the base internal format 156 specified by <internalformat>. Table 3.8 summarizes the mapping of R, G, 157 B, A, depth, or stencil values to texture components, as a function of the 158 base internal format of the texture image. <internalformat> may be 159 specified as one of the internal format symbolic constants listed in 160 table 3.8. Specifying a value for <internalformat> that is not one of the 161 above values generates the error INVALID_VALUE. If <internalformat> does 162 not match <format>, the error INVALID_OPERATION is generated. 163 164 Textures with a base internal format of DEPTH_COMPONENT or 165 DEPTH_STENCIL_OES are supported by texture image specification commands 166 only if <target> is TEXTURE_2D. Using these formats in conjunction with 167 any other <target> will result in an INVALID_OPERATION error. 168 169 Textures with a base internal format of DEPTH_COMPONENT or 170 DEPTH_STENCIL_OES only support one level of image data. Specifying a 171 non-zero value for <level> will result in an INVALID_OPERATION error. 172 173 Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES 174 require either depth component data or depth/stencil component data. 175 Textures with other base internal formats require RGBA component data. The 176 error INVALID_OPERATION is generated if the base internal format is 177 DEPTH_COMPONENT or DEPTH_STENCIL_OES and <format> is not DEPTH_COMPONENT or 178 DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or 179 DEPTH_STENCIL_OES and <format> is DEPTH_COMPONENT or DEPTH_STENCIL_OES. 180 181 Textures with a base internal format of DEPTH_COMPONENT or 182 DEPTH_STENCIL_OES do not support loading image data via the TexImage 183 commands. They can only have their contents specified by rendering 184 to them. The INVALID_OPERATION error is generated by the TexImage2D 185 command if <data> is not NULL for such textures." 186 187 Add a row to table 3.8 (page 68), and update the title of the 188 second column: 189 190 Base Internal Format RGBA, Depth and Stencil Values Internal Components 191 ------------------------------------------------------------------------- 192 ... ... ... 193 DEPTH_COMPONENT Depth D 194 DEPTH_STENCIL_OES Depth,Stencil D,S 195 ... ... ... 196 197 Update the caption for table 3.8 (page 68) 198 199 "Table 3.8: Conversion from RGBA, depth, and stencil pixel components to 200 internal texture components. Texture components R, G, B, A, and L are 201 converted back to RGBA colors during filtering as shown in table 3.12. 202 Texture components D are converted to RGBA colors as described in 203 section 3.7.8-1/2." 204 205 Add the following to section 3.7.2 "Alternate Texture Image Specification 206 Commands": 207 208 "CopyTexImage2D and CopyTexSubImage2D generate the INVALID_OPERATION 209 error if the base internal format of the destination texture is 210 DEPTH_COMPONENT or DEPTH_STENCIL_OES. 211 212 TexSubImage2D generates the INVALID_OPERATION error if the base internal 213 format of the texture is DEPTH_COMPONENT or DEPTH_STENCIL_OES." 214 215 Add a new section between sections 3.7.8 and 3.7.9: 216 217 "3.7.8-1/2 Depth/Stencil Textures 218 219 If the currently bound texture's base internal format is DEPTH_COMPONENT or 220 DEPTH_STENCIL_OES, then the output of the texture unit is as described 221 below. Otherwise, the texture unit operates in the normal manner. 222 223 Let <D_t> be the depth texture value, provided by the shader's texture lookup 224 function. Then the effective texture value is computed as follows: 225 <Tau> = <D_t> 226 227 If the texture image has a base internal format of DEPTH_STENCIL_OES, then 228 the stencil index texture component is ignored. The texture value <Tau> does 229 not include a stencil index component, but includes only the depth 230 component. 231 232 The resulting <Tau> is assigned to <R_t>. In some implementations, <Tau> is 233 also assigned to <G_t>, <B_t>, or <A_t>. Thus in table 3.12, textures with 234 depth component data behave as if their base internal format is RGBA, with 235 values in <G_t>, <B_t>, and <A_t> being implementation dependent." 236 237 Add the following to section 3.7.11 "Mipmap Generation": 238 239 "If the level zero array contains depth or depth-stencil data, the 240 error INVALID_OPERATION is generated." 241 242 Insert a new paragraph after the first paragraph of the "Texture Access" 243 subsection of section 3.8.2 on page 87, which says: 244 245 "Texture lookups involving textures with depth component data generate 246 a texture source color by using depth data directly, as described in 247 section 3.7.8-1/2. The stencil texture internal component is ignored 248 if the base internal format is DEPTH_STENCIL_OES." 249 250 Additions to Chapter 4 of the OpenGL ES 2.0 specification (Per-Fragment 251 Operations and the Framebuffer) 252 253 In section 4.4.5 "Framebuffer Completeness", replace the the 3rd 254 paragraph with the following text: 255 256 "* An internal format is color-renderable if it is one of the formats 257 from table 4.5 noted as color-renderable or if it is unsized format 258 RGBA or RGB. No other formats, including compressed internal formats, 259 are color-renderable. 260 261 * An internal format is depth-renderable if it is one of the sized 262 internal formats from table 4.5 noted as depth-renderable, if it 263 is the unsized format DEPTH_COMPONENT or if it is the internal 264 format value of DEPTH24_STENCIL8_OES. No other formats are 265 depth-renderable. 266 267 * An internal format is stencil-renderable if it is one of the sized 268 internal formats from table 4.5 noted as stencil-renderable or if it 269 is DEPTH24_STENCIL8_OES. No other formats are stencil-renderable." 270 271 Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special 272 Functions) 273 274 None. 275 276 Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State 277 Requests) 278 279 None. 280 281 Interactions with OES_packed_depth_stencil 282 283 If OES_packed_depth_stencil is not supported, mentions of 284 DEPTH_STENCIL_OES and UNSIGNED_INT_24_8_OES as a format/type combinations 285 for TexImage2D and TexSubImage2D are omitted. Mentions of 286 the internal format DEPTH24_STENCIL8_OES are also omitted. 287 288 Interactions with EXT_texture_storage 289 290 If EXT_texture_storage is supported the following internalformat 291 to format/type mappings are used: 292 293 <internalformat> <format> <type> 294 ---------------- -------- ------ 295 DEPTH_COMPONENT16 DEPTH_COMPONENT UNSIGNED_SHORT 296 DEPTH_COMPONENT32_OES DEPTH_COMPONENT UNSIGNED_INT 297 DEPTH24_STENCIL8_OES DEPTH_STENCIL_OES UNSIGNED_INT 298 299 Textures with the above <internalformats> only support one level of 300 image data. Specifying a value other than one for the <levels> parameter 301 to TexStorage2DEXT will result in an INVALID_OPERATION error. 302 303 If EXT_texture_storage is not supported, ignore any references 304 to TexStorage2DEXT. 305 306 Errors 307 308 The error INVALID_OPERATION is generated by TexImage2D if <format> and 309 <internalformat> are DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT, 310 or UNSIGNED_INT. 311 312 The error INVALID_OPERATION is generated by TexSubImage2D if <format> is 313 DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT, or UNSIGNED_INT. 314 315 The error INVALID_OPERATION is generated by TexImage2D if <format> and 316 <internalformat> are not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT, 317 or UNSIGNED_INT. 318 319 The error INVALID_OPERATION is generated by TexSubImage2D if <format> is 320 not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT, or UNSIGNED_INT. 321 322 The error INVALID_OPERATION is generated by TexImage2D if <format> and 323 <internalformat> are DEPTH_STENCIL_OES and <type> is not 324 UNSIGNED_INT_24_8_OES. 325 326 The error INVALID_OPERATION is generated by TexSubImage2D if <format> 327 is DEPTH_STENCIL_OES and <type> is not UNSIGNED_INT_24_8_OES. 328 329 The error INVALID_OPERATION is generated by TexImage2D if <format> and 330 <internalformat> is not DEPTH_STENCIL_OES and <type> is 331 UNSIGNED_INT_24_8_OES. 332 333 The error INVALID_OPERATION is generated by TexSubImage2D if <format> 334 is not DEPTH_STENCIL_OES and <type> is UNSIGNED_INT_24_8_OES. 335 336 The error INVALID_OPERATION is generated in the following situations: 337 - TexImage2D is called with <format> and <internalformat> of 338 DEPTH_COMPONENT or DEPTH_STENCIL_OES and 339 - <target> is not TEXTURE_2D, 340 - <data> is not NULL, or 341 - <level> is not zero. 342 - TexSubImage2D is called with <format> of DEPTH_COMPONENT or 343 DEPTH_STENCIL_OES. 344 - TexStorage2DEXT is called with <internalformat> of DEPTH_COMPONENT16, 345 DEPTH_COMPONENT32_OES, or DEPTH24_STENCIL8_OES, and 346 - <target> is not TEXTURE_2D, or 347 - <levels> is not one. 348 - CopyTexImage2D is called with an <internalformat> that has a base 349 internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES. 350 - CopyTexSubImage2D is called with a target texture that has a base 351 internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES. 352 - GenerateMipmap is called on a texture that has a base internal format 353 of DEPTH_COMPONENT or DEPTH_STENCIL_OES. 354 355 New State 356 357 None. 358 359 Issues 360 361 1) What are the differences between this extension and OES_depth_texture 362 and OES_packed_depth_stencil? 363 364 RESOLVED: This extension: 365 - does not support loading pre-baked depth stencil data via 366 TexImage2D or TexSubImage2D. 367 - allows variability in the y-, z-, and w-components of the sample 368 results from depth textures. 369 - only supports one level textures. 370 - explicitly lists the errors for unsupported functionality. 371 Since these were not clearly specified in the OES_depth_texture 372 extension there may be differences in error values between 373 implementations of OES_depth_texture and ANGLE_depth_texture. 374 This specification was also rebased to apply against the OpenGL ES 2.0 375 specification instead of the OpenGL specification, making it more 376 obvious what all the functionality changes are. 377 378 2) Why does TexSubImage2D accept the new format/type combinations even 379 though it does not actually support loading data? 380 381 RESOLVED: This was done to be more consistent with the OES_depth_texture 382 extension and to make it easier to add support for loading texture 383 data if it is possible to support in the future. 384 385 3) Why are only 1-level depth textures supported? 386 387 RESOLVED: The only use for multiple levels of depth textures would 388 be for fitlered texturing. However since it is not possible to 389 render to non-zero-level texture levels in OpenGL ES 2.0, and since 390 this extension forbids loading existing data and GenerateMipmap on 391 depth textures, it is impossible to initialize or specify contents 392 for non-zero levels of depth textures. 393 394 Revision History 395 396 02/25/2013 swoods revise to allow texture lookup to guarantee depth values 397 only in red channel of sample result. 398 06/04/2012 dgkoch fix errors, disallow multi-level depth textures. 399 05/30/2012 dgkoch minor updates and add issues. 400 05/23/2012 dgkoch intial revision based on OES_depth_texture and 401 OES_packed_depth_stencil and rebased against the ES 2.0 spec 402 403
