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 the type parameter.

• Uint8Array for gl.UNSIGNED_BYTE.
• Uint16Array for gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4, or gl.UNSIGNED_SHORT_5_5_5_1.
• Float32Array for gl.FLOAT.

dstOffset Optional

Offset. Defaults to 0.

Return value

None.

Exceptions

• A gl.INVALID_ENUM error is thrown if format or type is not an accepted value.
• A gl.INVALID_OPERATION error is thrown if
  • type is gl.UNSIGNED_SHORT_5_6_5 and format is not gl.RGB.
  • type is gl.UNSIGNED_SHORT_4_4_4_4 and format is not gl.RGBA.
  • type does not match the typed array type of pixels.
• 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

Browser compatibility

See also

• Typed Arrays