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 Methode WebGLRenderingContext.readPixels() der WebGL API liest einen Block von Pixeln aus einem angegebenen 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, das das erste horizontale Pixel angibt, das von der unteren linken Ecke eines rechteckigen Blocks von Pixeln gelesen wird.

y

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

width

Ein GLsizei, das die Breite des Rechtecks angibt.

height

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

format

Ein GLenum, das das Format der Pixeldaten angibt. Mögliche Werte:

gl.ALPHA: Ignoriert die roten, grünen und blauen Komponenten und liest die Alphakomponente.
gl.RGB: Ignoriert die Alphakomponente 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, das den Datentyp der Pixeldaten 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 sollen. Der Array-Typ 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. Standardmäßig 0.

Rückgabewert

Keiner (undefined).

Ausnahmen

Ein gl.INVALID_ENUM-Fehler wird ausgelöst, wenn format oder type kein akzeptierter Wert ist.
Ein gl.INVALID_OPERATION-Fehler wird ausgelöst, wenn
- type gl.UNSIGNED_SHORT_5_6_5 ist und format nicht gl.RGB ist.
- type gl.UNSIGNED_SHORT_4_4_4_4 ist und format nicht gl.RGBA ist.
- type nicht dem typisierten Array-Typ von pixels entspricht.
Ein gl.INVALID_FRAMEBUFFER_OPERATION-Fehler wird ausgelöst, wenn der derzeit gebundene Framebuffer nicht framebuffer-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

Siehe auch

Typisierte Arrays