1Name 2 3 EXT_packed_depth_stencil 4 5Name Strings 6 7 GL_EXT_packed_depth_stencil 8 9Contributors 10 11 Pat Brown 12 Matt Craighead 13 Cass Everitt 14 Michael Gold 15 Evan Hart 16 Jeff Juliano 17 John Kessenich 18 Mark Kilgard 19 Jon Leech 20 Bill Licea-Kane 21 Barthold Lichtenbelt 22 Kent Lin 23 Brian Paul 24 Ian Romanick 25 John Rosasco 26 Jeremy Sandmel 27 28Contact 29 30 Jeff Juliano, NVIDIA Corporation (jjuliano 'at' nvidia.com) 31 32Status 33 34 Incomplete 35 36Version 37 38 Last Modified Date: September 26, 2005 39 Revision: #12 40 41Number 42 43 312 44 45Dependencies 46 47 OpenGL 1.1 and EXT_framebuffer_object are required. 48 49 Written based on the wording of the OpenGL 2.0 specification. 50 51 Written based on the wording of EXT_framebuffer_object version 117. 52 53 This extension interacts with EXT_framebuffer_object. 54 55 This extension modifies NV_packed_depth_stencil. 56 57 ARB_depth_texture affects the definition of this extension. 58 59 SGIX_depth_texture affects the definition of this extension. 60 61Overview 62 63 Many OpenGL implementations have chosen to interleave the depth and 64 stencil buffers into one buffer, often with 24 bits of depth 65 precision and 8 bits of stencil data. 32 bits is more than is 66 needed for the depth buffer much of the time; a 24-bit depth buffer, 67 on the other hand, requires that reads and writes of depth data be 68 unaligned with respect to power-of-two boundaries. On the other 69 hand, 8 bits of stencil data is more than sufficient for most 70 applications, so it is only natural to pack the two buffers into a 71 single buffer with both depth and stencil data. OpenGL never 72 provides direct access to the buffers, so the OpenGL implementation 73 can provide an interface to applications where it appears the one 74 merged buffer is composed of two logical buffers. 75 76 One disadvantage of this scheme is that OpenGL lacks any means by 77 which this packed data can be handled efficiently. For example, 78 when an application reads from the 24-bit depth buffer, using the 79 type GL_UNSIGNED_SHORT will lose 8 bits of data, while 80 GL_UNSIGNED_INT has 8 too many. Both require expensive format 81 conversion operations. A 24-bit format would be no more suitable, 82 because it would also suffer from the unaligned memory accesses that 83 made the standalone 24-bit depth buffer an unattractive proposition 84 in the first place. 85 86 Many applications, such as parallel rendering applications, may also 87 wish to draw to or read back from both the depth and stencil buffers 88 at the same time. Currently this requires two separate operations, 89 reducing performance. Since the buffers are interleaved, drawing to 90 or reading from both should be no more expensive than using just 91 one; in some cases, it may even be cheaper. 92 93 This extension provides a new data format, GL_DEPTH_STENCIL_EXT, 94 that can be used with the glDrawPixels, glReadPixels, and 95 glCopyPixels commands, as well as a packed data type, 96 GL_UNSIGNED_INT_24_8_EXT, that is meant to be used with 97 GL_DEPTH_STENCIL_EXT. No other data types are supported with 98 GL_DEPTH_STENCIL_EXT. If ARB_depth_texture or SGIX_depth_texture is 99 supported, GL_DEPTH_STENCIL_EXT/GL_UNSIGNED_INT_24_8_EXT data can 100 also be used for textures; this provides a more efficient way to 101 supply data for a 24-bit depth texture. 102 103 GL_DEPTH_STENCIL_EXT data, when passed through the pixel path, 104 undergoes both depth and stencil operations. The depth data is 105 scaled and biased by the current GL_DEPTH_SCALE and GL_DEPTH_BIAS, 106 while the stencil data is shifted and offset by the current 107 GL_INDEX_SHIFT and GL_INDEX_OFFSET. The stencil data is also put 108 through the stencil-to-stencil pixel map. 109 110 glDrawPixels of GL_DEPTH_STENCIL_EXT data operates similarly to that 111 of GL_STENCIL_INDEX data, bypassing the OpenGL fragment pipeline 112 entirely, unlike the treatment of GL_DEPTH_COMPONENT data. The 113 stencil and depth masks are applied, as are the pixel ownership and 114 scissor tests, but all other operations are skipped. 115 116 glReadPixels of GL_DEPTH_STENCIL_EXT data reads back a rectangle 117 from both the depth and stencil buffers. 118 119 glCopyPixels of GL_DEPTH_STENCIL_EXT data copies a rectangle from 120 both the depth and stencil buffers. Like glDrawPixels, it applies 121 both the stencil and depth masks but skips the remainder of the 122 OpenGL fragment pipeline. 123 124 glTex[Sub]Image[1,2,3]D of GL_DEPTH_STENCIL_EXT data loads depth and 125 stencil data into a depth_stencil texture. glGetTexImage of 126 GL_DEPTH_STENCIL_EXT data can be used to retrieve depth and stencil 127 data from a depth/stencil texture. 128 129 In addition, a new base internal format, GL_DEPTH_STENCIL_EXT, can 130 be used by both texture images and renderbuffer storage. When an 131 image with a DEPTH_STENCIL_EXT internal format is attached to both 132 the depth and stencil attachment points of a framebuffer object (see 133 EXT_framebuffer_object), then it becomes both the depth and stencil 134 buffers of the framebuffer. This fits nicely with hardware that 135 interleaves both depth and stencil data into a single buffer. When 136 a texture with DEPTH_STENCIL_EXT data is bound for texturing, only 137 the depth component is accessible through the texture fetcher. The 138 stencil data can be written with TexImage or CopyTexImage, and can 139 be read with GetTexImage. When a DEPTH_STENCIL_EXT image is 140 attached to the stencil attachment of the bound framebuffer object, 141 the stencil data can be accessed through any operation that reads 142 from or writes to the framebuffer's stencil buffer. 143 144New Procedures and Functions 145 146 None. 147 148New Tokens 149 150 Accepted by the <format> parameter of DrawPixels, ReadPixels, 151 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 152 TexSubImage3D, and GetTexImage, by the <type> parameter of 153 CopyPixels, by the <internalformat> parameter of TexImage1D, 154 TexImage2D, TexImage3D, CopyTexImage1D, CopyTexImage2D, and 155 RenderbufferStorageEXT, and returned in the <data> parameter of 156 GetTexLevelParameter and GetRenderbufferParameterivEXT: 157 158 DEPTH_STENCIL_EXT 0x84F9 159 160 Accepted by the <type> parameter of DrawPixels, ReadPixels, 161 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 162 TexSubImage3D, and GetTexImage: 163 164 UNSIGNED_INT_24_8_EXT 0x84FA 165 166 Accepted by the <internalformat> parameter of TexImage1D, 167 TexImage2D, TexImage3D, CopyTexImage1D, CopyTexImage2D, and 168 RenderbufferStorageEXT, and returned in the <data> parameter of 169 GetTexLevelParameter and GetRenderbufferParameterivEXT: 170 171 DEPTH24_STENCIL8_EXT 0x88F0 172 173 Accepted by the <value> parameter of GetTexLevelParameter: 174 175 TEXTURE_STENCIL_SIZE_EXT 0x88F1 176 177Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL 178Operation) 179 180 Starting with the bullet list on page 86, update section 2.15.4 181 "Shader Execution" to say: 182 183 "* The sampler used in a texture lookup function is of type 184 sampler1D or sampler2D, and the texture object's base internal 185 format is DEPTH_COMPONENT or DEPTH_STENCIL_EXT, and the 186 TEXTURE_COMPARE_MODE is not NONE. 187 188 * The sampler used in a texture lookup function is of type 189 sampler1DShadow or sampler2DShadow, and the texture object's base 190 internal format is DEPTH_COMPONENT or DEPTH_STENCIL_EXT, and the 191 TEXTURE_COMPARE_MODE is NONE. 192 193 * The sampler used in a texture lookup function is of type 194 sampler1DShadow or sampler2DShadow, and the texture object's base 195 internal format is not DEPTH_COMPONENT or DEPTH_STENCIL_EXT. 196 197 The stencil index texture internal component is ignored if the base 198 internal format is DEPTH_STENCIL_EXT. 199 200 If a vertex shader uses..." 201 202Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 203 204 Update the first paragraph on page 118, in the definition of 205 ColorTable, to say: 206 207 "... The <formats> COLOR_INDEX, DEPTH_COMPONENT, DEPTH_STENCIL_EXT, 208 and STENCIL_INDEX and the <type> BITMAP are not allowed." 209 210 Update the third paragraph on page 118, in the definition of 211 ColorTable, to say: 212 213 "... <internalformat> must be one of the formats in table 3.15 or 214 table 3.16, other than the DEPTH or DEPTH_STENCIL_EXT formats in 215 those tables." 216 217 On page 121, update the first paragraph in the definition of 218 ConvolutionFilter2D to say: 219 220 "... The formats COLOR_INDEX, DEPTH_COMPONENT, DEPTH_STENCIL_EXT, 221 and STENCIL_INDEX and the type BITMAP are not allowed." 222 223 Update the paragraph that spans pages 121 and 122, in the definition 224 of ConvolutionFilter2D, to say: 225 226 "... <internalformat> must be one of the formats in table 3.15 or 227 table 3.16, other than the DEPTH or DEPTH_STENCIL_EXT formats in 228 those tables." 229 230 Update the third paragraph on page 125, in the definition of 231 Histogram, to say: 232 233 "... The error INVALID ENUM is generated if internalformat is not 234 one of the formats in table 3.15 or table 3.16, or is 1, 2, 3, 4, or 235 any of the DEPTH_COMPONENT or DEPTH_STENCIL_EXT or INTENSITY formats 236 in those tables." 237 238 On page 126, update the second paragraph in the definition of Minmax 239 to say: 240 241 "... The error INVALID ENUM is generated if internalformat is not 242 one of the formats in table 3.15 or table 3.16, or is 1, 2, 3, 4, or 243 any of the DEPTH_COMPONENT or DEPTH_STENCIL_EXT or INTENSITY formats 244 in those tables. The resulting..." 245 246 Add a row to Table 3.5 (page 128): 247 248 type Parameter GL Type Special 249 ------------------------------------------------ 250 ... ... ... 251 UNSIGNED_INT_2_10_10_10_REV uint Yes 252 UNSIGNED_INT_24_8_EXT uint Yes 253 254 Update the paragraph on page 128, in the definition of DrawPixels, 255 to say: 256 257 "... If the GL is in color index mode and <format> is not one of 258 COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL_EXT, 259 then the error INVALID_OPERATION occurs. If <type> is BITMAP and 260 <format> is not COLOR_INDEX or STENCIL_INDEX then the error 261 INVALID_ENUM occurs. If <format> is DEPTH_STENCIL_EXT and <type> is 262 not UNSIGNED_INT_24_8_EXT then the error INVALID_ENUM occurs. Some 263 additional constraints on the combinations of <format> and <type> 264 values that are accepted is discussed below." 265 266 Add a row to Table 3.6 (page 129): 267 268 Format Name Element Meaning and Order Target Buffer 269 ------------------------------------------------------------------ 270 ... ... ... 271 DEPTH_COMPONENT Depth Depth 272 DEPTH_STENCIL_EXT Depth and Stencil Index Depth and Stencil 273 ... ... ... 274 275 Add a row to Table 3.8 (page 132): 276 277 type Parameter GL Type Components Pixel Formats 278 ------------------------------------------------------------------ 279 ... ... ... ... 280 UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA 281 UNSIGNED_INT_24_8_EXT uint 2 DEPTH_STENCIL_EXT 282 283 Update the last paragraph on page 130 to say: 284 285 "Calling DrawPixels with a <type> of UNSIGNED_BYTE_3_3_2, ..., 286 UNSIGNED_INT_2_10_10_10_REV, or UNSIGNED_INT_24_8_EXT is a special 287 case in which all the components of each group are packed into a 288 single unsigned byte, unsigned short, or unsigned int, depending on 289 the type." 290 291 Add the following diagram to Table 3.11 (page 134): 292 293 UNSIGNED_INT_24_8_EXT 294 295 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 296 +----------------------------------+---------------+ 297 | 1st Component | 2nd Component | 298 +----------------------------------+---------------+ 299 300 Add a row to Table 3.12 (page 135): 301 302 Format | 1st 2nd 3rd 4th 303 ------------------+------------------------------- 304 ... | ... ... ... ... 305 BGRA | blue green red alpha 306 DEPTH_STENCIL_EXT | depth stencil N/A N/A 307 308 Add the following paragraph to the end of the section "Conversion to 309 floating-point" (page 135-136): 310 311 "For groups of components that contain both standard components and 312 index elements, such as DEPTH_STENCIL_EXT, the index elements are 313 not converted." 314 315 Update the last paragraph in the section "Conversion to Fragments" 316 (page 137) to say: 317 318 "... Groups arising from DrawPixels with a <format> of STENCIL_INDEX 319 or DEPTH_STENCIL_EXT are treated specially and are described in 320 section 4.3.1." 321 322 Update the first paragraph of section 3.6.5 "Pixel Transfer 323 Operations" (pages 137-138) to say: 324 325 "The GL defines five kinds of pixel groups: 326 327 1. RGBA component: Each group comprises four color components: 328 red, green, blue, and alpha. 329 2. Depth component: Each group comprises a single depth 330 component. 331 3. Color index: Each group comprises a single color index. 332 4. Stencil index: Each group comprises a single stencil index. 333 5. Depth/stencil: Each group comprises a single depth component 334 and a single stencil index." 335 336 Update the first paragraph in the section "Arithmetic on Components" 337 (page 138) to say: 338 339 "This step applies only to RGBA component and depth component 340 groups, and to the depth components in depth/stencil groups. ..." 341 342 Update the first paragraph in the section "Arithmetic on Indices" 343 (page 138) to say: 344 345 "This step applies only to color index and stencil index groups, and 346 to the stencil indices in depth/stencil groups. ..." 347 348 Update the first paragraph in the section "Stencil Index Lookup" 349 (page 139) to say: 350 351 "This step applies only to stencil index groups and to the stencil 352 indices in depth/stencil groups. ..." 353 354 In section 3.8.1 "Texture Image Specification", update page 151 to 355 say: 356 357 "The selected groups are processed exactly as for DrawPixels, 358 stopping just before final conversion. Each R, G, B, A, or depth 359 value so generated is clamped to [0, 1], while the stencil index 360 values are masked by 2^n-1, where n is the number of stencil bits in 361 the internal format resolution (see below). If the base internal 362 format is DEPTH_STENCIL_EXT and <format> is not DEPTH_STENCIL_EXT, 363 then the values of the stencil index texture component are 364 undefined. 365 366 Components are then selected from the resulting R, G, B, A, depth, 367 or stencil index values to obtain a texture with the base internal 368 format specified by (or derived from) <internalformat>. Table 3.15 369 summarizes the mapping of R, G, B, A, depth, or stencil values to 370 texture components, as a function of the base internal format of the 371 texture image. <internalformat> may be specified as one of the 372 eight internal format symbolic constants listed in table 3.15, as 373 one of ... 374 375 Textures with a base internal format of DEPTH_COMPONENT or 376 DEPTH_STENCIL_EXT are supported by texture image specification 377 commands only if <target> is TEXTURE_1D, TEXTURE_2D, 378 PROXY_TEXTURE_1D or PROXY_TEXTURE_2D. Using this format in 379 conjunction with any other <target> will result in an 380 INVALID_OPERATION error. 381 382 Textures with a base internal format of DEPTH_COMPONENT or 383 DEPTH_STENCIL_EXT require either depth component data or 384 depth/stencil component data. Textures with other base internal 385 formats require RGBA component data. The error INVALID_OPERATION is 386 generated if the base internal format is DEPTH_COMPONENT or 387 DEPTH_STENCIL_EXT and <format> is not DEPTH_COMPONENT or 388 DEPTH_STENCIL_EXT, or if the base internal format is not 389 DEPTH_COMPONENT or DEPTH_STENCIL_EXT and <format> is DEPTH_COMPONENT 390 or DEPTH_STENCIL_EXT." 391 392 Update the second paragraph on page 152 to say: 393 394 "...the mapping of the R, G, B, A, depth and stencil values to 395 texture components..." 396 397 Update the third paragraph on page 152 to say: 398 399 "...the mapping of the R, G, B, A, depth, and stencil values to 400 texture components..." 401 402 Add a row to table 3.15 (page 153), and update the title of the 403 second column: 404 405 Base Internal Format RGBA and Depth and Stencil Values Internal Components 406 ---------------------------------------------------------------------------- 407 ... ... ... 408 DEPTH_STENCIL_EXT Depth,Stencil D,S 409 ... ... ... 410 411 Update the caption for table 3.15 (page 153) 412 413 "Table 3.15: Conversion from RGBA, depth, and stencil pixel 414 components to internal texture, table, or filter components. See 415 section 3.8.13 for a description of the texture components R, G, B, 416 A, L, I, D, and S." 417 418 Add a new column to table 3.16 (page 153) labled "S bits". The 419 value of this column is blank for all rows except a new row: 420 421 Sized Base R G B A L I D S 422 Internal Format InternalFormat bits bits bits bits bits bits bits bits 423 ------------------------------------------------------------------------------ 424 ... ... ... ... ... ... ... ... ... ... 425 DEPTH24_STENCIL8_EXT DEPTH_STENCIL_EXT 24 8 426 ... ... ... ... ... ... ... ... ... ... 427 428 Update the second paragraph on page 159, in the definition of 429 CopyTexImage2D, to say: 430 431 "...The image is taken from the framebuffer exactly as if these 432 arguments were passed to CopyPixels with argument type set to COLOR 433 DEPTH, or DEPTH_STENCIL_EXT, depending on <internalformat>, stopping 434 after pixel transfer processing is complete. RGBA data is taken 435 from the current color buffer, while depth component and stencil 436 index data are taken from the depth and stencil buffers, 437 respectively. If depth component data is required and no depth 438 buffer is present, or if stencil index data is required and there is 439 no stencil buffer, the error INVALID_OPERATION is generated. 440 Subsequent processing is identical to that described for TexImage2D, 441 beginning with clamping of the R, G, B, A, or depth values, and 442 masking of the stencil index value, from the resulting pixel 443 groups..." 444 445 Update the third paragraph on page 161 to say: 446 447 "...except that the assignment of R, G, B, A, depth, and stencil 448 pixel group values to the texture components is controlled by the 449 internalformat of the texture array, not by an argument to the 450 command..." 451 452 Update section 3.8.5 "Depth Component Textures" (page 168) to say: 453 454 "Depth textures and the depth components of depth/stencil textures 455 can be treated as LUMINANCE, INTENSITY or ALPHA textures during 456 texture filtering and application. The initial state for depth and 457 depth/stencil textures treats them as LUMINANCE textures." 458 459 Add a new section between sections 3.8.9 and 3.8.10, after the first 460 paragraph on page 177: 461 462 "3.8.9-1/2 DEPTH/STENCIL Textures 463 464 If the texture image has a base internal format of 465 DEPTH_STENCIL_EXT, then the stencil index texture component is 466 ignored. The texture value Tau does not include a stencil index 467 component, but includes only the depth component." 468 469 Update the first paragraph of section 3.8.11 "Texture State and 470 Proxy State" on page 178 to say: 471 472 "...eight integer values describing the resolutions of each of the 473 red, green, blue, alpha, luminance, intensity, depth, and stencil 474 components of the image..." 475 476 Update the second paragraph on page 179 to say: 477 478 "... and internal format state values, as well as state for the red, 479 green, blue, alpha, luminance, intensity, depth, and stencil 480 component resolutions." 481 482 Update the first paragraph of "Depth Texture Comparison Mode" in 483 section 3.8.14 on page 188 to say: 484 485 "If the currently bound texture's base internal format is 486 DEPTH_COMPONENT or DEPTH_STENCIL_EXT..." 487 488 Update the first paragraph of section 3.8.15 "Texture Application", 489 on page 189, to say: 490 491 "...Otherwise, a texture value is found according to the parameter 492 values of the currently bound texture image of the appropriate 493 dimensionality using the rules given in sections 3.8.6 through 494 3.8.9. Note that the texture value may contain R, G, B, A, L, I, or 495 D components, but it does not contain an S component. If the 496 texture's base internal format is DEPTH_STENCIL_EXT, for the 497 purposes of texture application, it is as if the base internal 498 format was DEPTH..." 499 500 Starting with the bullet list on page 195, update section 3.11.2 501 "Shader Execution" to say: 502 503 "* The sampler used in a texture lookup function is of type 504 sampler1D or sampler2D, and the texture object's base internal 505 format is DEPTH_COMPONENT or DEPTH_STENCIL_EXT, and the 506 TEXTURE_COMPARE_MODE is not NONE. 507 508 * The sampler used in a texture lookup function is of type 509 sampler1DShadow or sampler2DShadow, and the texture object's base 510 internal format is DEPTH_COMPONENT or DEPTH_STENCIL_EXT, and the 511 TEXTURE_COMPARE_MODE is NONE. 512 513 * The sampler used in a texture lookup function is of type 514 sampler1DShadow or sampler2DShadow, and the texture object's base 515 internal format is not DEPTH_COMPONENT or DEPTH_STENCIL_EXT. 516 517 The stencil index texture internal component is ignored if the base 518 internal format is DEPTH_STENCIL_EXT. 519 520 If a fragment shader uses..." 521 522Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 523Operations and the Frame Buffer) 524 525 Replace section 4.3.1 "Writing to the Stencil Buffer" (page 218) 526 with the following: 527 528 "4.3.1 Writing to the Stencil Buffer or to the Depth and Stencil 529 Buffers 530 531 The operation of DrawPixels was described in section 3.6.4, except 532 if the <format> argument was STENCIL_INDEX or DEPTH_STENCIL_EXT. In 533 this case, all operations described for DrawPixels take place, but 534 window (x,y) coordinates, each with the corresponding stencil index, 535 or depth value and stencil index, are produced in lieu of fragments. 536 Each coordinate-data pair is sent directly to the per-fragment 537 operations, bypassing the texture, fog, and antialiasing application 538 stages of rasterization. Each pair is then treated as a fragment 539 for purposes of the pixel ownership and scissor tests; all other 540 per-fragment operations are bypassed. Finally, each stencil index 541 is written to its indicated location in the framebuffer, subject to 542 the current front stencil mask (set with StencilMask or 543 StencilMaskSeparate). If a depth component is present, and if the 544 setting of DepthMask is not FALSE, the depth component is also 545 written to the framebuffer; the setting of DepthTest is ignored. 546 547 The error INVALID_OPERATION results if the <format> argument is 548 STENCIL_INDEX and there is no stencil buffer, or if <format> is 549 DEPTH_STENCIL_EXT and there is neither a depth nor a stencil 550 buffer." 551 552 Add the following paragraph after the second paragraph of the 553 section "Obtaining Pixels from the Framebuffer" (page 219): 554 555 "If the <format> is DEPTH_STENCIL_EXT, then values are taken from 556 both the depth buffer and the stencil buffer. If there is no depth 557 buffer or if there is no stencil buffer, then the error 558 INVALID_OPERATION occurs. If the <type> parameter is not 559 UNSIGNED_INT_24_8_EXT, then the error INVALID_ENUM occurs. 560 561 If there is a multisample buffer, then values are obtained from the 562 depth and stencil samples in this buffer. It is recommended that the 563 depth and stencil values of the centermost sample be used, though 564 implementations may choose any function of the depth and stencil 565 sample values at each pixel." 566 567 Update the third paragraph on page 221 to say: 568 569 "... If the GL is in color index mode, and <format> is not 570 DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL_EXT, then the color 571 index is obtained at each pixel location." 572 573 Update the first sentence of the section "Conversion of RGBA values" 574 (page 222) to say: 575 576 "This step applies only if the GL is in RGBA mode, and then only if 577 <format> is neither STENCIL_INDEX, DEPTH_COMPONENT, nor 578 DEPTH_STENCIL_EXT." 579 580 Update the section "Conversion of Depth values" (page 222) to say: 581 582 "This step applies only if <format> is DEPTH_COMPONENT or 583 DEPTH_STENCIL_EXT. Each element taken from the depth buffer is 584 taken to be a fixed-point value in [0,1] with m bits, where m is the 585 number of bits in the depth buffer (see section 2.11.1)." 586 587 Add a row to Table 4.6 (page 223): 588 589 type Parameter Index Mask 590 --------------------------------- 591 ... ... 592 INT 2^31-1 593 UNSIGNED_INT_24_8_EXT 2^8-1 594 595 Update the second and third paragraphs of section 4.3.3 (page 223) 596 to say: 597 598 "<type> is a symbolic constant that must be one of COLOR, STENCIL, 599 DEPTH, or DEPTH_STENCIL_EXT, indicating that the values to be 600 transferred are colors, stencil values, depth values, or 601 depth/stencil pairs, respectively. The first four arguments have the 602 same interpretation as the corresponding arguments to ReadPixels. 603 604 Values are obtained from the framebuffer, converted (if 605 appropriate), then subjected to the pixel transfer operations 606 described in section 3.6.5, just as if ReadPixels were called with 607 the corresponding arguments. If the <type> is STENCIL or DEPTH, 608 then it is as if the <format> for ReadPixels were STENCIL_INDEX, or 609 DEPTH_COMPONENT, respectively. If the <type> is DEPTH_STENCIL_EXT, 610 then it is as if the <format> for ReadPixels were specified as 611 described in table 4.6b. If the <type> is COLOR, then if the GL is 612 in RGBA mode, it is as if the <format> were RGBA, while if the GL is 613 in color index mode, it is as if the <format> were COLOR_INDEX." 614 615 Add Table 4.6b: 616 617 DEPTH_BITS STENCIL_BITS format 618 ------------------------------------------- 619 zero zero DEPTH_STENCIL_EXT 620 zero non-zero DEPTH_COMPONENT 621 non-zero zero STENCIL_INDEX 622 non-zero non-zero DEPTH_STENCIL_EXT 623 624 Table 4.6b: Effective ReadPixels format for DEPTH_STENCIL_EXT 625 CopyPixels operation. 626 627 Add a row to Table 4.7 (page 224): 628 629 type Parameter GL Type Component Conversion ... 630 ------------------------------------------------------------------ 631 ... ... ... 632 UNSIGNED_INT_2_10_10_10_REV uint c = (2^N - 1)f 633 UNSIGNED_INT_24_8_EXT uint c = (2^N - 1)f (depth only) 634 635Additions to Chapter 4 of the OpenGL 2.0 Specification, as modified by 636the EXT_framebuffer_object specification 637 638 In section 4.4.2.1 "Renderbuffer Objects", modify the first 639 paragraph in the definition of RenderbufferStorageEXT to say: 640 641 "... <internalformat> must be RGB, RGBA, DEPTH_COMPONENT, 642 STENCIL_INDEX, DEPTH_STENCIL_EXT, or one of the internal formats 643 from table 3.16 or table 2.nnn that has a base internal format of 644 RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL_EXT..." 645 646 In section 4.4.4 "Framebuffer Completeness", modify the definition of 647 "depth-renderable" and "stencil-renderable" to say: 648 649 "* An internal format is "depth-renderable" if it is 650 DEPTH_COMPONENT or one of the formats from table 3.16 whose 651 base internal format is DEPTH_COMPONENT or DEPTH_STENCIL_EXT. 652 No other formats are depth-renderable. 653 654 * An internal format is "stencil-renderable" if it is 655 STENCIL_INDEX or DEPTH_STENCIL_EXT, if it is one of the 656 STENCIL_INDEX formats from table 2.nnn, or if it is one of the 657 formats from table 3.16 whose base internal format is 658 DEPTH_STENCIL_EXT. No other formats are stencil-renderable." 659 660 In section 4.4.4.2 "Framebuffer Completeness", modify the 661 duplicate attachment clause of "framebuffer complete" to say: 662 663 "* A single image is not attached more than once to the framebuffer 664 object. The exception is that an image with a DEPTH_STENCIL_EXT 665 base internal format may be simultaneously attached to both 666 FRAMEBUFFER_DEPTH_ATTACHMENT and FRAMEBUFFER_STENCIL_ATTACHMENT. 667 { FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT }" 668 669Additions to Chapter 5 of the OpenGL 2.0 Specification (Special 670Functions) 671 672 None. 673 674Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 675Requests) 676 677 Update the third paragraph on page 247, of section 6.1.3 "Enumerated 678 Queries", to say: 679 680 "For texture images with uncompressed internal formats, queries of 681 value of TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, TEXTURE_BLUE_SIZE, 682 TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, TEXTURE_INTENSITY_SIZE, 683 TEXTURE_DEPTH_SIZE, and TEXTURE_STENCIL_SIZE_EXT return the actual 684 resolutions of the stored image array components..." 685 686 Section 6.1.4, Texture Queries, p. 248, replace the first two 687 sentences of paragraph two as follows: 688 689 "Calling GetTexImage with a color format (one of RED, GREEN, 690 BLUE, ALPHA, RGB, BGR, RGBA, BGRA, LUMINANCE, or 691 LUMINANCE_ALPHA) when the internal format of the texture image 692 is not a color format causes the error INVALID_OPERATION. 693 694 Calling GetTexImage with a <format> of DEPTH_COMPONENT when the 695 base internal format of the texture image is not DEPTH_COMPONENT 696 or DEPTH_STENCIL_EXT causes the error INVALID_OPERATION. 697 698 Calling GetTexImage with a <format> of DEPTH_STENCIL_EXT when 699 the base internal format of the texture image is not 700 DEPTH_STENCIL_EXT causes the error INVALID_OPERATION. 701 702 GetTexImage obtains component groups from a texture image with 703 the indicated level-of-detail. If <format> is a color format, 704 then the components are assigned among R, G, B, and A according 705 to Table 6.1, starting with the first group in the first row, 706 and continuing by obtaining groups in order from each row and 707 proceeding from the first row to the last, and from the first 708 image to the last for three-dimensional textures. If <format> 709 is DEPTH_COMPONENT, then each depth component is assigned with 710 the same ordering of rows and images. If <format> is 711 DEPTH_STENCIL_EXT, then each depth component and each stencil 712 index is assigned with the same ordering of rows and images." 713 714 Add a row to table 6.17 "Textures (state per texture image)" on page 715 278: 716 717 Get value Type Get Cmd IV Description Sec. 718 ------------------------------------------------------------------------------------------------------- 719 ... ... ... ... ... ... 720 TEXTURE_STENCIL_SIZE_EXT n x Z+ GetTexLevelParameter 0 texture image's intensity resolution 3.8.3 721 722 Update 723 724Dependencies on EXT_framebuffer_object 725 726 If EXT_framebuffer_object is not supported, then all discussion of 727 framebuffer objects and renderbuffer objects should be removed. 728 729GLX Protocol 730 731 None. 732 733Errors 734 735 The error INVALID_ENUM is generated if DrawPixels or ReadPixels is 736 called where format is DEPTH_STENCIL_EXT and type is not 737 UNSIGNED_INT_24_8_EXT. 738 739 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 740 is called where type is UNSIGNED_INT_24_8_EXT and format is not 741 DEPTH_STENCIL_EXT. 742 743 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 744 is called where format is DEPTH_STENCIL_EXT and there is not both a 745 depth buffer and a stencil buffer. 746 747 The error INVALID_OPERATION is generated if CopyPixels is called 748 where type is DEPTH_STENCIL_EXT and there is not both a depth buffer 749 and a stencil buffer. 750 751 Update the following error in the EXT_framebuffer_object 752 specification by adding mention of DEPTH_STENCIL_EXT formats: 753 754 "The error INVALID_ENUM is generated if RenderbufferStorageEXT is 755 called with an <internalformat> that is not RGB, RGBA, 756 DEPTH_COMPONENT, STENCIL_INDEX, DEPTH_STENCIL_EXT, or one of the 757 internal formats from table 3.16 or table 2.nnn that has a base 758 internal format of RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, or 759 DEPTH_STENCIL_EXT." 760 761New State 762 763 None. 764 765Usage ExampleS 766 767 (1) Attach a DEPTH_STENCIL_EXT texture image to an FBO as both the 768 depth and stencil buffers. 769 770 glGenFramebuffersEXT(1, &fb); 771 glGenTextures(1, &tex_color); 772 glGenTextures(1, &tex_depthstencil); 773 774 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 775 776 // Setup color texture (mipmap) 777 glBindTexture(GL_TEXTURE_2D, tex_color); 778 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 779 512, 512, 0, GL_RGBA, GL_INT, NULL); 780 glGenerateMipmapEXT(GL_TEXTURE_2D); 781 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 782 GL_COLOR_ATTACHMENT0_EXT, 783 GL_TEXTURE_2D, tex_color, 0); 784 785 // Setup depth_stencil texture (not mipmap) 786 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 787 glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 788 glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH24_STENCIL8_EXT, 789 512, 512, 0, GL_DEPTH_STENCIL_EXT, 790 GL_UNSIGNED_INT_24_8_EXT, NULL); 791 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 792 GL_DEPTH_ATTACHMENT_EXT, 793 GL_TEXTURE_2D, tex_depthstencil, 0); 794 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 795 GL_STENCIL_ATTACHMENT_EXT, 796 GL_TEXTURE_2D, tex_depthstencil, 0); 797 798 // Check framebuffer completeness at the end of initialization. 799 800 loop { 801 glBindTexture(GL_TEXTURE_2D, 0); 802 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 803 <render to color, depth, and stencil textures> 804 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 805 806 glBindTexture(GL_TEXTURE_2D, tex_color); 807 glGenerateMipmapEXT(GL_TEXTURE_2D); 808 <draw to the window, reading from the color texture> 809 810 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 811 <draw to the window, reading depth from the depthstencil texture> 812 } 813 814Issues 815 816 01) Depth data has a format of GL_DEPTH_COMPONENT, and stencil data 817 has a format of STENCIL_INDEX. So shouldn't the enumerant be 818 called DEPTH_COMPONENT_STENCIL_INDEX_EXT? 819 820 RESOLVED: No, this is fairly clumsy. 821 822 02) Should we support CopyPixels? 823 824 RESOLVED: Yes. Right now copying stencil data means masking off 825 just the stencil bits, while copying depth data has strange 826 unintended consequences (fragment operations) and is difficult 827 to implement. It is easy and useful to add CopyPixels support. 828 829 03) Should we support textures? 830 831 RESOLVED: Yes. 24-bit depth textures have no good format 832 without this extension. 833 834 04) Should the depth/stencil format support other standard types, 835 like FLOAT or UNSIGNED_INT? 836 837 RESOLVED: No, this extension is designed to be minimalist. 838 Supporting more types gains little because the new types will 839 just require data format conversions. Our goal is to match the 840 native format of the buffer, not add broad new classes of 841 functionality. 842 843 05) Should the 24/8 format be supported for other formats, such as 844 LUMINANCE_ALPHA? Should we support an 8/24 reversed format as 845 well? 846 847 RESOLVED: No and no, this adds implementation burden and gains 848 us little, if anything. 849 850 06) Should anything be said about performance? 851 852 RESOLVED: No, not in the spec. However, common sense should 853 apply. Apps should probably check that DEPTH_BITS is 24 and 854 that STENCIL_BITS is 8 before using either the new DrawPixels or 855 ReadPixels formats. CopyPixels is probably safe regardless of 856 the size of either buffer. The 24/8 format should probably only 857 be used with 24-bit depth textures. 858 859 07) What happens when the format of a DEPTH_STENCIL_EXT pixel path 860 operation specifies more components than are present in the 861 source? 862 863 RESOLVED: INVALID_OPERATION is generated. 864 865 Operations affected by this issue include ReadPixels and 866 operations defined in terms of ReadPixels, such as CopyPixels, 867 CopyTexImage, CopyTexSubImage, and GetTexImage. 868 869 For example, if the framebuffer has non-zero DEPTH_BITS but zero 870 STENCIL_BITS, then ReadPixels of DEPTH_COMPONENT is legal. But 871 ReadPixels of DEPTH_STENCIL_EXT will generate INVALID_OPERATION. 872 873 08) What happens when the format of a DEPTH_STENCIL_EXT pixel path 874 operation specifies more components than are present in the 875 destination? 876 877 RESOLVED: The extra information is thrown away. No GL error is 878 generated because the source contains more components than the 879 destination. 880 881 For example, consider a TexSubImage operation where the source 882 data is DEPTH_STENCIL_EXT but the existing texture format is 883 DEPTH_COMPONENT. 884 885 09) What happens when the format of a DEPTH_STENCIL_EXT pixel path 886 operation specifies fewer components than are present in the 887 destination? 888 889 RESOLVED: the existing values of the unspecified components are 890 preserved. 891 892 For example, consider a TexSubImage operation where the <format> 893 is DEPTH_COMPONENT and the existing internalformat is 894 DEPTH_STENCIL_EXT. The texture image's depth component will be 895 updated, but the texture's existing stencil component will be 896 preserved. 897 898 10) And, for completeness, what happens when the format of a 899 DEPTH_STENCIL_EXT pixel path operation specifies fewer 900 components than are present in the source? 901 902 RESOLVED: trivial. Only the specified components are read. 903 904 11) How does the texture border color interact with a 905 DEPTH_STENCIL_EXT texture? 906 907 RESOLVED: nothing special needs to be stated here. 908 909 There is no stencil component in the border color. Either 910 you're rendering to it, in which case it's just a buffer, or 911 texturing from it, in which case stencil is irrelevant. If a 912 future use case comes up, the second component of 913 TEXTURE_BORDER_COLOR could be used at the stencil border value, 914 just as the first component is used as the depth value today. 915 916 12) How does automatic mipmap generation deal with the stencil 917 component of a DEPTH_STENCIL_EXT texture? 918 919 RESOLVED: The 2.0 spec doesn't talk about depth textures 920 specifically. Stencils, which are indexes / counts, are even 921 harder. We'll leave this undefined. 922 923 Also, an application that wants to generate a stencil mipmap can 924 follow the procedure given in example 5 of the 925 EXT_framebuffer_object specification. 926 927 13) Should GetTexImage permit <format> of DEPTH_STENCIL_EXT? 928 929 RESOLVED: Yes. 930 931 The GL 2.0 spec disallows GetTexImage of DEPTH_COMPONENT data. 932 But that seems to be an unintentional spec bug. 933 ARB_depth_texture permitted it and even addressed the question 934 as issue 9. Appendix G.4 of the GL 2.0 spec does not mention 935 this discrepancy. 936 937 GetTexImage of DEPTH_STENCIL_EXT format should follow the 938 resolution for GetTexImage of DEPTH_COMPONENT format. 939 940 A future version of the core GL spec will be modified to state 941 that GetTexImage of DEPTH_COMPONENT data is legal. 942 943 14) Does DrawPixels with DEPTH_STENCIL_EXT format behave like 944 DrawPixels of DEPTH_COMPONENT format, or like DrawPixels of 945 STENCIL_INDEX format? 946 947 RESOLVED: It behaves like DrawPixels of STENCIL_INDEX format. 948 949 See sections 3.6.4 and 4.3.1. It is desirable to give similar 950 treatment to both the depth and the stencil components. 951 952 15) If depth/stencil images are mixed such that they violate the 953 framebuffer completeness rule in section 4.4.4.2, what 954 FRAMEBUFFER_INCOMPLETE_ enum should be used? 955 956 UNRESOLVED: FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT and 957 FRAMEBUFFER_INCOMPLETE_MIXED_DEPTH_STENCIL_EXT are possible 958 answers. 959 960 16) What happens if DEPTH_STENCIL_EXT and STENCIL_ATTACHMENT_EXT 961 name distinct framebuffer-attachable images, but the format of 962 one or both is DEPTH_STENCIL_EXT? 963 964 RESOLVED: This is permitted. The depth component of the depth 965 attachment should be updated, the stencil component of the 966 stencil attachment should be updated, and the other components 967 are preserved. However, it should be noted that some 968 implementations might not support such mix-matching, and that 969 these implementations are free to label such a framebuffer as 970 FRAMEBUFFER_UNSUPPORTED_EXT. 971 972 An earlier drafts of this extension contained the following 973 language. 974 975 In section 4.4.4.2 "Framebuffer Completeness", add a clause 976 to the definition of "framebuffer complete": 977 978 "* If both attachment points FRAMEBUFFER_DEPTH_ATTACHMENT 979 and FRAMEBUFFER_STENCIL_ATTACHMENT have an attached 980 image, and if either image's base internal format is 981 DEPTH_STENCIL_EXT, then the same image must be attached 982 to both FRAMEBUFFER_DEPTH_ATTACHMENT and 983 FRAMEBUFFER_STENCIL_ATTACHMENT. 984 { FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT }" 985 986 That clause was removed from section 4.4.4.2 in revision #10 987 after it was pointed out that, on implementations where such 988 mix-matching is supported, it need not result in an incomplete 989 framebuffer. 990 991Revision History 992 993#12 September 26, 2005 994 - Fix copy/paste error in the example. 995 996#11 September 20, 2005 997 - Assign enum values. 998 999#10 September 19, 2005 1000 - Remove FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT clause and add the 1001 accompanying issue 16 explaining why. 1002 1003#09 September 19, 2005 1004 - Add issue 15. 1005 - Fix FBO interaction. (depth_stencil can be attached twice) 1006 - Add Usage Examples section and example 1. 1007 - Move issues to the end according to new precedent. 1008 - Add more dependencies, add contributors. 1009 - Fix typos pointed out at ARB meeting. 1010 1011#08 September 9, 2005 1012 - Resolve issues 13 and 14. 1013 - Add issue 10 for completeness. 1014 - Modify GetTexImage to permit depth and depth/stencil. 1015 - Incorporate feedback from Barthold's review. 1016 1017#07 August 29, 2005 1018 - Record resolutions for issues 7-12. 1019 - Update the spec body to reflect the issue resolutions. 1020 - Add new issues 13-14. 1021 - Remove interaction with copy_depth_to_color (no resolution needed) 1022 1023#06 July 15, 2005 1024 - Improve some wording in the issues section. 1025 - Add issue on interaction with NV_copy_depth_to_color. 1026 - Remove interaction with stenci_clear_tag (no resolution needed) 1027 1028#05 June 20, 2005 1029 - Add (now removed) unresolved issue 12 on interactions with 1030 EXT_stencil_clear_tag. 1031 1032#04 June 10, 2005 1033 - Add modifications to the EXT_framebuffer_object specification. 1034 1035#03 May 28, 2005 1036 - Add DEPTH_STENCIL_EXT as a new base internal format, 1037 - Add DEPTH24_STENCIL8_EXT as a new sized internal format. 1038 1039#02 May 12, 2005 1040 - Update to be written against OpenGL 2.0 specification. 1041 1042#01 May 12, 2005 1043 - Start with NV_packed_depth_stencil as the basis for 1044 EXT_packed_depth_stencil. 1045 - Rename to EXT. 1046