The WebGLRenderingContext.readPixels()
method of the WebGL API reads a block of pixels from a
specified rectangle of the current color framebuffer into an
ArrayBufferView
object.
Syntax
// WebGL1:
void gl.readPixels(x, y, width, height, format, type, pixels);
// WebGL2:
void gl.readPixels(x, y, width, height, format, type, GLintptr offset);
void gl.readPixels(x, y, width, height, format, type, ArrayBufferView pixels, GLuint dstOffset);
Parameters
- x
- A
GLint
specifying the first horizontal pixel that is read from the lower left corner of a rectangular block of pixels. - y
- A
GLint
specifying the first vertical pixel that is read from the lower left corner of a rectangular block of pixels. - width
- A
GLsizei
specifying the width of the rectangle. - height
- A
GLsizei
specifying the height of the rectangle. - format
- A
GLenum
specifying the format of the pixel data. Possible values:gl.ALPHA
: Discards the red, green and blue components and reads the alpha component.gl.RGB
: Discards the alpha components and reads the red, green and blue components.gl.RGBA
: Red, green, blue and alpha components are read from the color buffer.
WebGL2 adds
gl.RED
gl.RG
gl.RED_INTEGER
gl.RG_INTEGER
gl.RGB_INTEGER
gl.RGBA_INTEGER
- type
- A
GLenum
specifying the data type of the pixel data. Possible values:gl.UNSIGNED_BYTE
gl.UNSIGNED_SHORT_5_6_5
gl.UNSIGNED_SHORT_4_4_4_4
gl.UNSIGNED_SHORT_5_5_5_1
gl.FLOAT
WebGL2 adds
gl.BYTE
gl.UNSIGNED_INT_2_10_10_10_REV
gl.HALF_FLOAT
gl.SHORT
gl.UNSIGNED_SHORT
gl.INT
gl.UNSIGNED_INT
gl.UNSIGNED_INT_10F_11F_11F_REV
gl.UNSIGNED_INT_5_9_9_9_REV
- pixels
- An
ArrayBufferView
object to read data into. The array type must match the type of thetype
parameter.Uint8Array
forgl.UNSIGNED_BYTE
.Uint16Array
forgl.UNSIGNED_SHORT_5_6_5
,gl.UNSIGNED_SHORT_4_4_4_4
, orgl.UNSIGNED_SHORT_5_5_5_1
.Float32Array
forgl.FLOAT
.
dstOffset
Optional- Offset. Defaults to 0.
Return value
None.
Exceptions
- A
gl.INVALID_ENUM
error is thrown ifformat
ortype
is not an accepted value. - A
gl.INVALID_OPERATION
error is thrown iftype
isgl.UNSIGNED_SHORT_5_6_5
andformat
is notgl.RGB
.type
isgl.UNSIGNED_SHORT_4_4_4_4
andformat
is notgl.RGB
A.type
does not match the typed array type ofpixels
.
- A
gl.INVALID_FRAMEBUFFER_OPERATION
error is thrown if the currently bound framebuffer is not framebuffer complete.
Examples
var canvas = document.getElementById('canvas');
var gl = canvas.getContext('webgl');
var pixels = new Uint8Array(gl.drawingBufferWidth * gl.drawingBufferHeight * 4);
gl.readPixels(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
console.log(pixels); // Uint8Array
Specifications
Specification | Status | Comment |
---|---|---|
WebGL 1.0 The definition of 'readPixels' in that specification. |
Recommendation | Initial definition. |
OpenGL ES 2.0 The definition of 'glReadPixels' in that specification. |
Standard | Man page of the OpenGL API. |
Browser compatibility
BCD tables only load in the browser
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.