1Name 2 3 NV_read_buffer 4 NV_read_buffer_front 5 6Name Strings 7 8 GL_NV_read_buffer 9 GL_NV_read_buffer_front 10 11Contact 12 13 Greg Roth, NVIDIA Corporation (groth 'at' nvidia.com) 14 15Contributors 16 17 Koji Ashida, NVIDIA Corporation 18 Gregory Prisament, NVIDIA Corporation 19 Greg Roth, NVIDIA Corporation 20 James Helferty, NVIDIA Corporation 21 Antoine Chauveau, NVIDIA Corporation 22 23Status 24 25 Complete. 26 27Version 28 29 Last Modified Date: September 27, 2013 30 NVIDIA Revision: 7.0 31 32Number 33 34 OpenGL ES Extension #93 35 36Dependencies 37 38 Written against the OpenGL ES 2.0 Specification. 39 40 NV_draw_buffers affects this extension. 41 42Overview 43 44 Unextended OpenGL ES 2.0 only supports using ReadPixels to read from 45 the default color buffer of the currently-bound framebuffer. 46 However, it is useful for debugging to be able to read from 47 non-default color buffers. Particularly, when the NV_draw_buffers 48 extension is supported, each framebuffer may contain multiple color 49 buffers. This extension provides a mechanism to select which color 50 buffer to read from. 51 52 This document describes two extensions to allow an implementation to 53 support a subset of the total functionality. 54 55 The NV_read_buffer extension adds the command ReadBufferNV, which is 56 used to select which color buffer of the currently-bound framebuffer 57 to use as the source for subsequent calls to ReadPixels, 58 CopyTexImage2D, and CopyTexSubImage2D. If the system-provided 59 framebuffer is bound, then ReadBufferNV accepts value BACK. If a 60 user-created FBO is bound, then ReadBufferNV accepts COLOR_ATTACHMENT0. 61 Additionally, if the NV_draw_buffers extension is supported, 62 ReadBufferNV accepts COLOR_ATTACHMENTn_NV (n is 0 to 15). 63 64 The NV_read_buffer_front extension requires NV_read_buffer and adds 65 the ability to select the system-provided FRONT color buffer as the 66 source for read operations when the system-provided framebuffer is 67 bound and contains both a front and back buffer. 68 69New Procedures and Functions 70 71 void ReadBufferNV(GLenum mode) 72 73New Tokens 74 75 Accepted by the <pname> parameter of GetIntegerv: 76 77 READ_BUFFER_NV 0x0C02 78 79Changes to Chapter 4 of the OpenGL ES 2.0 Specification 80(Per-Fragment Operations and the Framebuffer) 81 82 Section 4.3.1 (Reading Pixels), subsection "Obtaining Pixels from 83 the Framebuffer" add: 84 85 For color formats, the read buffer from which values are obtained 86 is one of the color buffers; the selection of color buffer for the 87 bound framebuffer object is controlled with ReadBufferNV. 88 89 The command 90 91 void ReadBufferNV(enum src); 92 93 takes a symbolic constant as argument. <src> must be FRONT, BACK, 94 NONE, COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where <i> is the 95 index of the color attachment point. Otherwise, an INVALID_ENUM 96 error is generated. Further, the acceptable values for <src> depend 97 on whether the GL is using the default framebuffer (i.e. 98 FRAMEBUFFER_BINDING is zero), or a framebuffer object (i.e. 99 FRAMEBUFFER_BINDING is non-zero) and whether the default framebuffer 100 is single or double buffered. For more information about framebuffer 101 objects, see section 4.4. 102 103 If the object bound to FRAMEBUFFER_BINDING is not framebuffer 104 complete (as defined in section 4.4.5), then ReadPixels generates 105 the error INVALID_FRAMEBUFFER_OPERATION. If ReadBufferNV is supplied 106 with a constant that is neither legal for the default framebuffer, 107 nor legal for a framebuffer object, then the error INVALID_ENUM 108 results. 109 110 When FRAMEBUFFER_BINDING is zero, i.e. the default framebuffer, 111 <src> must be FRONT, BACK or NONE. If the requested buffer is 112 missing, the error INVALID_OPERATION is generated. If there is a default 113 framebuffer associated with the context, the initial setting for 114 READ_BUFFER_NV is BACK, otherwise it is NONE. 115 116 When the GL is using a framebuffer object, <src> must be NONE, 117 COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where <i> is the index 118 of the color attachment point. Specifying COLOR_ATTACHMENT0 or 119 COLOR_ATTACHMENTi_NV enables reading from the image attached to the 120 framebuffer at COLOR_ATTACHMENTi_NV. For framebuffer objects, the 121 initial setting for READ_BUFFER_NV is COLOR_ATTACHMENT0. 122 123 ReadPixels generates an INVALID_OPERATION error if it attempts to 124 select a color buffer while READ_BUFFER_NV is NONE or if the GL is 125 using a framebuffer object (i.e., READ_FRAMEBUFFER_BINDING is non-zero) 126 and the read buffer selects an attachment that has no image attached. 127 128 Section 4.3.2 (Pixel Draw/Read State) Replace first paragraph: 129 130 The state required for pixel operations consists of the parameters 131 that are set with PixelStore. This state has been summarized in 132 tables 3.1. Additional state includes an integer indicating the 133 current setting of ReadBufferNV. State set with PixelStore is GL 134 client state. 135 136 137Dependencies on NV_read_buffer_front: 138 139 If NV_read_buffer_front is not supported, add to the third paragraph 140 describing ReadBufferNV: 141 142 If <src> is FRONT, the error INVALID_ENUM is generated. 143 144Dependencies on NV_draw_buffers: 145 146 If NV_draw_buffers is not supported, change all references to 147 "COLOR_ATTACHMENTi_NV, where <i> is the index of the color attachment 148 point" or simply "COLOR_ATTACHMENTi_NV" to "COLOR_ATTACHMENT0". 149 150New State 151 152 Add Table 6.X Framebuffer (State per framebuffer object): 153 154 State Type Get Command Initial Value Description 155 --------------- ---- ------------ ------------- ----------- 156 READ_BUFFER_NV Z10* GetIntegerv see 4.2.1 Read source buffer 157 158Issues 159 160 1. Should we use ReadBufferNV to specify whether ReadPixels reads 161 from the window system provided framebuffer or FBO? 162 163 No. The switching is automatic with FBO binding. The read buffer 164 state belongs to the rendering surface, so switching the rendering 165 surface automatically switches which read buffer to use. 166 167 This is consistent with the behavior of OpenGL 2.0 with the 168 ARB_framebuffer_object extension and unextended OpenGL 3.0. 169 170 2. Should we have FRONT/BACK, LEFT/RIGHT buffer enums for <mode> 171 parameter of ReadBufferNV to be used with window system provided 172 framebuffers? 173 174 OpenGL ES 2.0 does not support stereo framebuffers, so for now we 175 only support FRONT and BACK. 176 177 3. Why separate NV_read_buffer and NV_read_buffer_front? 178 179 SUGGESTION: Some platforms, such as those with a compositing 180 window system, may be unable to read from the front buffer. 181 However, we would like to allow these platforms to read from any 182 of the buffers drawn to using the NV_draw_buffers extension. 183 184 4. Should this extension allow reading from depth and stencil buffers? 185 186 While originally part of this document, support for reading from 187 depth and stencil buffers has been moved to the 188 NV_read_depth_stencil extension. It is clearer to devote one 189 document to the re-introduction of ReadBuffer, and a separate 190 document to legalizing new format and type combinations for 191 ReadPixels. 192 193 5. Should ReadBufferNV() pass if READ_BUFFER points to a non- 194 existent buffer? 195 196 Early drivers followed the precedent set by Issue 55 of the 197 EXT_framebuffer_object spec; ReadBufferNV() would cause an error if 198 a FBO was bound and the requested buffer did not exist. 199 200 OpenGL ES 3.0 and OpenGL 4.3 allow it to pass. 201 202 RESOLVED: Behavior should match OpenGL ES 3.0. Application developers 203 are cautioned that early Tegra drivers may exhibit the previous 204 behavior. 205 206 6. What should happen if COLOR_ATTACHMENT0, the default ReadBufferNV 207 is not bound and ReadBufferNV() gets called on this attachment? 208 209 Behavior matches the resolution of Issue 5. 210 211 7. Version 6 of this specification isn't compatible with OpenGL ES 3.0. 212 For contexts without a back buffer, this extension makes FRONT the 213 default read buffer. ES 3.0 instead calls it BACK. 214 How can this be harmonized? 215 216 RESOLVED: Update the specification to match ES 3.0 behavior. This 217 introduces a backwards incompatibility, but few applications are 218 expected to be affected. In the EGL ecosystem where ES 2.0 is 219 prevalent, only pixmaps have no backbuffer and their usage remains 220 limited. 221 222 223Revision History 224 225 Rev. Date Author Changes 226 ---- -------- --------- ------------------------------------- 227 7 09/27/13 achauveau Harmonize BACK vs. FRONT selection 228 with GLES 3.0. 229 6 07/11/13 jhelferty Changes in behavior to match GLES 3.0 230 5 06/07/11 groth Responded to feedback. Clarified 231 non-FBO behavior and state ownership. 232 added a few issues. 233 4 06/01/11 groth Mostly rewrote spec edits to better 234 match the spec and more clearly 235 describe behavior. 236 3 03/22/09 gprisament Split depth & stencil reading into 237 separate document 238 (NV_read_depth_stencil). 239 Inline dependencies on NV_draw_buffers 240 Re-wrote overview section. 241 2 07/03/08 kashida Change to depend on 242 NV_packed_depth_stencil2 243 1 06/10/07 kashida First revision. 244