1Name 2 3 OES_packed_depth_stencil 4 5Name Strings 6 7 GL_OES_packed_depth_stencil 8 9Contributors 10 11 Maurice Ribble 12 Contributors to EXT_packed_depth_stencil 13 14Contact 15 16 Benj Lipchak, Apple (lipchak 'at' apple.com) 17 18Notice 19 20 Copyright (c) 2007-2013 The Khronos Group Inc. Copyright terms at 21 http://www.khronos.org/registry/speccopyright.html 22 23Specification Update Policy 24 25 Khronos-approved extension specifications are updated in response to 26 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 27 extensions which have been promoted to a core Specification, fixes will 28 first appear in the latest version of that core Specification, and will 29 eventually be backported to the extension document. This policy is 30 described in more detail at 31 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 32 33Status 34 35 Ratified by the Khronos BOP, March 20, 2008. 36 37Version 38 39 Last Modified Date: September 17, 2009 40 Revision: #3 41 42Number 43 44 OpenGL ES Extension #43 45 46Dependencies 47 48 OpenGL ES 1.0 is required. 49 50 OES_framebuffer_object or OpenGL ES 2.0 is required. 51 52 Written based on the wording of the OpenGL 2.0 specification. 53 54 OES_depth_texture affects the definition of this extension. 55 56Overview 57 58 Many OpenGL implementations have chosen to interleave the depth and stencil 59 buffers into one buffer, often with 24 bits of depth precision and 8 bits of 60 stencil data. 32 bits is more than is needed for the depth buffer much of 61 the time; a 24-bit depth buffer, on the other hand, requires that reads and 62 writes of depth data be unaligned with respect to power-of-two boundaries. 63 On the other hand, 8 bits of stencil data is more than sufficient for most 64 applications, so it is only natural to pack the two buffers into a single 65 buffer with both depth and stencil data. OpenGL never provides direct 66 access to the buffers, so the OpenGL implementation can provide an interface 67 to applications where it appears the one merged buffer is composed of two 68 logical buffers. 69 70 One disadvantage of this scheme is that OpenGL lacks any means by which this 71 packed data can be handled efficiently. For example, when an application 72 reads from the 24-bit depth buffer, using the type GL_UNSIGNED_SHORT will 73 lose 8 bits of data, while GL_UNSIGNED_INT has 8 too many. Both require 74 expensive format conversion operations. A 24-bit format would be no more 75 suitable, because it would also suffer from the unaligned memory accesses 76 that made the standalone 24-bit depth buffer an unattractive proposition in 77 the first place. 78 79 If OES_depth_texture is supported, a new data format, GL_DEPTH_STENCIL_OES, 80 as well as a packed data type, UNSIGNED_INT_24_8_OES, together can be used 81 with glTex[Sub]Image2D. This provides an efficient way to supply data for a 82 24-bit depth texture. When a texture with DEPTH_STENCIL_OES data is bound 83 for texturing, only the depth component is accessible through the texture 84 fetcher. 85 86 This extension also provides a new sized internal format, 87 DEPTH24_STENCIL8_OES, which can be used for renderbuffer storage. When a 88 renderbuffer or texture image with a DEPTH_STENCIL_OES base internal format 89 is attached to both the depth and stencil attachment points of a framebuffer 90 object, then it becomes both the depth and stencil buffers of the 91 framebuffer. This fits nicely with hardware that interleaves both depth and 92 stencil data into a single buffer. 93 94New Procedures and Functions 95 96 None. 97 98New Tokens 99 100 Accepted by the <format> parameter of TexImage2D and TexSubImage2D and by the 101 <internalformat> parameter of TexImage2D: 102 103 DEPTH_STENCIL_OES 0x84F9 104 105 Accepted by the <type> parameter of TexImage2D and TexSubImage2D: 106 107 UNSIGNED_INT_24_8_OES 0x84FA 108 109 Accepted by the <internalformat> parameter of RenderbufferStorage, and 110 returned in the <params> parameter of GetRenderbufferParameteriv when 111 <pname> is RENDERBUFFER_INTERNAL_FORMAT: 112 113 DEPTH24_STENCIL8_OES 0x88F0 114 115Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) 116 117 Update section 2.15.4, after the bullet list on page 86, to add this line: 118 119 "The stencil index texture internal component is ignored if the base 120 internal format is DEPTH_STENCIL_OES. 121 122 If a vertex shader uses..." 123 124Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 125 126 Add a row to Table 3.5 (page 128): 127 128 type Parameter GL Type Special 129 ------------------------------------------------ 130 ... ... ... 131 UNSIGNED_INT_24_8_OES uint Yes 132 133 Add a row to Table 3.6 (page 129): 134 135 Format Name Element Meaning and Order Target Buffer 136 ------------------------------------------------------------------ 137 ... ... ... 138 DEPTH_COMPONENT Depth Depth 139 DEPTH_STENCIL_OES Depth and Stencil Index Depth and Stencil 140 ... ... ... 141 142 Add a row to Table 3.8 (page 132): 143 144 type Parameter GL Type Components Pixel Formats 145 ------------------------------------------------------------------ 146 ... ... ... ... 147 UNSIGNED_INT_24_8_OES uint 2 DEPTH_STENCIL_OES 148 149 Add the following diagram to Table 3.11 (page 134): 150 151 UNSIGNED_INT_24_8_OES 152 153 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 154 +----------------------------------+---------------+ 155 | 1st Component | 2nd Component | 156 +----------------------------------+---------------+ 157 158 Add a row to Table 3.12 (page 135): 159 160 Format | 1st 2nd 3rd 4th 161 ------------------+------------------------------- 162 ... | ... ... ... ... 163 DEPTH_STENCIL_OES | depth stencil N/A N/A 164 165 Add the following paragraph to the end of the section "Conversion to 166 floating-point" (page 135-136): 167 168 "For groups of components that contain both standard components and index 169 elements, such as DEPTH_STENCIL_OES, the index elements are not converted." 170 171 In section 3.8.1 "Texture Image Specification", update page 151 to 172 say: 173 174 "The selected groups are processed exactly as for DrawPixels, stopping just 175 before final conversion. Each R, G, B, A, or depth value so generated is 176 clamped to [0, 1], while the stencil index values are masked by 2^n-1, where 177 n is the number of stencil bits in the internal format resolution (see 178 below). 179 180 Components are then selected from the resulting R, G, B, A, depth, or 181 stencil index values to obtain a texture with the base internal format 182 specified by <internalformat>. Table 3.15 summarizes the mapping of R, G, 183 B, A, depth, or stencil values to texture components, as a function of the 184 base internal format of the texture image. <internalformat> may be 185 specified as one of the eight internal format symbolic constants listed in 186 table 3.15, as one of ... 187 188 Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES 189 are supported by texture image specification commands only if <target> is 190 TEXTURE_2D. Using this format in conjunction with any other <target> will 191 result in an INVALID_OPERATION error. 192 193 Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES 194 require either depth component data or depth/stencil component data. 195 Textures with other base internal formats require RGBA component data. The 196 error INVALID_OPERATION is generated if the base internal format is 197 DEPTH_COMPONENT or DEPTH_STENCIL_OES and <format> is not DEPTH_COMPONENT or 198 DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or 199 DEPTH_STENCIL_OES and <format> is DEPTH_COMPONENT or DEPTH_STENCIL_OES." 200 201 Add a row to table 3.15 (page 153), and update the title of the 202 second column: 203 204 Base Internal Format RGBA, Depth and Stencil Values Internal Components 205 ------------------------------------------------------------------------- 206 ... ... ... 207 DEPTH_STENCIL_OES Depth,Stencil D,S 208 ... ... ... 209 210 Update the caption for table 3.15 (page 153) 211 212 "Table 3.15: Conversion from RGBA, depth, and stencil pixel components to 213 internal texture components. See section 3.8.13 for a description of the 214 texture components R, G, B, A, L, I, D, and S." 215 216 Add a new section between sections 3.8.9 and 3.8.10, after the first 217 paragraph on page 177: 218 219 "3.8.9-1/2 Depth/Stencil Textures 220 221 If the texture image has a base internal format of DEPTH_STENCIL_OES, then 222 the stencil index texture component is ignored. The texture value Tau does 223 not include a stencil index component, but includes only the depth 224 component." 225 226 Update the first paragraph of section 3.8.15 "Texture Application", 227 on page 189, to say: 228 229 "...Otherwise, a texture value is found according to the parameter 230 values of the currently bound texture image of the appropriate 231 dimensionality using the rules given in sections 3.8.6 through 232 3.8.9. Note that the texture value may contain R, G, B, A, L, I, or 233 D components, but it does not contain an S component. If the 234 texture's base internal format is DEPTH_STENCIL_OES, for the 235 purposes of texture application, it is as if the base internal 236 format was DEPTH..." 237 238 Update section 3.11.2, after the bullet list on page 195, to add this line: 239 240 "The stencil index texture internal component is ignored if the base 241 internal format is DEPTH_STENCIL_OES. 242 243 If a fragment shader uses..." 244 245Additions to Chapter 4 of the OpenGL ES 2.0 Specification 246 247 In section 4.4.5 "Framebuffer Completeness", modify the definition of 248 "depth-renderable" and "stencil-renderable" to say: 249 250 "* An internal format is depth-renderable if it is one of the sized 251 internal formats that has a depth-renderable internal format value of 252 DEPTH_COMPONENT16 or DEPTH24_STENCIL8_OES. No other formats are depth- 253 renderable. 254 255 * An internal format is stencil-renderable if it is one of the sized 256 internal formats that has a stencil-renderable internal format value 257 of STENCIL_INDEX8 or DEPTH24_STENCIL8_OES. No other formats are 258 stencil-renderable." 259 260Additions to Chapter 5 of the OpenGL 2.0 Specification (Special 261Functions) 262 263 None. 264 265Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 266Requests) 267 268 None. 269 270GLX Protocol 271 272 None. 273 274Interactions with OES_depth_texture 275 276 If OES_depth_texture is not available, mentions of DEPTH_STENCIL_OES and 277 UNSIGNED_INT_24_8_OES as format/type combinations accepted by TexImage2D and 278 TexSubImage2D are omitted. 279 280Errors 281 282 The error INVALID_ENUM is generated if RenderbufferStorage is called with an 283 <internalformat> that is not RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, 284 DEPTH_STENCIL_OES, or one of the internal formats from table 3.16 or table 285 2.nnn that has a base internal format of RGB, RGBA, DEPTH_COMPONENT, 286 STENCIL_INDEX, or DEPTH_STENCIL_OES." 287 288New State 289 290 None. 291 292Usage Example 293 294 (1) Attach a DEPTH_STENCIL_OES texture image to an FBO as both the depth and 295 stencil buffers. 296 297 glGenFramebuffers(1, &fb); 298 glGenTextures(1, &tex_color); 299 glGenTextures(1, &tex_depthstencil); 300 301 glBindFramebuffer(GL_FRAMEBUFFER, fb); 302 303 // Setup color texture (mipmap) 304 glBindTexture(GL_TEXTURE_2D, tex_color); 305 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 306 512, 512, 0, GL_RGBA, GL_UNSIGNED_BYTE, NULL); 307 glGenerateMipmap(GL_TEXTURE_2D); 308 glFramebufferTexture2D(GL_FRAMEBUFFER, 309 GL_COLOR_ATTACHMENT0, 310 GL_TEXTURE_2D, tex_color, 0); 311 312 // Setup depth_stencil texture (not mipmap) 313 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 314 glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 315 glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH_STENCIL_OES, 316 512, 512, 0, GL_DEPTH_STENCIL_OES, 317 GL_UNSIGNED_INT_24_8_OES, NULL); 318 glFramebufferTexture2D(GL_FRAMEBUFFER, 319 GL_DEPTH_ATTACHMENT, 320 GL_TEXTURE_2D, tex_depthstencil, 0); 321 glFramebufferTexture2D(GL_FRAMEBUFFER, 322 GL_STENCIL_ATTACHMENT, 323 GL_TEXTURE_2D, tex_depthstencil, 0); 324 325 // Check framebuffer completeness at the end of initialization. 326 327 loop { 328 glBindTexture(GL_TEXTURE_2D, 0); 329 glBindFramebuffer(GL_FRAMEBUFFER, fb); 330 <render to color, depth, and stencil textures> 331 glBindFramebuffer(GL_FRAMEBUFFER, 0); 332 333 glBindTexture(GL_TEXTURE_2D, tex_color); 334 glGenerateMipmap(GL_TEXTURE_2D); 335 <draw to the window, reading from the color texture> 336 337 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 338 <draw to the window, reading depth from the depthstencil texture> 339 } 340 341Issues 342 343 1) What are the differences between this extension and 344 EXT_packed_depth_stencil? 345 346 RESOLVED: The following are the only differences: 347 348 * No support for 1D or 3D textures 349 * No support for proxy targets 350 * Sized internal format only used for RenderbufferStorage 351 * Format and internal format must match for TexImage2D 352 * No support for DrawPixels, ReadPixels, CopyPixels, 353 CopyTexImage2D, or CopyTexSubImage2D 354 * No support for GetTexLevelParameter, so no TEXTURE_STENCIL_SIZE_EXT 355 * No support for GetTexImage 356 357Revision History 358 359 #03 09/17/2009 Jon Leech Add glCopyTexSubImage2D to 360 exclusions from OpenGL in 361 issue 1 (bug 5335). 362 #02 01/20/2009 Benj Lipchak Make the OES_depth_texture interactions 363 more explicit. 364 #01 10/02/2007 Benj Lipchak Start with EXT_packed_depth_stencil, 365 rename OES and remove non-ES stuff. 366