WebGLRenderingContext: readPixels() method
The WebGLRenderingContext.readPixels()
method of the WebGL API reads a block of pixels from a
specified rectangle of the current color framebuffer into a TypedArray
or a DataView
object.
Syntax
js
// WebGL1:
readPixels(x, y, width, height, format, type, pixels)
// WebGL2:
readPixels(x, y, width, height, format, type, offset)
readPixels(x, y, width, height, format, type, pixels)
readPixels(x, y, width, height, format, type, pixels, 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 object to read data into. The array type must match the type of the
type
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 (undefined
).
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.RGBA
. 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
js
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");
const 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