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
void gl.readPixels(x, y, width, height, format, type, pixels);
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.
- 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
- 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
.
Return value
None.
Errors thrown
- 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
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 9 | 12 | 4.0 (2.0) | 11 | 12 | 5.1 |
Feature | Android | Chrome for Android | Edge | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|---|---|
Basic support | ? | 25 | (Yes) | 4.0 (2.0) | 1.0 | ? | 12 | 8.0 |