WebGLRenderingContext: readPixels() 方法

語法

// 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 引數的型別匹配。

• 對於 gl.UNSIGNED_BYTE，使用 Uint8Array。
• 對於 gl.UNSIGNED_SHORT_5_6_5、gl.UNSIGNED_SHORT_4_4_4_4 或 gl.UNSIGNED_SHORT_5_5_5_1，使用 Uint16Array。
• 對於 gl.FLOAT，使用 Float32Array。

dstOffset 可選

偏移量。預設為 0。

返回值

無（undefined）。

異常

• 如果 format 或 type 不是可接受的值，則會丟擲 gl.INVALID_ENUM 錯誤。

• 如果滿足以下條件，則會丟擲 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

規範

瀏覽器相容性

另見

• 型別化陣列