Framebuffer operations read, copy, and otherwise manipulate framebuffer data.
The features supported by the 3DS system are restricted as follows.
- The
glDrawBuffer()
function has not been implemented. - The
glReadBuffer()
function has not been implemented. - The
glDrawPixels()
function has not been implemented. - The
glReadPixels()
function can get the contents of the color, depth, and stencil buffers. - The
glCopyPixels()
function has not been implemented. - The
glPixelStore*()
functions have not been implemented.
14.1. Reading Pixels
You can use the glReadPixels()
function to take the contents of a render buffer (the color, depth, or stencil buffer) bound to the framebuffer and place it into memory. You can also read the contents of the depth and stencil buffers into memory, using a combined format.
void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, void* pixels);
For x
and y
, specify the starting coordinates (the lower-left corner) of the rectangular region to capture. For width
and height
, specify the width and height of the rectangular region. A GL_INVALID_VALUE
error is generated if any of these values are negative. A GL_INVALID_OPERATION
error is generated when the sum of x
and width
exceeds the render buffer width, or when the sum of y
and height
exceeds the render buffer height.
Using a combination of format
and type
, you can specify the format of the image to capture.
format |
type |
Format |
Bits |
---|---|---|---|
|
|
RGBA8 |
32 |
|
RGBA4 |
16 |
|
|
RGBA5551 |
16 |
|
|
|
RGB8 |
24 |
|
RGB565 |
16 |
|
|
|
BGRA8 |
32 |
|
BGRA4 |
16 |
|
|
BGRA5551 |
16 |
|
|
|
LA8 |
16 |
|
|
L8 |
8 |
|
|
A8 |
8 |
|
|
Depth |
32 |
|
Depth |
24 |
|
|
Depth |
16 |
|
|
Depth |
8 |
|
|
|
Stencil |
8 |
|
|
Depth + Stencil |
32 |
A GL_INVALID_ENUM
error is generated if you specify a combination that is not in the table.
The captured image is stored in pixels
, using the specified format.
Images taken from the color buffer are stored in linear format, using a pixel byte order that is OpenGL-compliant.
Images read from the depth buffer are also stored in linear format, but the pixel data is ordered starting with the least-significant bits. For example, an image captured using a 24-bit format is stored in memory one byte at a time, starting with the least-significant byte and ending with the most-significant byte.
Images read from the stencil buffer are stored in linear format, with one byte per pixel.
Images read from the depth and stencil buffers in a combined format are also stored in linear format, but the pixel data is ordered starting with the least-significant bits. 24 bits of depth data are stored first, one byte at a time, from the least-significant to the most-significant byte, followed by 8 bits of stencil data.
A GL_INVALID_FRAMEBUFFER_OPERATION
error is generated if an error related to the framebuffer occurs (for example, if a color buffer has not been bound to the framebuffer). A GL_OUT_OF_MEMORY
error is generated when temporary memory fails to be allocated within the library.
14.2. Copying Pixels
The glCopyPixels()
function does not support copying data to other framebuffers.
You can call the glCopyTexImage2D()
and glCopyTexSubImage2D()
functions to copy the content of the color buffer to a texture. For more information, see 7.5.1. Copying From the Color Buffer.
14.3. Texture Rendering
You can bind a texture to the framebuffer as a render buffer. For more information, see 7.6. Specifying a Texture as the Render Target.
14.4. Clearing the Framebuffer
In OpenGL, the scissor test and masking affect how the glClear()
function clears (every buffer bound to) the framebuffer. On a 3DS system, however, the scissor test and masking are not included in the graphics pipeline and have no effect.
You can bind three render buffers to the framebuffer, as explained in 3.3.1. Render Buffer Allocation: a color buffer (which could be a texture or a buffer used to render gas), a depth buffer, and a stencil buffer. Index colors are not supported.
To clear a buffer, call the glClear()
function with the buffer's corresponding bit specified as an argument.
void glClear(GLbitfield mask);
You can specify the following values as a bit field in mask
. To clear multiple buffers simultaneously, specify the bit field using bitwise OR operations.
mask |
Buffer to Clear |
---|---|
|
Color buffer. |
|
Depth buffer. |
|
Stencil buffer. This must be specified together with |
You cannot clear the 3DS stencil buffer alone because it is combined with the depth buffer (GL_DEPTH24_STENCIL8_EXT
).
14.4.1. Clear Color
You can use the glClearColor()
function to specify the color to use when clearing the color buffer.
void glClearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha);
Each of the specified color components is clamped between 0.0 and 1.0. By default, all components are set to 0.0.
14.4.2. Clear Depth
You can use the glClearDepthf()
function to specify the depth value to use when clearing the depth buffer.
void glClearDepthf(GLclampf depth);
The specified values are clamped between 0.0 and 1.0. The default value is 1.0.