| Name |
| |
| NV_packed_depth_stencil |
| |
| Name Strings |
| |
| GL_NV_packed_depth_stencil |
| |
| Contact |
| |
| Matt Craighead, NVIDIA Corporation (mcraighead 'at' nvidia.com) |
| |
| Notice |
| |
| Copyright NVIDIA Corporation, 2000, 2001. |
| |
| IP Status |
| |
| NVIDIA Proprietary. |
| |
| Status |
| |
| Shipping (version 1.1) |
| |
| Version |
| |
| NVIDIA Date: August 22, 2001 (version 1.1) |
| |
| Number |
| |
| 226 |
| |
| Dependencies |
| |
| Written based on the wording of the OpenGL 1.2.1 specification. |
| |
| SGIX_depth_texture affects the definition of this extension. |
| |
| Overview |
| |
| Many OpenGL implementations have chosen to interleave the depth and |
| stencil buffers into one buffer, often with 24 bits of depth |
| precision and 8 bits of stencil data. 32 bits is more than is needed |
| for the depth buffer much of the time; a 24-bit depth buffer, on the |
| other hand, requires that reads and writes of depth data be unaligned |
| with respect to power-of-two boundaries. On the other hand, 8 bits |
| of stencil data is more than sufficient for most applications, so it |
| is only natural to pack the two buffers into a single buffer with |
| both depth and stencil data. OpenGL never provides direct access to |
| the buffers, so the OpenGL implementation can provide an interface to |
| applications where it appears the one merged buffer is composed of |
| two logical buffers. |
| |
| One disadvantage of this scheme is that OpenGL lacks any means by |
| which this packed data can be handled efficiently. For example, when |
| an application reads from the 24-bit depth buffer, using the type |
| GL_UNSIGNED_SHORT will lose 8 bits of data, while GL_UNSIGNED_INT has |
| 8 too many. Both require expensive format conversion operations. A |
| 24-bit format would be no more suitable, because it would also suffer |
| from the unaligned memory accesses that made the standalone 24-bit |
| depth buffer an unattractive proposition in the first place. |
| |
| Many applications, such as parallel rendering applications, may also |
| wish to draw to or read back from both the depth and stencil buffers |
| at the same time. Currently this requires two separate operations, |
| reducing performance. Since the buffers are interleaved, drawing to |
| or reading from both should be no more expensive than using just one; |
| in some cases, it may even be cheaper. |
| |
| This extension provides a new data format, GL_DEPTH_STENCIL_NV, that |
| can be used with the glDrawPixels, glReadPixels, and glCopyPixels |
| commands, as well as a packed data type, GL_UNSIGNED_INT_24_8_NV, |
| that is meant to be used with GL_DEPTH_STENCIL_NV. No other formats |
| are supported with GL_DEPTH_STENCIL_NV. If SGIX_depth_texture is |
| supported, GL_DEPTH_STENCIL_NV/GL_UNSIGNED_INT_24_8_NV data can also |
| be used for textures; this provides a more efficient way to supply |
| data for a 24-bit depth texture. |
| |
| GL_DEPTH_STENCIL_NV data, when passed through the pixel path, |
| undergoes both depth and stencil operations. The depth data is |
| scaled and biased by the current GL_DEPTH_SCALE and GL_DEPTH_BIAS, |
| while the stencil data is shifted and offset by the current |
| GL_INDEX_SHIFT and GL_INDEX_OFFSET. The stencil data is also put |
| through the stencil-to-stencil pixel map. |
| |
| glDrawPixels of GL_DEPTH_STENCIL_NV data operates similarly to that |
| of GL_STENCIL_INDEX data, bypassing the OpenGL fragment pipeline |
| entirely, unlike the treatment of GL_DEPTH_COMPONENT data. The |
| stencil and depth masks are applied, as are the pixel ownership and |
| scissor tests, but all other operations are skipped. |
| |
| glReadPixels of GL_DEPTH_STENCIL_NV data reads back a rectangle from |
| both the depth and stencil buffers. |
| |
| glCopyPixels of GL_DEPTH_STENCIL_NV data copies a rectangle from |
| both the depth and stencil buffers. Like glDrawPixels, it applies |
| both the stencil and depth masks but skips the remainder of the |
| OpenGL fragment pipeline. |
| |
| glTex[Sub]Image[1,2,3]D of GL_DEPTH_STENCIL_NV data loads depth data |
| into a depth texture. glGetTexImage of GL_DEPTH_STENCIL_NV data can |
| be used to retrieve depth data from a depth texture. |
| |
| Issues |
| |
| * Depth data has a format of GL_DEPTH_COMPONENT, and stencil data |
| has a format of GL_STENCIL_INDEX. So shouldn't the enumerant be |
| called GL_DEPTH_COMPONENT_STENCIL_INDEX_NV? |
| |
| RESOLVED: No, this is fairly clumsy. |
| |
| * Should we support CopyPixels? |
| |
| RESOLVED: Yes. Right now copying stencil data means masking off |
| just the stencil bits, while copying depth data has strange |
| unintended consequences (fragment operations) and is difficult to |
| implement. It is easy and useful to add CopyPixels support. |
| |
| * Should we support textures? |
| |
| RESOLVED: Yes. 24-bit depth textures have no good format without |
| this extension. |
| |
| * Should the depth/stencil format support other standard types, |
| like GL_FLOAT or GL_UNSIGNED_INT? |
| |
| RESOLVED: No, this extension is designed to be minimalist. |
| Supporting more types gains little because the new types will |
| just require data format conversions. Our goal is to match the |
| native format of the buffer, not add broad new classes of |
| functionality. |
| |
| * Should the 24/8 format be supported for other formats, such as |
| LUMINANCE_ALPHA? Should we support an 8/24 reversed format as |
| well? |
| |
| RESOLVED: No and no, this adds implementation burden and gains us |
| little, if anything. |
| |
| * Does anything need to be written in the spec on the topic of |
| using GL_DEPTH_STENCIL_NV formats for glTexImage* or |
| glGetTexImage? |
| |
| RESOLVED: No. Since the SGIX_depth_texture extension spec was |
| never actually written (the additions to Section 3 are "XXX - |
| lots" and a few brief notes on how it's intended to work), it's |
| impossible to write what would essentially be amendments to that |
| spec. |
| |
| However, it is worthwhile to mention here the intended behavior. |
| When downloading into a depth component texture, the stencil |
| indices are ignored, and when retrieving a depth component |
| texture, the stencil indices obtained from the texture are |
| undefined. |
| |
| * Should anything be said about performance? |
| |
| RESOLVED: No, not in the spec. However, common sense should |
| apply. Apps should probably check that GL_DEPTH_BITS is 24 and |
| that GL_STENCIL_BITS is 8 before using either the new DrawPixels |
| or ReadPixels formats. CopyPixels is probably safe regardless of |
| the size of either buffer. The 24/8 format should probably only |
| be used with 24-bit depth textures. |
| |
| New Procedures and Functions |
| |
| None. |
| |
| New Tokens |
| |
| Accepted by the <format> parameter of DrawPixels, ReadPixels, |
| TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, |
| TexSubImage3D, and GetTexImage, and by the <type> parameter of |
| CopyPixels: |
| |
| DEPTH_STENCIL_NV 0x84F9 |
| |
| Accepted by the <type> parameter of DrawPixels, ReadPixels, |
| TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, |
| TexSubImage3D, and GetTexImage: |
| |
| UNSIGNED_INT_24_8_NV 0x84FA |
| |
| Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) |
| |
| Update the first paragraph on page 90 to say: |
| |
| "... If the GL is in color index mode and <format> is not one of |
| COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL_NV, |
| then the error INVALID_OPERATION occurs. If <type> is BITMAP and |
| <format> is not COLOR_INDEX or STENCIL_INDEX then the error |
| INVALID_ENUM occurs. If <format> is DEPTH_STENCIL_NV and <type> is |
| not UNSIGNED_INT_24_8_NV then the error INVALID_ENUM occurs. Some |
| additional constraints on the combinations of <format> and <type> |
| values that are accepted is discussed below." |
| |
| Add a row to Table 3.5 (page 91): |
| |
| type Parameter GL Type Special |
| ------------------------------------------------ |
| ... ... ... |
| UNSIGNED_INT_2_10_10_10_REV uint Yes |
| UNSIGNED_INT_24_8_NV uint Yes |
| |
| Add a row to Table 3.6 (page 92): |
| |
| Format Name Element Meaning and Order Target Buffer |
| ------------------------------------------------------------------ |
| ... ... ... |
| DEPTH_COMPONENT Depth Depth |
| DEPTH_STENCIL_NV Depth and Stencil Index Depth and Stencil |
| ... ... ... |
| |
| Add a row to Table 3.8 (page 94): |
| |
| type Parameter GL Type Components Pixel Formats |
| ------------------------------------------------------------------ |
| ... ... ... ... |
| UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA |
| UNSIGNED_INT_24_8_NV uint 2 DEPTH_STENCIL_NV |
| |
| Update the last paragraph on page 93 to say: |
| |
| "Calling DrawPixels with a <type> of UNSIGNED_BYTE_3_3_2, ..., |
| UNSIGNED_INT_2_10_10_10_REV, or UNSIGNED_INT_24_8_NV is a special |
| case in which all the components of each group are packed into a |
| single unsigned byte, unsigned short, or unsigned int, depending on |
| the type." |
| |
| Add the following diagram to Table 3.11 (page 97): |
| |
| UNSIGNED_INT_24_8_NV |
| |
| 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 |
| +----------------------------------+---------------+ |
| | 1st Component | 2nd Component | |
| +----------------------------------+---------------+ |
| |
| Add a row to Table 3.12 (page 98): |
| |
| Format | 1st 2nd 3rd 4th |
| -----------------+------------------------------- |
| ... | ... ... ... ... |
| BGRA | blue green red alpha |
| DEPTH_STENCIL_NV | depth stencil N/A N/A |
| |
| Add the following paragraph to the end of the section "Conversion to |
| floating-point" (page 99): |
| |
| "For groups of components that contain both standard components and |
| index elements, such as DEPTH_STENCIL_NV, the index elements are not |
| converted." |
| |
| Update the last paragraph in the section "Conversion to Fragments" |
| (page 100) to say: |
| |
| "... Groups arising from DrawPixels with a <format> of STENCIL_INDEX |
| or DEPTH_STENCIL_NV are treated specially and are described in |
| section 4.3.1." |
| |
| Update the first paragraph of section 3.6.5 "Pixel Transfer |
| Operations" (pages 100-101) to say: |
| |
| "The GL defines five kinds of pixel groups: |
| |
| 1. RGBA component: Each group comprises four color components: |
| red, green, blue, and alpha. |
| 2. Depth component: Each group comprises a single depth component. |
| 3. Color index: Each group comprises a single color index. |
| 4. Stencil index: Each group comprises a single stencil index. |
| 5. Depth/stencil: Each group comprises a depth component and a |
| stencil index." |
| |
| Update the first paragraph in the section "Arithmetic on Components" |
| (page 101) to say: |
| |
| "This step applies only to RGBA component and depth component groups |
| and the depth components in depth/stencil groups. ..." |
| |
| Update the first paragraph in the section "Arithmetic on Indices" |
| (page 101) to say: |
| |
| "This step applies only to color index and stencil index groups and |
| the stencil indices in depth/stencil groups. ..." |
| |
| Update the first paragraph in the section "Stencil Index Lookup" |
| (page 102) to say: |
| |
| "This step applies only to stencil index groups and the stencil |
| indices in depth/stencil groups. ..." |
| |
| Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment |
| Operations and the Frame Buffer) |
| |
| Replace section 4.3.1 "Writing to the Stencil Buffer" (page 156) with |
| the following: |
| |
| "4.3.1 Writing to the Stencil Buffer or to the Depth and Stencil |
| Buffers |
| |
| The operation of DrawPixels was described in section 3.6.4, except if |
| the <format> argument was STENCIL_INDEX or DEPTH_STENCIL_NV. In this |
| case, all operations described for DrawPixels take place, but window |
| (x,y) coordinates, each with the corresponding stencil index or depth |
| value and stencil index, are produced in lieu of fragments. Each |
| coordinate-data pair is sent directly to the per-fragment operations, |
| bypassing the texture, fog, and antialiasing application stages of |
| rasterization. Each pair is then treated as a fragment for purposes |
| of the pixel ownership and scissor tests; all other per-fragment |
| operations are bypassed. Finally, each stencil index is written to |
| its indicated location in the framebuffer, subject to the current |
| setting of StencilMask, and if a depth component is present, if the |
| setting of DepthMask is not FALSE, it is also written to the |
| framebuffer; the setting of DepthTest is ignored. |
| |
| The error INVALID_OPERATION results if there is no stencil buffer, or |
| if the <format> argument was DEPTH_STENCIL_NV, if there is no depth |
| buffer." |
| |
| Add the following paragraph after the second paragraph of the |
| section "Obtaining Pixels from the Framebuffer" (page 158): |
| |
| "If the <format> is DEPTH_STENCIL_NV, then values are taken from both |
| the depth buffer and the stencil buffer. If there is no depth buffer |
| or if there is no stencil buffer, the error INVALID_OPERATION |
| occurs. If the <type> parameter is not UNSIGNED_INT_24_8_NV, the |
| error INVALID_ENUM occurs." |
| |
| Update the third paragraph on page 159 to say: |
| |
| "If the GL is in RGBA mode, and <format> is one of RED, GREEN, BLUE, |
| ALPHA, RGB, RGBA, BGR, BGRA, LUMINANCE, or LUMINANCE_ALPHA, then red, |
| green, blue, and alpha values are obtained from the framebuffer |
| |
| Update the first sentence of the section "Conversion of RGBA values" |
| (page 159) to say: |
| |
| "This step applies only if the GL is in RGBA mode, and then only if |
| <format> is neither STENCIL_INDEX, DEPTH_COMPONENT, nor |
| DEPTH_STENCIL_NV." |
| |
| Update the section "Conversion of Depth values" (page 159) to say: |
| |
| "This step applies only if <format> is DEPTH_COMPONENT or |
| DEPTH_STENCIL_NV. Each element taken from the depth buffer is taken |
| to be a fixed-point value in [0,1] with m bits, where m is the number |
| of bits in the depth buffer (see section 2.10.1)." |
| |
| Add a row to Table 4.6 (page 160): |
| |
| type Parameter Index Mask |
| --------------------------------- |
| ... ... |
| INT 2^31-1 |
| UNSIGNED_INT_24_8_NV 2^8-1 |
| |
| Add the following paragraph to the end of the section "Final |
| Conversion" (page 160): |
| |
| "For a depth/stencil pair, first the depth component is clamped to |
| [0,1]. Then the appropriate conversion formula from Table 4.7 is |
| applied to the depth component, while the index is masked by the |
| value given in Table 4.6 or converted to a GL float data type if the |
| <type> is FLOAT." |
| |
| Add a row to Table 4.7 (page 161): |
| |
| type Parameter GL Type Component Conversion ... |
| ------------------------------------------------------------------ |
| ... ... ... |
| UNSIGNED_INT_2_10_10_10_REV uint c = (2^N - 1)f |
| UNSIGNED_INT_24_8_NV uint c = (2^N - 1)f (depth only) |
| |
| Update the second and third paragraphs of section 4.3.3 (page 162) to |
| say: |
| |
| "<type> is a symbolic constant that must be one of COLOR, STENCIL, |
| DEPTH, or DEPTH_STENCIL_NV, indicating that the values to be |
| transfered are colors, stencil values, depth values, or depth/stencil |
| pairs, respectively. The first four arguments have the same |
| interpretation as the corresponding arguments to ReadPixels. |
| |
| Values are obtained from the framebuffer, converted (if appropriate), |
| then subjected to the pixel transfer operations described in section |
| 3.6.5, just as if ReadPixels were called with the corresponding |
| arguments. If the <type> is STENCIL, DEPTH, or DEPTH_STENCIL_NV, |
| then it is as if the <format> for ReadPixels were STENCIL_INDEX, |
| DEPTH_COMPONENT, or DEPTH_STENCIL_NV, respectively. If the <type> is |
| COLOR, then if the GL is in RGBA mode, it is as if the <format> were |
| RGBA, while if the GL is in color index mode, it is as if the |
| <format> were COLOR_INDEX." |
| |
| Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and |
| State Requests) |
| |
| None. |
| |
| GLX Protocol |
| |
| None. |
| |
| Errors |
| |
| The error INVALID_ENUM is generated if DrawPixels or ReadPixels is |
| called where format is DEPTH_STENCIL_NV and type is not |
| UNSIGNED_INT_24_8_NV. |
| |
| The error INVALID_OPERATION is generated if DrawPixels or ReadPixels |
| is called where type is UNSIGNED_INT_24_8_NV and format is not |
| DEPTH_STENCIL_NV. |
| |
| The error INVALID_OPERATION is generated if DrawPixels or ReadPixels |
| is called where format is DEPTH_STENCIL_NV and there is not both a |
| depth buffer and a stencil buffer. |
| |
| The error INVALID_OPERATION is generated if CopyPixels is called |
| where type is DEPTH_STENCIL_NV and there is not both a depth buffer |
| and a stencil buffer. |
| |
| New State |
| |
| None. |
| |
| Revision History |
| |
| August 22, 2001 - Fixed a small typo in the updates to Section 4.3.3. |