WebGLRenderingContext: Methode 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.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die WebGLRenderingContext.readPixels()-Methode der WebGL API liest einen Block von Pixeln aus einem festgelegten Rechteck des aktuellen Farb-Framebuffers in ein TypedArray oder ein DataView-Objekt.

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)

Parameter

x

Ein GLint, der das erste horizontale Pixel angibt, das von der unteren linken Ecke eines rechteckigen Pixelblocks gelesen wird.

y

Ein GLint, der das erste vertikale Pixel angibt, das von der unteren linken Ecke eines rechteckigen Pixelblocks gelesen wird.

width

Ein GLsizei, der die Breite des Rechtecks angibt.

height

Ein GLsizei, der die Höhe des Rechtecks angibt.

format

Ein GLenum, der das Format der Pixel-Daten angibt. Mögliche Werte:

gl.ALPHA: Ignoriert die roten, grünen und blauen Komponenten und liest die Alpha-Komponente.
gl.RGB: Ignoriert die Alpha-Komponenten und liest die roten, grünen und blauen Komponenten.
gl.RGBA: Rote, grüne, blaue und Alpha-Komponenten werden aus dem Farb-Buffer gelesen.

WebGL2 fügt hinzu

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

type

Ein GLenum, der den Datentyp der Pixel-Daten angibt. Mögliche Werte:

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 fügt hinzu

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

Ein Objekt, in das die Daten gelesen werden. Der Arraytyp muss mit dem Typ des type-Parameters übereinstimmen:

Uint8Array für gl.UNSIGNED_BYTE.
Uint16Array für gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4 oder gl.UNSIGNED_SHORT_5_5_5_1.
Float32Array für gl.FLOAT.

dstOffset Optional

Offset. Standardwert ist 0.

Rückgabewert

Keiner (undefined).

Ausnahmen

Ein gl.INVALID_ENUM-Fehler wird ausgelöst, wenn format oder type keinen akzeptierten Wert hat.
Ein gl.INVALID_OPERATION-Fehler wird ausgelöst, wenn
- type ist gl.UNSIGNED_SHORT_5_6_5 und format ist nicht gl.RGB.
- type ist gl.UNSIGNED_SHORT_4_4_4_4 und format ist nicht gl.RGBA.
- type nicht mit dem Typ des pixels-Arrays übereinstimmt.
Ein gl.INVALID_FRAMEBUFFER_OPERATION-Fehler wird ausgelöst, wenn der aktuell gebundene Framebuffer nicht vollständig ist.

Beispiele

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

Spezifikationen

Specification
WebGL Specification # 5.14.12

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch

Typed Arrays