W3cubDocs

/Web APIs

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

// 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 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 (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

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

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet
`readPixels`	9	12	4	11	12	5.1	4.4.3	25	4	12	8	1.5