DOMMatrix.rotateSelf() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.rotateSelf(rotX, rotY, rotZ)

Beschreibung

rotateSelf() ist die verändernde Variante von DOMMatrix.rotate(). Statt eine neue Matrix zu erzeugen, wird die bestehende Matrix mit einer Rotationsmatrix multipliziert (von rechts, also Post-Multiplikation: this = this × R), und die Methode gibt genau dieses Objekt zurück. So lassen sich Transformationen effizient verketten, ohne bei jedem Schritt neue Objekte anzulegen – z. B. in Animationsschleifen oder beim Zeichnen auf einem <canvas>.

Alle Winkel werden in Grad angegeben, nicht im Bogenmaß. Eine Besonderheit: Wird nur ein Argument übergeben, wird es als Drehung um die Z-Achse interpretiert – das entspricht der üblichen 2D-Rotation in der Bildebene, genau wie bei CSS rotate(). Werden mehrere Argumente übergeben, dreht die Methode nacheinander um Z, dann Y, dann X (die Rotationen werden in der Reihenfolge X·Y·Z angehängt).

Sobald rotX oder rotY ungleich 0 ist, wird die Matrix zu einer echten 3D-Matrix und is2D wird dauerhaft false. Ihre String-Darstellung lautet dann matrix3d(...) statt matrix(...).

Weil die Rotation immer um den Ursprung (0, 0) erfolgt, kombiniert man sie für eine Drehung um einen beliebigen Punkt typischerweise mit translateSelf(): erst zum Drehpunkt verschieben, drehen, dann zurückverschieben.

Parameter

Name	Typ	Default	Beschreibung
$rotX	number	0	Drehwinkel in Grad um die X-Achse. Achtung: Ist dies das einzige Argument, wird der Wert als Drehung um die Z-Achse verwendet.
$rotY	number	0	Drehwinkel in Grad um die Y-Achse. Ein Wert ungleich 0 macht die Matrix zur 3D-Matrix.
$rotZ	number	0 (bzw. <code>rotX</code>, falls nur ein Argument übergeben wird)	Drehwinkel in Grad um die Z-Achse (2D-Drehung in der Bildebene).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe DOMMatrix-Instanz, jetzt verändert. Dadurch sind Methodenketten wie m.translateSelf(10, 10).rotateSelf(45) möglich.

Beispiele

Einfache 2D-Drehung um 90 Grad

const m = new DOMMatrix();
const result = m.rotateSelf(90); // ein Argument = Drehung um Z

console.log(result === m); // gleiche Instanz
// Werte runden, da cos(90°) nur ~6.12e-17 ergibt
const r = (v) => Math.round(v * 1e6) / 1e6;
console.log(r(m.a), r(m.b), r(m.c), r(m.d));
console.log(m.is2D);

true 0 1 -1 0 true

Um einen beliebigen Drehpunkt drehen (Canvas)

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

const cx = 100, cy = 75; // Mittelpunkt des Rechtecks
const m = new DOMMatrix()
  .translateSelf(cx, cy)
  .rotateSelf(30)
  .translateSelf(-cx, -cy);

ctx.setTransform(m);
ctx.fillStyle = 'tomato';
ctx.fillRect(50, 50, 100, 50);
ctx.resetTransform();

Animation ohne neue Objekte pro Frame

const box = document.querySelector('.box');
const m = new DOMMatrix();
let last = performance.now();

const tick = (now) => {
  const dt = (now - last) / 1000;
  last = now;
  m.rotateSelf(90 * dt); // 90 Grad pro Sekunde, akkumuliert
  box.style.transform = m.toString();
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

3D-Rotation und Punkttransformation

const m = new DOMMatrix().rotateSelf(0, 90, 0); // um Y-Achse
console.log(m.is2D);
console.log(m.toString().startsWith('matrix3d('));

const p = m.transformPoint(new DOMPoint(1, 0, 0));
const r = (v) => Math.round(v * 1e6) / 1e6 + 0; // +0 entfernt -0
console.log(r(p.x), r(p.y), r(p.z));

false true 0 0 -1

// Wichtig · Fallstricke

Grad statt Bogenmaß: Anders als Math.sin()/Math.cos() oder CanvasRenderingContext2D.rotate() erwartet rotateSelf() Winkel in Grad. Wer Werte aus Math.atan2() übernimmt, muss sie mit 180 / Math.PI umrechnen.
Ein Argument = Z-Achse: rotateSelf(45) dreht um Z, nicht um X. rotateSelf(45, 0) dreht dagegen um X – ein häufiger Stolperstein.
Verändernd: Die Originalmatrix wird überschrieben. Wird die Ausgangsmatrix noch gebraucht, stattdessen rotate() verwenden oder vorher mit DOMMatrix.fromMatrix(m) kopieren. Auf DOMMatrixReadOnly gibt es rotateSelf() nicht.
Reihenfolge: Es handelt sich um eine Post-Multiplikation. translateSelf().rotateSelf() ist nicht dasselbe wie rotateSelf().translateSelf().
Gleitkomma-Ungenauigkeit: Auch bei 90° oder 180° entstehen Werte wie 6.12e-17 statt 0. Beim Vergleichen oder Ausgeben runden. Bei sehr vielen aufeinanderfolgenden Aufrufen (Animationen) können sich Fehler aufsummieren. Dann besser den Gesamtwinkel speichern und die Matrix pro Frame neu aufbauen.
2D → 3D ist endgültig: Werte ungleich 0 für rotX/rotY setzen is2D auf false. Das bleibt so, auch wenn man später zurückdreht.
Kompatibilität: In allen aktuellen Browsern verfügbar (Chrome/Edge 61+, Firefox 33+, Safari 11+), auch in Web Workers. In Node.js gibt es DOMMatrix nicht von Haus aus. Dort braucht man ein Polyfill oder Pakete wie canvas/geometry-interfaces.

Siehe auch

DOMMatrix.scaleSelf() DOMMatrix.translateSelf() DOMMatrix.invertSelf() DOMMatrix.scale3dSelf() DOMMatrix.skewXSelf() DOMMatrix.setMatrixValue() new TaskPriorityChangeEvent()