DOMMatrixReadOnly.toFloat32Array() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.toFloat32Array()

Beschreibung

Die Methode toFloat32Array() wandelt eine DOMMatrixReadOnly (und damit auch jede DOMMatrix) in ein neues Float32Array mit genau 16 Einträgen um. Die Reihenfolge ist m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 und entspricht damit der spaltenweisen Anordnung (column-major), die auch WebGL und viele Grafikbibliotheken erwarten.

Typischer Einsatzzweck ist die Übergabe einer im DOM berechneten Transformation an eine GPU-Schnittstelle, etwa gl.uniformMatrix4fv() in WebGL oder einen Uniform-Puffer in WebGPU. Man kann Transformationen also bequem mit translate(), rotate() oder scale() aufbauen und das Ergebnis direkt als Float-Array weiterreichen.

Auch 2D-Matrizen (is2D === true) liefern immer 16 Werte; die fehlenden 3D-Komponenten werden mit den Werten der Einheitsmatrix (0 bzw. 1) aufgefüllt. Das zurückgegebene Array ist eine unabhängige Kopie – Änderungen daran wirken sich nicht auf die Matrix aus.

Da DOMMatrix intern mit 64-Bit-Gleitkommazahlen rechnet, geht bei der Umwandlung in 32-Bit-Werte Genauigkeit verloren. Wer die volle Präzision braucht, verwendet toFloat64Array().

Rückgabewert

Typ

Float32Array

Beschreibung

Ein neues Float32Array der Länge 16 mit den Matrixelementen in spaltenweiser Reihenfolge (m11 bis m44).

Beispiele

Einheitsmatrix und Verschiebung als Float32Array

const identity = new DOMMatrixReadOnly();
console.log(Array.from(identity.toFloat32Array()));

// Verschiebung: landet in m41/m42 (Index 12 und 13)
const moved = new DOMMatrix().translate(10, 20);
console.log(Array.from(moved.toFloat32Array()));

[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 0, 1]

Transformationsmatrix an einen WebGL-Shader übergeben

const canvas = document.querySelector('canvas');
const gl = canvas.getContext('webgl');

const program = gl.createProgram();
// ... Shader anhängen, linken, gl.useProgram(program) ...

const modelMatrix = new DOMMatrix()
  .translate(0.5, 0, 0)
  .rotate(0, 0, 45)
  .scale(0.5);

const location = gl.getUniformLocation(program, 'uModel');
// WebGL erwartet column-major – passt direkt, transpose muss false sein
gl.uniformMatrix4fv(location, false, modelMatrix.toFloat32Array());

Genauigkeitsverlust gegenüber toFloat64Array()

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

console.log(m.toFloat32Array()[0]);
console.log(m.toFloat64Array()[0]);

0.10000000149011612 0.1

Rückgabe ist eine unabhängige Kopie

const matrix = new DOMMatrix().scale(2);
const arr = matrix.toFloat32Array();

arr[0] = 99; // ändert nur das Array
console.log(matrix.a, arr[0], arr.length);

2 99 16

// Wichtig · Fallstricke

Reihenfolge: Die Werte liegen spaltenweise (column-major) vor. Wer eine zeilenweise Anordnung erwartet, erhält eine transponierte Matrix – bei gl.uniformMatrix4fv() daher transpose auf false lassen (in WebGL 1 ist true ohnehin nicht erlaubt).
Präzision: Die Umwandlung in 32-Bit-Floats rundet die Werte. Für Vergleiche oder weitere Berechnungen besser toFloat64Array() oder die Eigenschaften direkt verwenden.
Immer 16 Werte: Auch 2D-Matrizen liefern ein Array der Länge 16, nicht nur die sechs Werte a–f.
Neues Array bei jedem Aufruf: In Render-Schleifen mit vielen Aufrufen pro Frame entsteht Speicherdruck; bei Bedarf Werte in einen wiederverwendeten Puffer kopieren.
Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar. Node.js stellt DOMMatrix nicht nativ bereit; dort sind Polyfills (z. B. aus canvas-Paketen) nötig.

Siehe auch

DOMMatrixReadOnly.toFloat64Array() DOMMatrixReadOnly DOMMatrix DOMMatrix.fromFloat32Array() DOMMatrixReadOnly.toJSON() Float32Array