DOMMatrix.fromFloat32Array() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.fromFloat32Array(array)

Beschreibung

Die statische Methode DOMMatrix.fromFloat32Array() erzeugt ein neues, veränderbares DOMMatrix-Objekt aus einem typisierten Array mit 32-Bit-Gleitkommawerten (einfache Genauigkeit). Das ist der direkte Weg, um Matrixdaten aus WebGL, WebGPU, binären Dateiformaten oder Bibliotheken wie gl-matrix in die Geometrie-API des Browsers zu übernehmen.

Die Länge des Arrays bestimmt die Art der Matrix:

6 Elemente: eine 2D-Matrix mit den Komponenten a, b, c, d, e, f (entspricht matrix(a, b, c, d, e, f) in CSS). is2D ist dann true.
16 Elemente: eine 4×4-Matrix in spaltenweiser Reihenfolge (column-major): m11, m12, m13, m14, m21, …, m44. Die Verschiebung steht also in den Elementen 12–14 (m41, m42, m43). is2D ist dann false.

Das ist genau die Reihenfolge, die WebGL mit uniformMatrix4fv() erwartet und die DOMMatrix.prototype.toFloat32Array() liefert. Damit ist ein verlustfreier Hin- und Rückweg zwischen DOMMatrix und GPU-Puffern möglich. Intern speichert DOMMatrix die Werte allerdings als 64-Bit-Zahlen. Die Werte übernehmen deshalb die Rundungsfehler der 32-Bit-Darstellung.

Parameter

Name	Typ	Default	Beschreibung
$array Pflicht	Float32Array		Typisiertes Array mit genau `6` Werten (2D-Matrix: `a`–`f`) oder genau `16` Werten (4×4-Matrix in spaltenweiser Reihenfolge `m11`…`m44`).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Ein neues DOMMatrix-Objekt mit den Werten aus dem Array. Bei 6 Elementen ist is2D gleich true, bei 16 Elementen gleich false.

Beispiele

2D-Verschiebung aus 6 Werten erzeugen

// a, b, c, d, e, f → Verschiebung um 50 px nach rechts und 20 px nach unten
const m = DOMMatrix.fromFloat32Array(new Float32Array([1, 0, 0, 1, 50, 20]));

console.log(m.is2D);
console.log(m.toString());

// Direkt als CSS-Transformation verwenden
document.querySelector('.box').style.transform = m.toString();

true matrix(1, 0, 0, 1, 50, 20)

3D-Matrix aus WebGL-Daten (spaltenweise Reihenfolge)

// 4×4-Matrix, Verschiebung steht in den Elementen 12–14
const data = new Float32Array([
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  10, 20, 30, 1
]);

const m = DOMMatrix.fromFloat32Array(data);
console.log(m.is2D, m.m41, m.m42, m.m43);

// Weiter transformieren und zurück an die GPU geben
const rotated = m.rotate(0, 0, 45);
// gl.uniformMatrix4fv(uModelLocation, false, rotated.toFloat32Array());
console.log(rotated.toFloat32Array().length);

false 10 20 30 16

Rundungsfehler durch 32-Bit-Genauigkeit

const m32 = DOMMatrix.fromFloat32Array(new Float32Array([0.1, 0, 0, 1, 0, 0]));
const m64 = DOMMatrix.fromFloat64Array(new Float64Array([0.1, 0, 0, 1, 0, 0]));

console.log(m32.a);
console.log(m64.a);

0.10000000149011612 0.1

Ungültige Länge abfangen

const toMatrix = (values) => {
  try {
    return DOMMatrix.fromFloat32Array(new Float32Array(values));
  } catch (err) {
    console.error(`${err.name}: ungültige Matrixlänge ${values.length}`);
    return new DOMMatrix(); // Einheitsmatrix als Rückfall
  }
};

const m = toMatrix([1, 0, 0, 1]);
console.log(m.isIdentity);

TypeError: ungültige Matrixlänge 4 true

// Wichtig · Fallstricke

Nur 6 oder 16 Elemente: Jede andere Länge löst einen TypeError aus. Leere Arrays sind ebenfalls ungültig.
Nur Float32Array: Ein normales Array oder ein Float64Array wird mit einem TypeError abgewiesen. Für 64-Bit-Daten gibt es DOMMatrix.fromFloat64Array(), für normale Arrays new DOMMatrix([...]).
Spaltenweise Reihenfolge: Wenn Sie 16 Werte zeilenweise ablegen (wie in vielen Mathe-Lehrbüchern), landet die Verschiebung in m14/m24/m34 statt in m41/m42/m43. Das ist ein häufiger Fehler.
Genauigkeit: Die Werte haben nur 32-Bit-Genauigkeit (etwa 7 Dezimalstellen). Vergleiche mit === schlagen deshalb leicht fehl.
Kopie statt Referenz: Die Werte werden kopiert. Spätere Änderungen am Float32Array wirken sich nicht auf die Matrix aus.
Die unveränderliche Variante heißt DOMMatrixReadOnly.fromFloat32Array().
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workers. Node.js hat DOMMatrix nicht eingebaut; dort braucht man ein Polyfill oder eine Canvas-Bibliothek.

Siehe auch

DOMMatrix DOMMatrix.fromFloat64Array() DOMMatrix.fromMatrix() DOMMatrixReadOnly.prototype.toFloat32Array() DOMMatrixReadOnly Float32Array