glReadPixels Function

GL_APICALL void GL_APIENTRY glReadPixels(
     GLint x,
     GLint y,
     GLsizei width,
     GLsizei height,
     GLenum format,
     GLenum type,
     void * pixels
);

	Name	Description
in	x	X coordinate of the lower-left corner of the rectangular region to read from the render buffer
in	y	Y coordinate of the lower-left corner of the rectangular region to read from the render buffer
in	width	Width of the rectangular region to read
in	height	Height of the rectangular region to read
in	format	Format of stored pixel data
in	type	Type of stored pixel data
out	pixels	Array storing the pixel data

There is no return value.

Reads pixel data from a rectangular region in the current render buffer.

Set x to the x coordinate of the lower-left corner of the rectangular region to read from the render buffer. Set y to the y coordinate of the lower-left corner of the rectangular region to read from the render buffer.

Set width equal to the width of the rectangular region to read. Set height equal to the height of the rectangular region to read.

Use format and type to configure the format of the data to read. The following combinations can be used.

format	type
GL_RGBA	GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_5_5_5_1
GL_RGB	GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5
GL_BGRA	GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_5_5_5_1
GL_LUMINANCE_ALPHA	GL_UNSIGNED_BYTE
GL_LUMINANCE	GL_UNSIGNED_BYTE
GL_ALPHA	GL_UNSIGNED_BYTE
GL_DEPTH_COMPONENT	GL_UNSIGNED_INT, GL_UNSIGNED_INT24_DMP, GL_UNSIGNED_SHORT, GL_UNSIGNED_BYTE
GL_STENCIL_INDEX	GL_UNSIGNED_BYTE
GL_DEPTH24_STENCIL8_EXT	GL_UNSIGNED_INT

The pixel data is read into pixels.

Use glRenderBlockModeDMP to set the block mode. Make sure the same block mode is configured when rendering the color buffer and when using this function to read the color buffer. You cannot get the content of the color buffer correctly when the block modes differ.

Each pixel's depth value is read from the depth buffer in order starting with the least-significant bits. When type is GL_UNSIGNED_INT24_DMP, for example, three bytes are obtained for a single pixel in order from the least-significant to the most-significant eight bits. If the depth value is actually rendered with a different bit width than the type setting, the obtained value is converted for use with the type setting.

When reading the content of a stencil buffer, the format of the current depth buffer must be GL_DEPTH24_STENCIL8_EXT. When format is GL_STENCIL_INDEX, each pixel stencil value is read into each byte of pixels (where 1 byte corresponds to 1 pixel). When the format argument is GL_DEPTH24_STENCIL8_EXT each pixel is read into 4 bytes as follows: the least-significant 8 bits of the depth value, the middle 8 bits, the most-significant 8 bits of the depth value, the 8-bit stencil value.

The following errors occur in this function.

GL_INVALID_OPERATION	The x or y argument is negative; the sum of x and width is greater than the width (in pixels) of the color buffer; or the sum of y and height is greater than the height (in pixels) of the color buffer.
GL_INVALID_FRAMEBUFFER_OPERATION	The framebuffer was configured incorrectly.
GL_INVALID_VALUE	The width or height argument is negative.
GL_INVALID_ENUM	Invalid combination of format and type.
GL_OUT_OF_MEMORY	Failed to allocate temporary memory that is used internally.

2010/11/01

Corrected the text.

2010/08/12

Added description of how stencil buffer is read. Revised description of error occurring for invalid combinations for the format and type arguments.

2010/06/09

Added information on support for reading from the depth buffer.

2010/01/07

Initial version.