WebGLRenderingContext: readPixels() method
WebGL
WebGL
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
// 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_BYTEgl.UNSIGNED_SHORT_5_6_5gl.UNSIGNED_SHORT_4_4_4_4gl.UNSIGNED_SHORT_5_5_5_1gl.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
typeparameter:- Uint8Array for
gl.UNSIGNED_BYTE. - Uint16Array for
gl.UNSIGNED_SHORT_5_6_5,gl.UNSIGNED_SHORT_4_4_4_4, orgl.UNSIGNED_SHORT_5_5_5_1. - Float32Array for
gl.FLOAT.
- Uint8Array for
-
dstOffset - : Offset. Defaults to 0.
Return value
None (undefined).
Exceptions
- A
gl.INVALID_ENUMerror is thrown ifformatortypeis not an accepted value. - A
gl.INVALID_OPERATIONerror is thrown if typeisgl.UNSIGNED_SHORT_5_6_5andformatis notgl.RGB.typeisgl.UNSIGNED_SHORT_4_4_4_4andformatis notgl.RGBA.-
typedoes not match the typed array type ofpixels. -
A
gl.INVALID_FRAMEBUFFER_OPERATIONerror is thrown if the currently bound framebuffer is not framebuffer complete.
Examples
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