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)
Status
Koji Ashida, NVIDIA Corporation
Gregory Prisament, NVIDIA Corporation
Greg Roth, NVIDIA Corporation
Status
Draft
Version
Last Modified Date: June 07, 2011
NVIDIA Revision: 4.0
Number
XXX Unassigned XXX
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 <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 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,
<src> 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, <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.
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 <src> 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 <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?
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.