WebGLRenderingContext: readPixels() 方法

基线 广泛可用

此功能非常成熟，可在许多设备和浏览器版本上正常运行。自 2015 年 7 月.

报告反馈

语法

WebGLRenderingContext.readPixels() 方法是 WebGL API 的一部分，它将当前颜色帧缓冲区中指定矩形的像素块读入 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)

js

参数

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

从颜色缓冲区读取红色、绿色、蓝色和 alpha 分量。

  • gl.FLOAT
  • 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）。

  • 异常
  • 如果 format 或 type 不是可接受的值，则会抛出 gl.INVALID_ENUM 错误。
    • 如果
    • type 为 gl.UNSIGNED_SHORT_5_6_5 且 format 不为 gl.RGB，则会抛出 gl.INVALID_OPERATION 错误。
    • type 为 gl.UNSIGNED_SHORT_4_4_4_4 且 format 不为 gl.RGBA，则会抛出 gl.INVALID_OPERATION 错误。
  • type 与 pixels 的类型化数组类型不匹配，则会抛出 gl.INVALID_OPERATION 错误。

示例

WebGLRenderingContext.readPixels() 方法是 WebGL API 的一部分，它将当前颜色帧缓冲区中指定矩形的像素块读入 TypedArray 或 DataView 对象中。
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

规范

如果当前绑定的帧缓冲区不是帧缓冲区完整，则会抛出 gl.INVALID_FRAMEBUFFER_OPERATION 错误。
规范
# 5.14.12

浏览器兼容性

WebGL 规范

另请参阅