1Name 2 3 NV_read_depth 4 NV_read_stencil 5 NV_read_depth_stencil 6 7Name Strings 8 9 GL_NV_read_depth 10 GL_NV_read_stencil 11 GL_NV_read_depth_stencil 12 13Contact 14 15 Greg Roth, NVIDIA Corporation (groth 'at' nvidia.com) 16 17Contributors 18 19 Koji Ashida, NVIDIA Corporation 20 Gregory Prisament, NVIDIA Corporation 21 Greg Roth, NVIDIA Corporation 22 23Status 24 25 Complete. 26 27Version 28 29 Last Modified Date: June 07, 2011 30 NVIDIA Revision: 4.0 31 32Number 33 34 OpenGL ES Extension #94 35 36Dependencies 37 38 Written against the OpenGL ES 2.0 Specification. 39 40 NV_depth_buffer_float2 affects this extension. 41 42 NV_read_depth_stencil requires OES_packed_depth_stencil. 43 44Overview 45 46 Unextended OpenGL-ES 2.0 only supports using ReadPixels to read from the 47 default color buffer of the currently-bound framebuffer. However, it is 48 useful for debugging to be able to read from depth and stencil buffers. 49 This extension re-introduces these features into OpenGL-ES 2.0. 50 51 This document describes several extensions in order to allow an 52 implementation to support a subset of the total functionality. 53 54 The NV_read_depth extension allows reading from the depth buffer using 55 ReadPixels. 56 57 The NV_read_stencil extension allows reading from the stencil buffer using 58 ReadPixels. 59 60 The NV_read_depth_stencil extension allows reading from packed 61 depth-stencil buffers using ReadPixels. 62 63 64New Procedures and Functions 65 66 None. 67 68New Tokens 69 70 None. 71 72Changes to Chapter 4 of the OpenGL ES 2.0 Specification 73(Per-Fragment Operations and the Framebuffer) 74 75 76 Section 4.3.1 (Reading Pixels), replace description of ReadPixels: 77 78 The arguments after x and y to ReadPixels are those described in 79 section 3.6.2 defining pixel rectangles. The pixel storage modes 80 that apply to ReadPixels are summarized in Table 4.3. 81 82 Section 4.3.1 (Reading Pixels) subsection "Obtaining Pixels from 83 the Framebuffer", replace the first paragraph with: 84 85 If the <format> is DEPTH_COMPONENT, then values are obtained 86 from the depth buffer. If there is no depth buffer, the error 87 INVALID_OPERATION occurs. If the <type> is not UNSIGNED_SHORT, 88 FLOAT, or UNSIGNED_INT_24_8_OES then the error INVALID_ENUM 89 occurs. If the <type> is FLOAT and the depth buffer is not a 90 float buffer, an INVALID_OPERATION error occurs. If the <type> 91 is UNSIGNED_SHORT or UNSIGNED_INT_24_8_OES and the depth buffer 92 is a float buffer, an INVALID_OPERATION error occurs. When the 93 <type> is UNSIGNED_INT_24_8_OES the values read into the 8 94 stencil bits are undefined. 95 96 If the <format> is DEPTH_STENCIL_OES, then values are taken from 97 both the depth buffer and the stencil buffer. If there is no 98 depth buffer or if there is no stencil buffer, then the error 99 INVALID_OPERATION occurs. If the <type> is not UNSIGNED_INT_24_- 100 8_OES or FLOAT_32_UNSIGNED_INT_24_8_REV_NV, then the error 101 INVALID_ENUM occurs. If the <type> is FLOAT_32_UNSIGNED_INT_24_- 102 8_REV_NV and the depth buffer is not a float buffer, an INVALID_- 103 OPERATION error occurs. If the <type> is UNSIGNED_INT_24_8_OES 104 and the depth buffer is a float buffer, an INVALID_OPERATION 105 error occurs. 106 107 If the <format> is STENCIL_INDEX, then values are taken from 108 the stencil buffer. If there is no stencil buffer, then the 109 error INVALID_OPERATION occurs. If the <type> is not 110 UNSIGNED_BYTE, then the error INVALID_ENUM occurs. 111 112 If <format> is a color format, then red, green, blue, and alpha 113 values are obtained from the color buffer at each pixel 114 location. If the framebuffer does not support alpha values then 115 the value that is obtained is 1.0. Only two combinations of 116 color format and type are accepted. The first is format RGBA and 117 type UNSIGNED_BYTE. The second is an implementation-chosen 118 format from among those defined in table 3.4, excluding formats 119 LUMINANCE and LUMINANCE_ALPHA. The values of format and type for 120 this format may be determined by calling GetIntegerv with the 121 symbolic constants IMPLEMENTATION_COLOR_READ_FORMAT and 122 IMPLEMENTATION_COLOR_READ_TYPE, respectively. The implementation- 123 chosen format may vary depending on the format of the currently 124 bound rendering surface. Unsupported combinations of format and 125 type will generate an INVALID_OPERATION error. 126 127Dependencies on NV_read_depth: 128 129 If NV_read_depth is not supported, the paragraph in "Obtaining Pixels 130 from the Framebuffer" describing behavior when the <format> is 131 DEPTH_COMPONENT is omitted. 132 133Dependencies on NV_read_stencil: 134 135 If NV_read_stencil is not supported, the paragraph in "Obtaining 136 Pixels from the Framebuffer" describing behavior "when the <format> 137 is STENCIL_INDEX" is omitted. 138 139Dependencies on NV_read_depth_stencil: 140 141 If NV_read_depth_stencil is not supported, the paragraph in 142 "Obtaining Pixels from the Framebuffer" describing behavior "when 143 the <format> is DEPTH_STENCIL_OES is omitted and UNSIGNED_INT_24_8_EXT is not an 144 accepted <value> when <format> is DEPTH_COMPONENT. 145 146Dependencies on NV_depth_buffer_float2: 147 148 If NV_depth_buffer_float2 is not supported, FLOAT is not an accepted 149 <value> when <format> is DEPTH_COMPONENT and FLOAT_32_UNSIGNED_INT_- 150 24_8_REV_NV is not an accepted <value> when <format> is DEPTH_- 151 STENCIL_OES. 152 153Issues 154 155 1. Do we need to be able to read stencil buffers individually? 156 157 On platforms that easily support reading stencil buffers 158 individually, it is useful for debugging. However, we do not want 159 to require that it is supported on platforms using packed depth- 160 stencil buffers. Therefore we use multiple extension names. 161 162 2. Should we have FRONT/BACK, LEFT/RIGHT buffer enums for <mode> 163 parameter of ReadBufferNV to be used with window system provided 164 framebuffers? 165 166 OpenGL ES 2.0 does not support stereo framebuffers, so for now we 167 only support FRONT and BACK. 168 169 3. Should this extension add reading of coverage samples? 170 171 No. That should be left to the EGL_NV_coverage_sample 172 specification. 173 174 4. How does this extension interact with NV_read_buffer? 175 176 NV_read_buffer adds support for the ReadBufferNV command, which is 177 used to select which color buffer to read from. It does not 178 affect the behavior of this extension, since all framebuffers have 179 at most one depth and one stencil buffer. 180 181 182Revision History 183 184 Rev. Date Author Changes 185 ---- -------- --------- ------------------------------------- 186 4 06/01/11 groth Mostly rewrote spec edits to better 187 match the spec and more clearly 188 describe behavior. Reformatted. 189 3 03/22/09 gprisament Split from NV_read_buffer. 190 Broken into several extension names. 191 Re-wrote overview section. 192 2 07/03/08 kashida Change to depend on 193 NV_packed_depth_stencil2 194 1 06/10/07 kashida First revision. 195 196