WebGLRenderingContext.readPixels()
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 if-
type
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 |
---|
WebGL Specification # 5.14.12 |
Browser compatibility
BCD tables only load in the browser