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