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.

备注： 此特性在 Web Worker 中可用。

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

参见

类型化数组