DOMMatrixReadOnly.fromFloat32Array() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.fromFloat32Array(array)

Beschreibung

DOMMatrixReadOnly.fromFloat32Array() erzeugt eine unveränderliche Transformationsmatrix aus einem typisierten Array mit 32-Bit-Gleitkommawerten. Das ist praktisch, wenn Matrixdaten bereits als Float32Array vorliegen, zum Beispiel aus WebGL-Puffern, Bibliotheken wie gl-matrix oder binären Dateiformaten. Die Daten lassen sich dann mit den DOM-Geometrie-Methoden (transformPoint(), multiply(), inverse() …) weiterverarbeiten.

Wie die Werte interpretiert werden, hängt von der Länge des Arrays ab:

6 Elemente: 2D-Matrix in der Reihenfolge a, b, c, d, e, f (entspricht matrix(a, b, c, d, e, f) in CSS). Das Ergebnis hat is2D === true.
16 Elemente: 3D-Matrix in spaltenweiser Reihenfolge (column-major): m11, m12, m13, m14, m21, …, m44, also genau das Layout, das auch WebGL verwendet. Die Verschiebung steht an den Indizes 12–14 (m41, m42, m43). Das Ergebnis hat is2D === false.

Bei jeder anderen Länge wird ein TypeError geworfen. Brauchst du eine veränderbare Matrix, nimm stattdessen DOMMatrix.fromFloat32Array(). Für Werte mit doppelter Genauigkeit gibt es fromFloat64Array().

Parameter

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

Rückgabewert

Typ

DOMMatrixReadOnly

Beschreibung

Eine neue, unveränderliche Matrix mit den Werten aus dem Array. Bei 6 Elementen ist is2D gleich true, bei 16 Elementen false.

Beispiele

2D-Verschiebung aus 6 Werten erstellen und auf einen Punkt anwenden

// a, b, c, d, e, f → Verschiebung um (50, 20)
const values = new Float32Array([1, 0, 0, 1, 50, 20]);
const matrix = DOMMatrixReadOnly.fromFloat32Array(values);

console.log(matrix.is2D, matrix.e, matrix.f);

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

true 50 20 60 30

WebGL-Matrix (column-major, 16 Werte) übernehmen

// Einheitsmatrix mit Verschiebung (10, 20, 30) an den Indizes 12–14
const glMatrix = new Float32Array([
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  10, 20, 30, 1
]);

const m = DOMMatrixReadOnly.fromFloat32Array(glMatrix);
console.log(m.is2D, m.m41, m.m42, m.m43);

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

false 10 20 30 matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 30, 1)

Genauigkeitsverlust durch 32-Bit-Werte

const m = DOMMatrixReadOnly.fromFloat32Array(
  new Float32Array([0.1, 0, 0, 1, 0, 0])
);

// Float32 kann 0.1 nicht exakt speichern
console.log(m.a);
console.log(m.a === 0.1);

// Zum Vergleich mit 64-Bit-Werten
const exact = DOMMatrixReadOnly.fromFloat64Array(
  new Float64Array([0.1, 0, 0, 1, 0, 0])
);
console.log(exact.a);

0.10000000149011612 false 0.1

Ungültige Länge abfangen

const safeFromFloat32 = (arr) => {
  try {
    return DOMMatrixReadOnly.fromFloat32Array(arr);
  } catch (err) {
    console.warn(`${err.name}: Array braucht 6 oder 16 Werte, hat ${arr.length}`);
    return new DOMMatrixReadOnly(); // Einheitsmatrix als Fallback
  }
};

const m = safeFromFloat32(new Float32Array(4));
console.log(m.isIdentity);

TypeError: Array braucht 6 oder 16 Werte, hat 4 true

// Wichtig · Fallstricke

Nur 6 oder 16 Elemente: Bei jeder anderen Länge wird ein TypeError geworfen.
Nur Float32Array: Normale Arrays wie [1, 0, 0, 1, 0, 0] werden nicht akzeptiert und lösen ebenfalls einen TypeError aus. Für normale Arrays nimmst du den Konstruktor new DOMMatrixReadOnly([...]).
Genauigkeit: Intern speichert die Matrix 64-Bit-Werte. Die 32-Bit-Werte werden umgewandelt, Rundungsfehler aus Float32 bleiben dabei erhalten (z. B. 0.1 → 0.10000000149011612). Für exakte Werte verwende fromFloat64Array().
Reihenfolge: Bei 16 Werten ist das Layout spaltenweise (column-major), wie in WebGL. Zeilenweise Daten aus anderen Quellen musst du vorher transponieren.
Das Ergebnis ist unveränderlich. Methoden wie translate() liefern jeweils eine neue Matrix zurück. Für Änderungen direkt am Objekt nimm DOMMatrix.fromFloat32Array().
Wird in allen modernen Browsern unterstützt, auch in Web Workern. Im Internet Explorer gibt es die Methode nicht, und in Node.js ist sie ohne Polyfill nicht verfügbar.

Siehe auch

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