DOMMatrix.multiplySelf() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.multiplySelf(otherMatrix)

Beschreibung

multiplySelf() verknüpft eine DOMMatrix mit einer zweiten Matrix durch eine Matrixmultiplikation (nicht, wie oft falsch übersetzt, durch ein Skalarprodukt). Die zweite Matrix wird dabei von rechts angehängt: Ist A die aktuelle Matrix und B der Parameter, dann gilt danach A = A · B. Die Matrix wird direkt verändert – anders als bei DOMMatrixReadOnly.prototype.multiply(), das eine neue Matrix zurückgibt.

Eine Multiplikation von rechts heißt: Auf einen Punkt wird zuerst die Transformation B angewendet und danach A. So verhält sich auch eine CSS-transform-Liste, die von links nach rechts gelesen wird: translate(…) scale(…) entspricht T · S. Brauchen Sie die umgekehrte Reihenfolge (B · A), nehmen Sie preMultiplySelf().

Als Parameter geht eine DOMMatrix bzw. DOMMatrixReadOnly oder ein einfaches Objekt nach DOMMatrixInit (z. B. { a, b, c, d, e, f } oder { m11 … m44 }). Fehlende Einträge werden mit den Werten der Einheitsmatrix aufgefüllt. Ohne Argument wird mit der Einheitsmatrix multipliziert, die Matrix bleibt also unverändert.

Typische Einsatzgebiete: Transformationen für Canvas, SVG oder CSS schrittweise aufbauen, Szenengraphen mit verschachtelten Koordinatensystemen und Animationen, bei denen pro Frame eine Transformation dazukommt, ohne jedes Mal ein neues Objekt anzulegen.

Parameter

Name	Typ	Default	Beschreibung
$otherMatrix	DOMMatrix \| DOMMatrixReadOnly \| DOMMatrixInit	Einheitsmatrix	Die Matrix, mit der von rechts multipliziert wird. Ein einfaches Objekt mit den 2D-Einträgen (`a`–`f`) oder den 3D-Einträgen (`m11`–`m44`) ist ebenfalls erlaubt. Fehlende Einträge werden durch Werte der Einheitsmatrix ersetzt.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe, jetzt veränderte DOMMatrix-Instanz (this). Deshalb lassen sich Aufrufe verketten.

Beispiele

Verschiebung und Skalierung kombinieren

const m = new DOMMatrix().translateSelf(100, 50);
const scale = new DOMMatrix().scale(2);

// m = T · S → zuerst skalieren, dann verschieben
m.multiplySelf(scale);

console.log(m.toString());
console.log(m.transformPoint({ x: 10, y: 10 }).x);

matrix(2, 0, 0, 2, 100, 50) 120

Die Reihenfolge spielt eine Rolle: multiplySelf vs. preMultiplySelf

const T = new DOMMatrix().translate(100, 50);
const S = new DOMMatrix().scale(2);

const rechts = DOMMatrix.fromMatrix(T).multiplySelf(S);    // T · S
const links  = DOMMatrix.fromMatrix(T).preMultiplySelf(S); // S · T

console.log(rechts.toString());
console.log(links.toString());

matrix(2, 0, 0, 2, 100, 50) matrix(2, 0, 0, 2, 200, 100)

Einfaches Objekt (DOMMatrixInit) als Parameter

const m = new DOMMatrix();

// Fehlende Einträge (a, b, c, d) werden aus der Einheitsmatrix übernommen
m.multiplySelf({ e: 10, f: 20 });

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

matrix(1, 0, 0, 1, 10, 20) true

Transformation in einer Canvas-Animation aufbauen

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

const world = new DOMMatrix().translateSelf(canvas.width / 2, canvas.height / 2);
const step = new DOMMatrix().rotate(2); // 2° pro Frame

const draw = () => {
  world.multiplySelf(step); // lokale Drehung anhängen, kein neues Objekt
  ctx.resetTransform();
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setTransform(world);
  ctx.fillRect(-25, -25, 50, 50);
  requestAnimationFrame(draw);
};

requestAnimationFrame(draw);

// Wichtig · Fallstricke

Die Matrix wird direkt verändert: Die ursprünglichen Werte sind nach dem Aufruf weg. Wenn Sie sie noch brauchen, rufen Sie vorher DOMMatrix.fromMatrix(m) auf oder verwenden Sie das nicht verändernde multiply().
Reihenfolge: multiplySelf(B) rechnet A · B, preMultiplySelf(B) rechnet B · A. Matrixmultiplikation ist nicht kommutativ. Eine vertauschte Reihenfolge ist der häufigste Fehler.
Aus 2D wird 3D: Ist otherMatrix eine 3D-Matrix (is2D === false), wird auch das Ergebnis zur 3D-Matrix. toString() liefert dann matrix3d(…).
Widersprüchliche Angaben: Enthält ein DOMMatrixInit-Objekt widersprüchliche Werte (z. B. a: 1, m11: 2) oder is2D: true zusammen mit 3D-Einträgen, wird ein TypeError geworfen.
Die Methode gibt es nur auf DOMMatrix, nicht auf DOMMatrixReadOnly. In Node.js ist DOMMatrix nicht eingebaut. Die Methode läuft in allen modernen Browsern und in Web Workern. Ältere WebKit-Versionen kennen nur WebKitCSSMatrix.
Rechnungen mit Gleitkommazahlen können kleine Rundungsfehler erzeugen (z. B. 6.123e-17 statt 0 nach Drehungen).

Siehe auch

DOMMatrix DOMMatrix.preMultiplySelf() DOMMatrixReadOnly.multiply() DOMMatrix.invertSelf() DOMMatrix.translateSelf() DOMMatrixReadOnly.transformPoint() new USBConnectionEvent()