Firefox Tomorrow

web api instance method

WebGLRenderingContext: readPixels() method

View on MDN ↗

Available in 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

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

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

SpecificationsStandards references are available on the canonical MDN page.

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.

See also