14. Framebuffer Operations

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.

Code 14-1. glReadPixels Function
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.

Table 14-1. Formats That Can Be Specified for Reading

format

type

Format

Bits

GL_RGBA

GL_UNSIGNED_BYTE

RGBA8

32

GL_UNSIGNED_SHORT_4_4_4_4

RGBA4

16

GL_UNSIGNED_SHORT_5_5_5_1

RGBA5551

16

GL_RGB

GL_UNSIGNED_BYTE

RGB8

24

GL_UNSIGNED_SHORT_5_6_5

RGB565

16

GL_BGRA

GL_UNSIGNED_BYTE

BGRA8

32

GL_UNSIGNED_SHORT_4_4_4_4

BGRA4

16

GL_UNSIGNED_SHORT_5_5_5_1

BGRA5551

16

GL_LUMINANCE_ALPHA

GL_UNSIGNED_BYTE

LA8

16

GL_LUMINANCE

GL_UNSIGNED_BYTE

L8

8

GL_ALPHA

GL_UNSIGNED_BYTE

A8

8

GL_DEPTH_COMPONENT

GL_UNSIGNED_INT

Depth

32

GL_UNSIGNED_INT24_DMP

Depth

24

GL_UNSIGNED_SHORT

Depth

16

GL_UNSIGNED_BYTE

Depth

8

GL_STENCIL_INDEX

GL_UNSIGNED_BYTE

Stencil

8

GL_DEPTH24_STENCIL8_EXT

GL_UNSIGNED_INT

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.

Code 14-2. Definition of the glClear Function
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.

Table 14-2. Specifying the Buffers to Clear

mask

Buffer to Clear

GL_COLOR_BUFFER_BIT

Color buffer.

GL_DEPTH_BUFFER_BIT

Depth buffer.

GL_STENCIL_BUFFER_BIT

Stencil buffer. This must be specified together with GL_DEPTH_BUFFER_BIT.

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.

Code 14-3. Specifying the Clear Color
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.

Code 14-4. Specifying the Clear Depth
void glClearDepthf(GLclampf depth); 

The specified values are clamped between 0.0 and 1.0. The default value is 1.0.

14.4.3. Clear Stencil

You can use the glClearStencil() function to specify the value to use when clearing the stencil buffer.

Code 14-5. Specifying the Clear Stencil
void glClearStencil(GLint s); 

Specify a value between 0 and 255 to use for clear operations. The default value is 0.


CONFIDENTIAL