DOMMatrixReadOnly.fromFloat64Array() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.fromFloat64Array(array)

Beschreibung

Die statische Methode DOMMatrixReadOnly.fromFloat64Array() baut aus einem typisierten Array mit 64-Bit-Gleitkommazahlen eine unveränderliche Transformationsmatrix. Das ist praktisch, wenn Matrixdaten schon als Binärdaten vorliegen, etwa aus WebGL/WebGPU-Puffern, aus einer Mathematik-Bibliothek oder aus einer vorher mit toFloat64Array() serialisierten Matrix.

Wie das Array gedeutet wird, hängt von seiner Länge ab:

6 Elemente: Sie werden als 2D-Matrix [a, b, c, d, e, f] gelesen, genau wie bei CSS matrix(). Die Matrix hat dann is2D === true.
16 Elemente: Sie werden als 4×4-Matrix in spaltenweiser Reihenfolge (column-major) gelesen: m11, m12, m13, m14, m21, …, m44. Die Matrix hat dann is2D === false.

Die Rechenmethoden des Ergebnisses (multiply(), translate(), inverse() usw.) ändern das Objekt nicht, sondern liefern jeweils eine neue DOMMatrix zurück. Wer eine veränderbare Matrix direkt braucht, nimmt die gleichnamige Methode DOMMatrix.fromFloat64Array().

Parameter

Name	Typ	Default	Beschreibung
$array Pflicht	Float64Array		Typisiertes Array mit genau 6 Werten (2D-Matrix `a`–`f`) oder genau 16 Werten (3D-Matrix, spaltenweise). Jede andere Länge löst einen `TypeError` aus.

Rückgabewert

Typ

DOMMatrixReadOnly

Beschreibung

Ein neues, unveränderliches Matrixobjekt mit den Werten aus dem Array. Bei 6 Elementen ist is2D true, bei 16 Elementen false.

Beispiele

2D-Verschiebung aus 6 Werten erzeugen und einen Punkt umrechnen

// [a, b, c, d, e, f] – Verschiebung um 50 px nach rechts und 20 px nach unten
const werte = new Float64Array([1, 0, 0, 1, 50, 20]);
const matrix = DOMMatrixReadOnly.fromFloat64Array(werte);

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

const punkt = matrix.transformPoint(new DOMPoint(10, 10));
console.log(punkt.x, punkt.y);

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

3D-Matrix aus 16 Werten (spaltenweise) aufbauen

// Einheitsmatrix plus Verschiebung (10, 20, 30) – steht in m41, m42, m43
const daten = new Float64Array([
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  10, 20, 30, 1,
]);

const m = DOMMatrixReadOnly.fromFloat64Array(daten);
console.log(m.is2D, m.m41, m.m42, m.m43);

// Als CSS-Transformation auf ein Element anwenden
document.querySelector('.box').style.transform = m.toString();

false 10 20 30

Matrix speichern, wiederherstellen und falsche Länge abfangen

// Transformation eines Elements auslesen und serialisieren
const box = document.querySelector('.box');
const aktuell = new DOMMatrixReadOnly(getComputedStyle(box).transform);
const gespeichert = Array.from(aktuell.toFloat64Array());
localStorage.setItem('boxMatrix', JSON.stringify(gespeichert));

// Später wiederherstellen
const geladen = new Float64Array(JSON.parse(localStorage.getItem('boxMatrix')));
const wiederhergestellt = DOMMatrixReadOnly.fromFloat64Array(geladen);
console.log(wiederhergestellt.m41 === aktuell.m41);

// Ungültige Länge führt zu TypeError
try {
  DOMMatrixReadOnly.fromFloat64Array(new Float64Array([1, 2, 3]));
} catch (err) {
  console.log(err.name);
}

true TypeError

// Wichtig · Fallstricke

Nur 6 oder 16 Elemente: Jede andere Länge löst einen TypeError aus. Ein normales Array ([1, 0, 0, 1, 0, 0]) wird nicht automatisch umgewandelt. Dafür ist DOMMatrixReadOnly.fromMatrix() oder der Konstruktor new DOMMatrixReadOnly([...]) gedacht.
Spaltenweise Reihenfolge: Bei 16 Werten stehen die Verschiebungsanteile an den Indizes 12–14 (m41–m43), nicht in der letzten Spalte. Wer Daten aus zeilenweise arbeitenden Bibliotheken übernimmt, muss sie vorher transponieren.
Kein automatisches 2D: Eine Matrix aus 16 Werten hat immer is2D === false, auch wenn die Werte eigentlich einer 2D-Transformation entsprechen. toString() gibt dann matrix3d(...) aus.
Kopie statt Verweis: Die Werte werden kopiert. Spätere Änderungen am Float64Array wirken sich nicht auf die Matrix aus.
Genauigkeit: Intern rechnet die Matrix mit doppelter Genauigkeit, daher geht dabei nichts verloren. Mit fromFloat32Array() und 32-Bit-Werten können dagegen Rundungsfehler entstehen.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, auch in Web Workers. Sehr alte Browser kennen nur WebKitCSSMatrix. Den gibt es als Alias zwar noch, er hat diese Methode aber nicht.

Siehe auch

DOMMatrixReadOnly DOMMatrixReadOnly.fromFloat32Array() DOMMatrixReadOnly.fromMatrix() DOMMatrixReadOnly.toFloat64Array() DOMMatrix.fromFloat64Array() DOMMatrix Float64Array