MDN self-hosted library · e01.org

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_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

  • : 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

Browser compatibility

See also