CanvasRenderingContext2D.setTransform() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.setTransform(a, b, c, d, e, f) | CanvasRenderingContext2D.prototype.setTransform(matrix)

Beschreibung

setTransform() setzt die Transformationsmatrix des Canvas-Kontexts zuerst auf die Identitätsmatrix zurück und wendet anschließend die übergebene Matrix an. Im Ergebnis wird die bisherige Transformation also überschrieben. Alle danach gezeichneten Pfade, Bilder und Texte werden mit dieser Matrix transformiert.

Die sechs Werte beschreiben eine affine 2D-Matrix in der Form [a c e; b d f; 0 0 1]. Ein Punkt (x, y) wird zu (a·x + c·y + e, b·x + d·y + f). Dabei stehen a/d für die Skalierung, b/c für Scherung bzw. Rotation und e/f für die Verschiebung.

Typische Einsatzfälle sind das Zurücksetzen mit ctx.setTransform(1, 0, 0, 1, 0, 0) (gleichbedeutend mit resetTransform()), das Einrichten der Skalierung für hochauflösende Displays (devicePixelRatio) und das Anwenden einer vorab berechneten Kamera- bzw. Sprite-Matrix in Spielen. Das geht schneller und ist weniger fehleranfällig als verkettete Aufrufe von translate(), rotate() und scale().

Alternativ nimmt die Methode ein DOMMatrix-Objekt oder ein DOMMatrix2DInit-Objekt ({a, b, c, d, e, f}) entgegen. Wird sie ohne Argument aufgerufen, setzt sie auf die Identitätsmatrix zurück. Die aktuelle Matrix liest du mit getTransform() aus.

Parameter

Name	Typ	Default	Beschreibung
$a Pflicht	number		Horizontale Skalierung (m11).
$b Pflicht	number		Vertikale Scherung (m12).
$c Pflicht	number		Horizontale Scherung (m21).
$d Pflicht	number		Vertikale Skalierung (m22).
$e Pflicht	number		Horizontale Verschiebung (m41) in Pixeln.
$f Pflicht	number		Vertikale Verschiebung (m42) in Pixeln.
$matrix	DOMMatrix \| DOMMatrix2DInit	Identitätsmatrix	Alternative Aufrufform: ein Matrix-Objekt anstelle der sechs Einzelwerte. Ohne Argument wird auf die Identitätsmatrix zurückgesetzt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Transformation zurücksetzen und Canvas komplett leeren

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

ctx.translate(50, 50);
ctx.rotate(Math.PI / 4);
ctx.fillRect(0, 0, 40, 40);

// clearRect würde sonst nur ein gedrehtes Rechteck löschen
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.clearRect(0, 0, canvas.width, canvas.height);
console.log(ctx.getTransform().isIdentity);

true

Scharfe Darstellung auf HiDPI-Displays

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const dpr = window.devicePixelRatio || 1;
const { width, height } = canvas.getBoundingClientRect();

canvas.width = Math.round(width * dpr);
canvas.height = Math.round(height * dpr);

// Überschreibt statt zu multiplizieren – sicher bei wiederholtem Resize
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
ctx.font = '16px sans-serif';
ctx.fillText('Gestochen scharf', 10, 24);

Sprite mit Rotation und Skalierung in einem Schritt

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

const drawSprite = ({ x, y, angle, scale }) => {
  const cos = Math.cos(angle) * scale;
  const sin = Math.sin(angle) * scale;
  ctx.setTransform(cos, sin, -sin, cos, x, y);
  ctx.fillStyle = 'tomato';
  ctx.fillRect(-20, -20, 40, 40); // um den eigenen Mittelpunkt
};

[{ x: 60, y: 60, angle: 0.3, scale: 1 },
 { x: 160, y: 80, angle: 1.2, scale: 1.5 }].forEach(drawSprite);

ctx.resetTransform();

DOMMatrix übergeben

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

const matrix = new DOMMatrix()
  .translate(100, 50)
  .rotate(30)   // Grad, nicht Bogenmaß!
  .scale(2);

ctx.setTransform(matrix);
ctx.strokeRect(0, 0, 30, 20);
console.log(ctx.getTransform().e, ctx.getTransform().f);

100 50

// Wichtig · Fallstricke

Überschreiben statt Multiplizieren: Anders als transform(), translate(), rotate() und scale() ignoriert setTransform() die bisherige Matrix vollständig. Eine vorher eingerichtete devicePixelRatio-Skalierung geht dabei verloren und muss bei Bedarf wieder hineingerechnet werden.
setTransform() gehört zum Zeichenzustand. save() und restore() sichern die Matrix und stellen sie wieder her.
Werte wie Infinity oder NaN werden bei der Sechs-Werte-Variante stillschweigend ignoriert, der Aufruf hat dann keine Wirkung. Ein nicht-endliches DOMMatrix-Objekt kann dagegen einen TypeError auslösen.
Wird canvas.width oder canvas.height neu gesetzt, setzt das den gesamten Kontext zurück, auch die Transformation.
DOMMatrix.rotate() erwartet Grad, ctx.rotate() dagegen Bogenmaß.
Kompatibilität: Die Variante mit sechs Werten funktioniert in allen Browsern. Die Aufrufe mit Matrix-Objekt und ohne Argument werden erst in neueren Versionen unterstützt (Chrome 68+, Firefox 70+, Safari 11+). Die Methode steht auch in OffscreenCanvasRenderingContext2D zur Verfügung.

Siehe auch

CanvasRenderingContext2D.transform() CanvasRenderingContext2D.getTransform() CanvasRenderingContext2D.resetTransform() CanvasRenderingContext2D.translate() CanvasRenderingContext2D.rotate() CanvasRenderingContext2D.scale() CanvasRenderingContext2D.save() DOMMatrix