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.0The definition of 'readPixels' in that specification. | Recommendation | Initial definition. |
OpenGL ES 2.0The definition of 'glReadPixels' in that specification. | Standard | Man page of the OpenGL API. |
Browser compatibility
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.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
readPixels
|
Chrome
Full support 9 |
Edge
Full support 12 |
Firefox
Full support 4 |
IE
Full support 11 |
Opera
Full support 12 |
Safari
Full support 5.1 |
WebView Android
Full support Yes |
Chrome Android
Full support 25 |
Firefox Android
Full support Yes |
Opera Android
Full support 12 |
Safari iOS
Full support 8 |
Samsung Internet Android
Full support 1.5 |
WebGL2
|
Chrome
Full support 56 |
Edge
Full support 79 |
Firefox
Full support 51 |
IE
No support No |
Opera
Full support 43 |
Safari
No support No |
WebView Android
Full support 58 |
Chrome Android
Full support 58 |
Firefox Android
Full support 51 |
Opera Android
Full support 43 |
Safari iOS
No support No |
Samsung Internet Android
Full support 7.0 |
Legend
- Full support
- Full support
- No support
- No support
See also
WebGLRenderingContext.readPixels() by Mozilla Contributors is licensed under CC-BY-SA 2.5.