| 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 |
| James Helferty, NVIDIA Corporation |
| Antoine Chauveau, NVIDIA Corporation |
| |
| Status |
| |
| Complete. |
| |
| Version |
| |
| Last Modified Date: September 27, 2013 |
| NVIDIA Revision: 7.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 value BACK. If a |
| user-created FBO is bound, then ReadBufferNV accepts COLOR_ATTACHMENT0. |
| Additionally, if the NV_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 <pname> 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. <src> must be FRONT, BACK, |
| NONE, COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where <i> is the |
| index of the color attachment point. Otherwise, an INVALID_ENUM |
| error is generated. Further, the acceptable values for <src> 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 default framebuffer |
| 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, |
| <src> must be FRONT, BACK or NONE. If the requested buffer is |
| missing, the error INVALID_OPERATION is generated. If there is a default |
| framebuffer associated with the context, the initial setting for |
| READ_BUFFER_NV is BACK, otherwise it is NONE. |
| |
| When the GL is using a framebuffer object, <src> must be NONE, |
| COLOR_ATTACHMENT0, or COLOR_ATTACHMENTi_NV, where <i> 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 or if the GL is |
| using a framebuffer object (i.e., READ_FRAMEBUFFER_BINDING is non-zero) |
| and the read buffer selects an attachment that has no image attached. |
| |
| 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 ReadBufferNV. 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 <src> is FRONT, the error INVALID_ENUM is generated. |
| |
| Dependencies on NV_draw_buffers: |
| |
| If NV_draw_buffers is not supported, change all references to |
| "COLOR_ATTACHMENTi_NV, where <i> 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 <mode> |
| 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? |
| |
| Early drivers followed the precedent set by Issue 55 of the |
| EXT_framebuffer_object spec; ReadBufferNV() would cause an error if |
| a FBO was bound and the requested buffer did not exist. |
| |
| OpenGL ES 3.0 and OpenGL 4.3 allow it to pass. |
| |
| RESOLVED: Behavior should match OpenGL ES 3.0. Application developers |
| are cautioned that early Tegra drivers may exhibit the previous |
| behavior. |
| |
| 6. What should happen if COLOR_ATTACHMENT0, the default ReadBufferNV |
| is not bound and ReadBufferNV() gets called on this attachment? |
| |
| Behavior matches the resolution of Issue 5. |
| |
| 7. Version 6 of this specification isn't compatible with OpenGL ES 3.0. |
| For contexts without a back buffer, this extension makes FRONT the |
| default read buffer. ES 3.0 instead calls it BACK. |
| How can this be harmonized? |
| |
| RESOLVED: Update the specification to match ES 3.0 behavior. This |
| introduces a backwards incompatibility, but few applications are |
| expected to be affected. In the EGL ecosystem where ES 2.0 is |
| prevalent, only pixmaps have no backbuffer and their usage remains |
| limited. |
| |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- -------- --------- ------------------------------------- |
| 7 09/27/13 achauveau Harmonize BACK vs. FRONT selection |
| with GLES 3.0. |
| 6 07/11/13 jhelferty Changes in behavior to match GLES 3.0 |
| 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 dependencies 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. |
