WebGLRenderingContext.readPixels()

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.

WebGL API 的 WebGLRenderingContext.readPixels() 方法从当前的颜色帧缓冲（framebuffer）中读取指定矩形的像素矩阵并转换为 TypedArray 或 DataView 对象。

语法

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

参数

x

GLint 值，指定从矩形像素块的左下角读取的第一个水平像素。

y

GLint 值，指定从矩形像素块的左下角读取的第一个垂直像素。

width

GLsizei 值，指定矩形的宽度。

height

GLsizei 值，指定矩形的高度。

format

GLenum 值，指定像素数据的格式，可能的值有：

gl.ALPHA: 放弃红、绿、蓝通道读取 alpha 通道的数据。
gl.RGB: 放弃 alpha 通道，读取红、绿、蓝通道的数据。
gl.RGBA: 从颜色缓存区读取红、绿、蓝以及 alpha 通道的数据。

WebGL2 增加的

gl.RED
gl.RG
gl.RED_INTEGER
gl.RG_INTEGER
gl.RGB_INTEGER
gl.RGBA_INTEGER

type

GLenum 值，指定像素数据的数据类型，可能的值有：

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 增加的

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

用于读取数据的对象，必须与参数 type 的类型相匹配：

Uint8Array：gl.UNSIGNED_BYTE。
Uint16Array：gl.UNSIGNED_SHORT_5_6_5、gl.UNSIGNED_SHORT_4_4_4_4 或 gl.UNSIGNED_SHORT_5_5_5_1。
Float32Array：gl.FLOAT。

dstOffset 可选

偏移量，默认为 0。

返回值

无（undefined）。

异常

gl.INVALID_ENUM：如果 format 或 type 不是可接受的值，则会引发此错误。
gl.INVALID_OPERATION：抛出此错误可能的原因：
- type 是 gl.UNSIGNED_SHORT_5_6_5 且 format 不是 gl.RGB 。
- type 是 gl.UNSIGNED_SHORT_4_4_4_4 且 format 不是 gl.RGBA。
- type 与类型化数组 pixels 的类型不匹配。
gl.INVALID_FRAMEBUFFER_OPERATION：如果当前绑定的帧缓冲区未完成，则引发此错误。

示例

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

规范

Specification
WebGL Specification # 5.14.12

浏览器兼容性

BCD tables only load in the browser

参见

类型化数组