WebGLRenderingContext: readPixels() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Note: This feature is available in Web Workers.

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:

dstOffset Optional

Offset. Defaults to 0.

Return value

None (undefined).

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

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

See also