Name NV_read_buffer NV_read_buffer_front Name Strings GL_NV_read_buffer GL_NV_read_buffer_front Contact Greg Roth, NVIDIA Corporation (groth 'at' nvidia.com) Contributors Koji Ashida, NVIDIA Corporation Gregory Prisament, NVIDIA Corporation Greg Roth, NVIDIA Corporation Status Complete. Version Last Modified Date: June 07, 2011 NVIDIA Revision: 4.0 Number OpenGL ES Extension #93 Dependencies Written against the OpenGL ES 2.0 Specification. NV_draw_buffers affects this extension. Overview Unextended OpenGL ES 2.0 only supports using ReadPixels to read from the default color buffer of the currently-bound framebuffer. However, it is useful for debugging to be able to read from non-default color buffers. Particularly, when the NV_draw_buffers extension is supported, each framebuffer may contain multiple color buffers. This extension provides a mechanism to select which color buffer to read from. This document describes two extensions to allow an implementation to support a subset of the total functionality. The NV_read_buffer extension adds the command ReadBufferNV, which is used to select which color buffer of the currently-bound framebuffer to use as the source for subsequent calls to ReadPixels, CopyTexImage2D, and CopyTexSubImage2D. If the system-provided framebuffer is bound, then ReadBufferNV accepts BACK if there's a back buffer and FRONT if there's not. If a user-created FBO is bound, then ReadBufferNV accepts COLOR_ATTACHMENT0. Additionally, if the ARB_draw_buffers extension is supported, ReadBufferNV accepts COLOR_ATTACHMENTn_NV (n is 0 to 15). The NV_read_buffer_front extension requires NV_read_buffer and adds the ability to select the system-provided FRONT color buffer as the source for read operations when the system-provided framebuffer is bound and contains both a front and back buffer. New Procedures and Functions void ReadBufferNV(GLenum mode) New Tokens Accepted by the parameter of GetIntegerv: READ_BUFFER_NV 0x0C02 Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment Operations and the Framebuffer) Section 4.3.1 (Reading Pixels), subsection "Obtaining Pixels from the Framebuffer" add: For color formats, the read buffer from which values are obtained is one of the color buffers; the selection of color buffer for the bound framebuffer object is controlled with ReadBufferNV. The command void ReadBufferNV(enum src); takes a symbolic constant as argument. must be FRONT, BACK, NONE, COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where is the index of the color attachment point. Otherwise, an INVALID_ENUM error is generated. Further, the acceptable values for depend on whether the GL is using the default framebuffer (i.e. FRAMEBUFFER_BINDING is zero), or a framebuffer object (i.e. FRAMEBUFFER_BINDING is non-zero) and whether the context is single or double buffered. For more information about framebuffer objects, see section 4.4. If the object bound to FRAMEBUFFER_BINDING is not framebuffer complete (as defined in section 4.4.5), then ReadPixels generates the error INVALID_FRAMEBUFFER_OPERATION. If ReadBufferNV is supplied with a constant that is neither legal for the default framebuffer, nor legal for a framebuffer object, then the error INVALID_ENUM results. When FRAMEBUFFER_BINDING is zero, i.e. the default framebuffer, must be FRONT, BACK or NONE. If the requested buffer is missing, the error INVALID_OPERATION is generated. For the default framebuffer, the initial setting for READ_BUFFER_NV is FRONT if there is no back buffer and BACK otherwise. When the GL is using a framebuffer object, must be NONE, COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where is the index of the color attachment point. Specifying COLOR_ATTACHMENT0 or COLOR_ATTACHMENTi_NV enables reading from the image attached to the framebuffer at COLOR_ATTACHMENTi_NV. For framebuffer objects, the initial setting for READ_BUFFER_NV is COLOR_ATTACHMENT0. ReadPixels generates an INVALID_OPERATION error if it attempts to select a color buffer while READ_BUFFER_NV is NONE. Section 4.3.2 (Pixel Draw/Read State) Replace first paragraph: The state required for pixel operations consists of the parameters that are set with PixelStore. This state has been summarized in tables 3.1. Additional state includes an integer indicating the current setting of ReadBuffer. For the default framebuffer, in the initial state the read buffer is BACK if there is a back buffer; FRONT if there is no back buffer; and NONE if no default framebuffer is associated with the context. State set with PixelStore is GL client state. Dependencies on NV_read_buffer_front: If NV_read_buffer_front is not supported, add to the third paragraph describing ReadBufferNV: If is FRONT and the context is double buffered, the error INVALID_OPERATION is generated. Dependencies on NV_draw_buffers: If NV_draw_buffers is not supported, change all references to "COLOR_ATTACHMENTi_NV, where is the index of the color attachment point" or simply "COLOR_ATTACHMENTi_NV" to "COLOR_ATTACHMENT0". New State Add Table 6.X Framebuffer (State per framebuffer object): State Type Get Command Initial Value Description --------------- ---- ------------ ------------- ----------- READ_BUFFER_NV Z10* GetIntegerv see 4.2.1 Read source buffer Issues 1. Should we use ReadBufferNV to specify whether ReadPixels reads from the window system provided framebuffer or FBO? No. The switching is automatic with FBO binding. The read buffer state belongs to the rendering surface, so switching the rendering surface automatically switches which read buffer to use. This is consistent with the behavior of OpenGL 2.0 with the ARB_framebuffer_object extension and unextended OpenGL 3.0. 2. Should we have FRONT/BACK, LEFT/RIGHT buffer enums for parameter of ReadBufferNV to be used with window system provided framebuffers? OpenGL ES 2.0 does not support stereo framebuffers, so for now we only support FRONT and BACK. 3. Why separate NV_read_buffer and NV_read_buffer_front? SUGGESTION: Some platforms, such as those with a compositing window system, may be unable to read from the front buffer. However, we would like to allow these platforms to read from any of the buffers drawn to using the NV_draw_buffers extension. 4. Should this extension allow reading from depth and stencil buffers? While originally part of this document, support for reading from depth and stencil buffers has been moved to the NV_read_depth_stencil extension. It is clearer to devote one document to the re-introduction of ReadBuffer, and a separate document to legalizing new format and type combinations for ReadPixels. 5. Should ReadBufferNV() pass if READ_BUFFER points to a non- existent buffer? As specified in issue 55 of EXT_framebuffer_object spec, ReadBufferNV() should throw an error if the buffer does not exist. 6. What should happen if COLOR_ATTACHMENT0, the default ReadBufferNV is not bound and ReadBufferNV() gets called on this attachment? For the same reason as described in issue 55 of EXT_framebuffer_- object spec, if this happens ReadBufferNV() will fail with an INVALID_OPERATION error. Revision History Rev. Date Author Changes ---- -------- --------- ------------------------------------- 5 06/07/11 groth Responded to feedback. Clarified non-FBO behavior and state ownership. added a few issues. 4 06/01/11 groth Mostly rewrote spec edits to better match the spec and more clearly describe behavior. 3 03/22/09 gprisament Split depth & stencil reading into separate document (NV_read_depth_stencil). Inline depenencies on NV_draw_buffers Re-wrote overview section. 2 07/03/08 kashida Change to depend on NV_packed_depth_stencil2 1 06/10/07 kashida First revision.