DOMMatrix.preMultiplySelf() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.preMultiplySelf(otherMatrix)

Beschreibung

preMultiplySelf() ersetzt die aktuelle Matrix durch das Produkt otherMatrix × this. Die übergebene Transformation wird also nach der bestehenden auf einen Punkt angewendet. Das ist das Gegenstück zu multiplySelf(). Diese Methode rechnet this × otherMatrix und wendet die neue Transformation damit vor der bestehenden an.

Die Methode arbeitet direkt auf der Matrix (mutierend) und gibt dasselbe Objekt zurück. Deshalb lässt sie sich verketten. Wer das Original behalten will, erzeugt vorher mit DOMMatrix.fromMatrix(m) eine Kopie oder nutzt die nicht mutierende Variante otherMatrix.multiply(m).

Typische Einsatzfälle:

Eine „globale“ Transformation (Kamera, Zoom, Verschiebung des Elterncontainers) nachträglich über eine bereits aufgebaute lokale Transformation legen.
Szenengraphen in Canvas oder WebGL, in denen die Eltern-Matrix vor die Kind-Matrix gestellt wird.
Pan- und Zoom-Funktionen, bei denen eine neue Verschiebung im Bildschirmkoordinatensystem gelten soll und nicht im lokalen Koordinatensystem.

Als Argument ist eine DOMMatrix, eine DOMMatrixReadOnly oder ein einfaches Objekt nach dem Muster von DOMMatrixInit erlaubt, zum Beispiel { e: 10, f: 20 }. Ist die übergebene Matrix dreidimensional, gilt danach auch das Ergebnis als 3D-Matrix (is2D === false).

Parameter

Name	Typ	Default	Beschreibung
$otherMatrix	DOMMatrix \| DOMMatrixReadOnly \| DOMMatrixInit	Einheitsmatrix (keine Änderung)	Die Matrix, die von links an die aktuelle Matrix multipliziert wird. Auch ein einfaches Objekt mit Feldern wie `a`–`f`, `m11`–`m44` und `is2D` ist erlaubt. Fehlende Felder erhalten die Werte der Einheitsmatrix.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe, jetzt veränderte DOMMatrix-Instanz (this) mit dem Inhalt otherMatrix × this.

Beispiele

Reihenfolge: preMultiplySelf() und multiplySelf() im Vergleich

const scale = new DOMMatrix().scale(2);
const shift = new DOMMatrix().translate(10, 0);

// shift × scale: erst skalieren, dann verschieben
const pre = DOMMatrix.fromMatrix(scale).preMultiplySelf(shift);
// scale × shift: erst verschieben, dann skalieren
const post = DOMMatrix.fromMatrix(scale).multiplySelf(shift);

console.log(pre.toString());
console.log(post.toString());

const p = new DOMPoint(1, 1);
console.log(p.matrixTransform(pre).x, p.matrixTransform(post).x);

matrix(2, 0, 0, 2, 10, 0) matrix(2, 0, 0, 2, 20, 0) 12 22

Einfaches Objekt als Argument und Verkettung

const m = new DOMMatrix().scale(3);

// Verschiebung um (50, 20), die nach der Skalierung wirkt
const result = m.preMultiplySelf({ e: 50, f: 20 });

console.log(result === m);     // dieselbe Instanz, mutiert
console.log(m.toString());
console.log(m.is2D);

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

Pan in Bildschirmkoordinaten für eine Canvas-Ansicht

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

// Aktuelle Ansicht: gezoomt und gedreht
const view = new DOMMatrix().rotate(30).scale(1.5);

let last = null;
canvas.addEventListener('pointerdown', (e) => { last = { x: e.offsetX, y: e.offsetY }; });
canvas.addEventListener('pointerup', () => { last = null; });
canvas.addEventListener('pointermove', (e) => {
  if (!last) return;
  const dx = e.offsetX - last.x;
  const dy = e.offsetY - last.y;
  last = { x: e.offsetX, y: e.offsetY };

  // Verschiebung soll in Bildschirmpixeln wirken, unabhängig von Drehung und Zoom
  view.preMultiplySelf(new DOMMatrix().translate(dx, dy));
  draw();
});

const draw = () => {
  ctx.resetTransform();
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setTransform(view);
  ctx.fillRect(0, 0, 100, 60);
};

draw();

// Wichtig · Fallstricke

Reihenfolge ist entscheidend: Die Matrixmultiplikation ist nicht kommutativ. a.preMultiplySelf(b) ergibt b × a, a.multiplySelf(b) dagegen a × b. Eine Verwechslung ist der häufigste Fehler, etwa wenn Verschiebungen plötzlich mitskaliert oder mitgedreht werden.
Mutierend: Die Methode verändert die Matrix selbst. Für eine unveränderte Kopie vorher DOMMatrix.fromMatrix() nutzen oder other.multiply(this) aufrufen, das eine neue Matrix liefert.
Die Methode gibt es nur auf DOMMatrix, nicht auf DOMMatrixReadOnly.
Ein widersprüchliches DOMMatrixInit-Objekt löst einen TypeError aus. Beispiele sind { a: 1, m11: 2 } oder { is2D: true, m33: 5 }.
Mit einer 3D-Matrix als Argument wird das Ergebnis dauerhaft zur 3D-Matrix. toString() liefert dann matrix3d(...).
Die Methode ist in allen aktuellen Browsern und in Web Workern verfügbar. In Node.js gibt es DOMMatrix nicht von Haus aus, dort ist ein Polyfill nötig, etwa aus canvas oder geometry-interfaces.
Die Fließkomma-Rundung summiert sich bei vielen verketteten Aufrufen (zum Beispiel bei jedem pointermove). Bei Bedarf die Matrix gelegentlich neu aufbauen.

Siehe auch

DOMMatrix.multiplySelf() DOMMatrix.rotateSelf() DOMMatrix.skewYSelf() DOMMatrix.translateSelf() DOMMatrix.invertSelf() DOMMatrix.setMatrixValue() new XMLSerializer()