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.

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

Specification
WebGL Specification
# 5.14.12

Browser compatibility

BCD tables only load in the browser

See also