DOMMatrix.fromFloat64Array() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.fromFloat64Array(array64)

Beschreibung

Die statische Methode DOMMatrix.fromFloat64Array() erzeugt ein neues, veränderbares DOMMatrix-Objekt aus einem Float64Array. Enthält das Array 6 Elemente, entsteht eine 2D-Matrix mit den Werten a, b, c, d, e, f (entspricht m11, m12, m21, m22, m41, m42). Bei 16 Elementen entsteht eine 3D-Matrix. Die Werte werden dabei in spaltenweiser Reihenfolge (column-major) gelesen: m11, m12, m13, m14, m21, …, m44.

Die Methode ist nützlich, wenn Transformationsdaten bereits als typisiertes Array vorliegen, etwa aus WebGL-Berechnungen, Bibliotheken wie gl-matrix, Binärdaten aus Netzwerk oder Worker-Nachrichten. Gegenüber fromFloat32Array() bleibt die volle 64-Bit-Genauigkeit erhalten, die DOMMatrix intern ohnehin verwendet – es gibt also keinen Präzisionsverlust.

Das Gegenstück ist DOMMatrix.prototype.toFloat64Array(), mit dem sich eine Matrix wieder in ein Float64Array serialisieren lässt. Zusammen eignen sich beide ideal für einen verlustfreien Hin- und Rücktransport von Matrizen, z. B. per postMessage().

Parameter

Name	Typ	Default	Beschreibung
$array64 Pflicht	Float64Array		Typisiertes Array mit genau 6 Elementen (2D-Matrix: `a, b, c, d, e, f`) oder genau 16 Elementen (3D-Matrix, spaltenweise `m11` bis `m44`).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue DOMMatrix. Bei 6 Werten ist is2D true, bei 16 Werten false.

Beispiele

2D-Matrix aus 6 Werten erzeugen

// Skalierung um Faktor 2 plus Verschiebung um (10, 20)
const werte = new Float64Array([2, 0, 0, 2, 10, 20]);
const matrix = DOMMatrix.fromFloat64Array(werte);

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

// Punkt transformieren
const punkt = new DOMPoint(5, 5).matrixTransform(matrix);
console.log(punkt.x, punkt.y);

true matrix(2, 0, 0, 2, 10, 20) 20 30

3D-Matrix aus 16 Werten (spaltenweise)

// Einheitsmatrix mit Verschiebung (tx=50, ty=0, tz=-100)
const daten = new Float64Array([
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  50, 0, -100, 1
]);
const m = DOMMatrix.fromFloat64Array(daten);

console.log(m.is2D);
console.log(m.m41, m.m43);

// Direkt auf ein Element anwenden
document.querySelector('.karte').style.transform = m.toString();

false 50 -100

Verlustfreier Transport zwischen Worker und Hauptthread

// Im Worker: Matrix berechnen und als Float64Array senden
const rotation = new DOMMatrix().rotate(45).scale(1.5);
const payload = rotation.toFloat64Array();
postMessage(payload, [payload.buffer]); // Buffer übertragen statt kopieren

// Im Hauptthread:
worker.addEventListener('message', (event) => {
  const matrix = DOMMatrix.fromFloat64Array(event.data);
  canvasCtx.setTransform(matrix);
});

// Wichtig · Fallstricke

Nur 6 oder 16 Elemente: Jede andere Länge wirft einen TypeError. Leere Arrays oder z. B. 9 Werte (3×3-Matrix) werden nicht akzeptiert.
Spaltenweise Reihenfolge: Bei 16 Werten liegen die Verschiebungsanteile an den Indizes 12–14 (m41–m43), nicht in der letzten Spalte einer zeilenweise notierten Matrix. Daten aus zeilenweise arbeitenden Quellen müssen vorher transponiert werden.
Nur Float64Array: Normale Arrays oder Float32Array werfen einen TypeError. Für gewöhnliche Arrays new DOMMatrix([…]) verwenden, für 32-Bit-Daten DOMMatrix.fromFloat32Array().
Das Ergebnis ist eine Kopie; spätere Änderungen am Array wirken sich nicht auf die Matrix aus.
Für eine unveränderliche Matrix gibt es DOMMatrixReadOnly.fromFloat64Array(). In allen aktuellen Browsern sowie in Web Workern verfügbar; nicht in Node.js ohne Polyfill.

Siehe auch

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