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
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.
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