1Name 2 3 NV_packed_depth_stencil 4 5Name Strings 6 7 GL_NV_packed_depth_stencil 8 9Contact 10 11 Matt Craighead, NVIDIA Corporation (mcraighead 'at' nvidia.com) 12 13Notice 14 15 Copyright NVIDIA Corporation, 2000, 2001. 16 17IP Status 18 19 NVIDIA Proprietary. 20 21Status 22 23 Shipping (version 1.1) 24 25Version 26 27 NVIDIA Date: August 22, 2001 (version 1.1) 28 29Number 30 31 226 32 33Dependencies 34 35 Written based on the wording of the OpenGL 1.2.1 specification. 36 37 SGIX_depth_texture affects the definition of this extension. 38 39Overview 40 41 Many OpenGL implementations have chosen to interleave the depth and 42 stencil buffers into one buffer, often with 24 bits of depth 43 precision and 8 bits of stencil data. 32 bits is more than is needed 44 for the depth buffer much of the time; a 24-bit depth buffer, on the 45 other hand, requires that reads and writes of depth data be unaligned 46 with respect to power-of-two boundaries. On the other hand, 8 bits 47 of stencil data is more than sufficient for most applications, so it 48 is only natural to pack the two buffers into a single buffer with 49 both depth and stencil data. OpenGL never provides direct access to 50 the buffers, so the OpenGL implementation can provide an interface to 51 applications where it appears the one merged buffer is composed of 52 two logical buffers. 53 54 One disadvantage of this scheme is that OpenGL lacks any means by 55 which this packed data can be handled efficiently. For example, when 56 an application reads from the 24-bit depth buffer, using the type 57 GL_UNSIGNED_SHORT will lose 8 bits of data, while GL_UNSIGNED_INT has 58 8 too many. Both require expensive format conversion operations. A 59 24-bit format would be no more suitable, because it would also suffer 60 from the unaligned memory accesses that made the standalone 24-bit 61 depth buffer an unattractive proposition in the first place. 62 63 Many applications, such as parallel rendering applications, may also 64 wish to draw to or read back from both the depth and stencil buffers 65 at the same time. Currently this requires two separate operations, 66 reducing performance. Since the buffers are interleaved, drawing to 67 or reading from both should be no more expensive than using just one; 68 in some cases, it may even be cheaper. 69 70 This extension provides a new data format, GL_DEPTH_STENCIL_NV, that 71 can be used with the glDrawPixels, glReadPixels, and glCopyPixels 72 commands, as well as a packed data type, GL_UNSIGNED_INT_24_8_NV, 73 that is meant to be used with GL_DEPTH_STENCIL_NV. No other formats 74 are supported with GL_DEPTH_STENCIL_NV. If SGIX_depth_texture is 75 supported, GL_DEPTH_STENCIL_NV/GL_UNSIGNED_INT_24_8_NV data can also 76 be used for textures; this provides a more efficient way to supply 77 data for a 24-bit depth texture. 78 79 GL_DEPTH_STENCIL_NV data, when passed through the pixel path, 80 undergoes both depth and stencil operations. The depth data is 81 scaled and biased by the current GL_DEPTH_SCALE and GL_DEPTH_BIAS, 82 while the stencil data is shifted and offset by the current 83 GL_INDEX_SHIFT and GL_INDEX_OFFSET. The stencil data is also put 84 through the stencil-to-stencil pixel map. 85 86 glDrawPixels of GL_DEPTH_STENCIL_NV data operates similarly to that 87 of GL_STENCIL_INDEX data, bypassing the OpenGL fragment pipeline 88 entirely, unlike the treatment of GL_DEPTH_COMPONENT data. The 89 stencil and depth masks are applied, as are the pixel ownership and 90 scissor tests, but all other operations are skipped. 91 92 glReadPixels of GL_DEPTH_STENCIL_NV data reads back a rectangle from 93 both the depth and stencil buffers. 94 95 glCopyPixels of GL_DEPTH_STENCIL_NV data copies a rectangle from 96 both the depth and stencil buffers. Like glDrawPixels, it applies 97 both the stencil and depth masks but skips the remainder of the 98 OpenGL fragment pipeline. 99 100 glTex[Sub]Image[1,2,3]D of GL_DEPTH_STENCIL_NV data loads depth data 101 into a depth texture. glGetTexImage of GL_DEPTH_STENCIL_NV data can 102 be used to retrieve depth data from a depth texture. 103 104Issues 105 106 * Depth data has a format of GL_DEPTH_COMPONENT, and stencil data 107 has a format of GL_STENCIL_INDEX. So shouldn't the enumerant be 108 called GL_DEPTH_COMPONENT_STENCIL_INDEX_NV? 109 110 RESOLVED: No, this is fairly clumsy. 111 112 * Should we support CopyPixels? 113 114 RESOLVED: Yes. Right now copying stencil data means masking off 115 just the stencil bits, while copying depth data has strange 116 unintended consequences (fragment operations) and is difficult to 117 implement. It is easy and useful to add CopyPixels support. 118 119 * Should we support textures? 120 121 RESOLVED: Yes. 24-bit depth textures have no good format without 122 this extension. 123 124 * Should the depth/stencil format support other standard types, 125 like GL_FLOAT or GL_UNSIGNED_INT? 126 127 RESOLVED: No, this extension is designed to be minimalist. 128 Supporting more types gains little because the new types will 129 just require data format conversions. Our goal is to match the 130 native format of the buffer, not add broad new classes of 131 functionality. 132 133 * Should the 24/8 format be supported for other formats, such as 134 LUMINANCE_ALPHA? Should we support an 8/24 reversed format as 135 well? 136 137 RESOLVED: No and no, this adds implementation burden and gains us 138 little, if anything. 139 140 * Does anything need to be written in the spec on the topic of 141 using GL_DEPTH_STENCIL_NV formats for glTexImage* or 142 glGetTexImage? 143 144 RESOLVED: No. Since the SGIX_depth_texture extension spec was 145 never actually written (the additions to Section 3 are "XXX - 146 lots" and a few brief notes on how it's intended to work), it's 147 impossible to write what would essentially be amendments to that 148 spec. 149 150 However, it is worthwhile to mention here the intended behavior. 151 When downloading into a depth component texture, the stencil 152 indices are ignored, and when retrieving a depth component 153 texture, the stencil indices obtained from the texture are 154 undefined. 155 156 * Should anything be said about performance? 157 158 RESOLVED: No, not in the spec. However, common sense should 159 apply. Apps should probably check that GL_DEPTH_BITS is 24 and 160 that GL_STENCIL_BITS is 8 before using either the new DrawPixels 161 or ReadPixels formats. CopyPixels is probably safe regardless of 162 the size of either buffer. The 24/8 format should probably only 163 be used with 24-bit depth textures. 164 165New Procedures and Functions 166 167 None. 168 169New Tokens 170 171 Accepted by the <format> parameter of DrawPixels, ReadPixels, 172 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 173 TexSubImage3D, and GetTexImage, and by the <type> parameter of 174 CopyPixels: 175 176 DEPTH_STENCIL_NV 0x84F9 177 178 Accepted by the <type> parameter of DrawPixels, ReadPixels, 179 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 180 TexSubImage3D, and GetTexImage: 181 182 UNSIGNED_INT_24_8_NV 0x84FA 183 184Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 185 186 None. 187 188Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 189 190 Update the first paragraph on page 90 to say: 191 192 "... If the GL is in color index mode and <format> is not one of 193 COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL_NV, 194 then the error INVALID_OPERATION occurs. If <type> is BITMAP and 195 <format> is not COLOR_INDEX or STENCIL_INDEX then the error 196 INVALID_ENUM occurs. If <format> is DEPTH_STENCIL_NV and <type> is 197 not UNSIGNED_INT_24_8_NV then the error INVALID_ENUM occurs. Some 198 additional constraints on the combinations of <format> and <type> 199 values that are accepted is discussed below." 200 201 Add a row to Table 3.5 (page 91): 202 203 type Parameter GL Type Special 204 ------------------------------------------------ 205 ... ... ... 206 UNSIGNED_INT_2_10_10_10_REV uint Yes 207 UNSIGNED_INT_24_8_NV uint Yes 208 209 Add a row to Table 3.6 (page 92): 210 211 Format Name Element Meaning and Order Target Buffer 212 ------------------------------------------------------------------ 213 ... ... ... 214 DEPTH_COMPONENT Depth Depth 215 DEPTH_STENCIL_NV Depth and Stencil Index Depth and Stencil 216 ... ... ... 217 218 Add a row to Table 3.8 (page 94): 219 220 type Parameter GL Type Components Pixel Formats 221 ------------------------------------------------------------------ 222 ... ... ... ... 223 UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA 224 UNSIGNED_INT_24_8_NV uint 2 DEPTH_STENCIL_NV 225 226 Update the last paragraph on page 93 to say: 227 228 "Calling DrawPixels with a <type> of UNSIGNED_BYTE_3_3_2, ..., 229 UNSIGNED_INT_2_10_10_10_REV, or UNSIGNED_INT_24_8_NV is a special 230 case in which all the components of each group are packed into a 231 single unsigned byte, unsigned short, or unsigned int, depending on 232 the type." 233 234 Add the following diagram to Table 3.11 (page 97): 235 236 UNSIGNED_INT_24_8_NV 237 238 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 239 +----------------------------------+---------------+ 240 | 1st Component | 2nd Component | 241 +----------------------------------+---------------+ 242 243 Add a row to Table 3.12 (page 98): 244 245 Format | 1st 2nd 3rd 4th 246 -----------------+------------------------------- 247 ... | ... ... ... ... 248 BGRA | blue green red alpha 249 DEPTH_STENCIL_NV | depth stencil N/A N/A 250 251 Add the following paragraph to the end of the section "Conversion to 252 floating-point" (page 99): 253 254 "For groups of components that contain both standard components and 255 index elements, such as DEPTH_STENCIL_NV, the index elements are not 256 converted." 257 258 Update the last paragraph in the section "Conversion to Fragments" 259 (page 100) to say: 260 261 "... Groups arising from DrawPixels with a <format> of STENCIL_INDEX 262 or DEPTH_STENCIL_NV are treated specially and are described in 263 section 4.3.1." 264 265 Update the first paragraph of section 3.6.5 "Pixel Transfer 266 Operations" (pages 100-101) to say: 267 268 "The GL defines five kinds of pixel groups: 269 270 1. RGBA component: Each group comprises four color components: 271 red, green, blue, and alpha. 272 2. Depth component: Each group comprises a single depth component. 273 3. Color index: Each group comprises a single color index. 274 4. Stencil index: Each group comprises a single stencil index. 275 5. Depth/stencil: Each group comprises a depth component and a 276 stencil index." 277 278 Update the first paragraph in the section "Arithmetic on Components" 279 (page 101) to say: 280 281 "This step applies only to RGBA component and depth component groups 282 and the depth components in depth/stencil groups. ..." 283 284 Update the first paragraph in the section "Arithmetic on Indices" 285 (page 101) to say: 286 287 "This step applies only to color index and stencil index groups and 288 the stencil indices in depth/stencil groups. ..." 289 290 Update the first paragraph in the section "Stencil Index Lookup" 291 (page 102) to say: 292 293 "This step applies only to stencil index groups and the stencil 294 indices in depth/stencil groups. ..." 295 296Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 297Operations and the Frame Buffer) 298 299 Replace section 4.3.1 "Writing to the Stencil Buffer" (page 156) with 300 the following: 301 302 "4.3.1 Writing to the Stencil Buffer or to the Depth and Stencil 303 Buffers 304 305 The operation of DrawPixels was described in section 3.6.4, except if 306 the <format> argument was STENCIL_INDEX or DEPTH_STENCIL_NV. In this 307 case, all operations described for DrawPixels take place, but window 308 (x,y) coordinates, each with the corresponding stencil index or depth 309 value and stencil index, are produced in lieu of fragments. Each 310 coordinate-data pair is sent directly to the per-fragment operations, 311 bypassing the texture, fog, and antialiasing application stages of 312 rasterization. Each pair is then treated as a fragment for purposes 313 of the pixel ownership and scissor tests; all other per-fragment 314 operations are bypassed. Finally, each stencil index is written to 315 its indicated location in the framebuffer, subject to the current 316 setting of StencilMask, and if a depth component is present, if the 317 setting of DepthMask is not FALSE, it is also written to the 318 framebuffer; the setting of DepthTest is ignored. 319 320 The error INVALID_OPERATION results if there is no stencil buffer, or 321 if the <format> argument was DEPTH_STENCIL_NV, if there is no depth 322 buffer." 323 324 Add the following paragraph after the second paragraph of the 325 section "Obtaining Pixels from the Framebuffer" (page 158): 326 327 "If the <format> is DEPTH_STENCIL_NV, then values are taken from both 328 the depth buffer and the stencil buffer. If there is no depth buffer 329 or if there is no stencil buffer, the error INVALID_OPERATION 330 occurs. If the <type> parameter is not UNSIGNED_INT_24_8_NV, the 331 error INVALID_ENUM occurs." 332 333 Update the third paragraph on page 159 to say: 334 335 "If the GL is in RGBA mode, and <format> is one of RED, GREEN, BLUE, 336 ALPHA, RGB, RGBA, BGR, BGRA, LUMINANCE, or LUMINANCE_ALPHA, then red, 337 green, blue, and alpha values are obtained from the framebuffer 338 339 Update the first sentence of the section "Conversion of RGBA values" 340 (page 159) to say: 341 342 "This step applies only if the GL is in RGBA mode, and then only if 343 <format> is neither STENCIL_INDEX, DEPTH_COMPONENT, nor 344 DEPTH_STENCIL_NV." 345 346 Update the section "Conversion of Depth values" (page 159) to say: 347 348 "This step applies only if <format> is DEPTH_COMPONENT or 349 DEPTH_STENCIL_NV. Each element taken from the depth buffer is taken 350 to be a fixed-point value in [0,1] with m bits, where m is the number 351 of bits in the depth buffer (see section 2.10.1)." 352 353 Add a row to Table 4.6 (page 160): 354 355 type Parameter Index Mask 356 --------------------------------- 357 ... ... 358 INT 2^31-1 359 UNSIGNED_INT_24_8_NV 2^8-1 360 361 Add the following paragraph to the end of the section "Final 362 Conversion" (page 160): 363 364 "For a depth/stencil pair, first the depth component is clamped to 365 [0,1]. Then the appropriate conversion formula from Table 4.7 is 366 applied to the depth component, while the index is masked by the 367 value given in Table 4.6 or converted to a GL float data type if the 368 <type> is FLOAT." 369 370 Add a row to Table 4.7 (page 161): 371 372 type Parameter GL Type Component Conversion ... 373 ------------------------------------------------------------------ 374 ... ... ... 375 UNSIGNED_INT_2_10_10_10_REV uint c = (2^N - 1)f 376 UNSIGNED_INT_24_8_NV uint c = (2^N - 1)f (depth only) 377 378 Update the second and third paragraphs of section 4.3.3 (page 162) to 379 say: 380 381 "<type> is a symbolic constant that must be one of COLOR, STENCIL, 382 DEPTH, or DEPTH_STENCIL_NV, indicating that the values to be 383 transfered are colors, stencil values, depth values, or depth/stencil 384 pairs, respectively. The first four arguments have the same 385 interpretation as the corresponding arguments to ReadPixels. 386 387 Values are obtained from the framebuffer, converted (if appropriate), 388 then subjected to the pixel transfer operations described in section 389 3.6.5, just as if ReadPixels were called with the corresponding 390 arguments. If the <type> is STENCIL, DEPTH, or DEPTH_STENCIL_NV, 391 then it is as if the <format> for ReadPixels were STENCIL_INDEX, 392 DEPTH_COMPONENT, or DEPTH_STENCIL_NV, respectively. If the <type> is 393 COLOR, then if the GL is in RGBA mode, it is as if the <format> were 394 RGBA, while if the GL is in color index mode, it is as if the 395 <format> were COLOR_INDEX." 396 397Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 398 399 None. 400 401Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and 402State Requests) 403 404 None. 405 406GLX Protocol 407 408 None. 409 410Errors 411 412 The error INVALID_ENUM is generated if DrawPixels or ReadPixels is 413 called where format is DEPTH_STENCIL_NV and type is not 414 UNSIGNED_INT_24_8_NV. 415 416 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 417 is called where type is UNSIGNED_INT_24_8_NV and format is not 418 DEPTH_STENCIL_NV. 419 420 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 421 is called where format is DEPTH_STENCIL_NV and there is not both a 422 depth buffer and a stencil buffer. 423 424 The error INVALID_OPERATION is generated if CopyPixels is called 425 where type is DEPTH_STENCIL_NV and there is not both a depth buffer 426 and a stencil buffer. 427 428New State 429 430 None. 431 432Revision History 433 434 August 22, 2001 - Fixed a small typo in the updates to Section 4.3.3. 435