CanvasRenderingContext2D.getTransform() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.getTransform()

Beschreibung

getTransform() liefert eine Kopie der aktuellen Transformationsmatrix des Canvas-Kontexts als DOMMatrix. Die Matrix entsteht aus allen bisherigen Aufrufen von translate(), rotate(), scale(), transform() und setTransform(). Die 2D-relevanten Komponenten stehen in den Eigenschaften a, b, c, d, e und f und entsprechen der Matrix [a c e; b d f; 0 0 1].

Typische Einsatzfälle sind das Umrechnen von Koordinaten (z. B. Mausposition vom Bildschirm in den transformierten Weltraum per inverse() und transformPoint()), das Zwischenspeichern und Wiederherstellen einer Transformation, ohne den gesamten Zustand über save()/restore() zu sichern, sowie das Übertragen einer Transformation auf einen anderen Kontext.

Da ein neues Objekt zurückgegeben wird, wirken sich Änderungen an der erhaltenen Matrix nicht auf den Kontext aus. Um eine geänderte Matrix wieder anzuwenden, übergibt man sie an setTransform(matrix).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Ein neues DOMMatrix-Objekt mit der aktuellen Transformationsmatrix. Ohne vorherige Transformation ist es die Einheitsmatrix (a=1, b=0, c=0, d=1, e=0, f=0).

Beispiele

Aktuelle Matrix auslesen

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

ctx.translate(50, 20);
ctx.scale(2, 2);

const m = ctx.getTransform();
console.log(m.a, m.b, m.c, m.d, m.e, m.f);
console.log(m.is2D, m.isIdentity);

2 0 0 2 50 20 true false

Mausposition in Weltkoordinaten umrechnen (Zoom/Pan)

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

// Ansicht: verschoben und gezoomt
ctx.setTransform(1.5, 0, 0, 1.5, 100, 40);

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect();
  const screen = new DOMPoint(event.clientX - rect.left, event.clientY - rect.top);
  // Inverse Matrix: Bildschirm -> Welt
  const world = ctx.getTransform().inverse().transformPoint(screen);
  console.log(`Welt: ${world.x.toFixed(1)}, ${world.y.toFixed(1)}`);
});

Welt: 33.3, 40.0 // bei Klick auf Canvas-Pixel (150, 100)

Transformation sichern und später wiederherstellen

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

ctx.translate(200, 150);
ctx.rotate(Math.PI / 4);
const saved = ctx.getTransform(); // Kopie merken

// Kurzzeitig in Bildschirmkoordinaten zeichnen (z. B. HUD)
ctx.resetTransform();
ctx.fillText('Punktestand: 42', 10, 20);

// Ursprüngliche Transformation wieder anwenden
ctx.setTransform(saved);
ctx.fillRect(-25, -25, 50, 50);

Transformation auf zweiten Kontext übertragen

const ctxA = document.querySelector('#a').getContext('2d');
const ctxB = document.querySelector('#b').getContext('2d');

ctxA.scale(0.5, 0.5);
ctxA.translate(30, 30);

ctxB.setTransform(ctxA.getTransform());
console.log(ctxB.getTransform().toString());

matrix(0.5, 0, 0, 0.5, 15, 15)

// Wichtig · Fallstricke

Kopie statt Referenz: Änderungen an der zurückgegebenen DOMMatrix (z. B. m.translateSelf(10, 0)) verändern den Kontext nicht. Erst ctx.setTransform(m) wendet sie an.
Kein Einfluss von CSS: Die Matrix beschreibt nur die Canvas-interne Transformation. CSS-Skalierung des Elements oder devicePixelRatio muss bei Mauskoordinaten separat berücksichtigt werden (z. B. über canvas.width / rect.width).
Inverse: Bei nicht invertierbaren Matrizen (z. B. scale(0, 1)) liefert inverse() eine Matrix mit NaN-Werten – vorher prüfen.
Performance: Jeder Aufruf erzeugt ein neues Objekt; in heißen Render-Schleifen möglichst einmal pro Frame abrufen und wiederverwenden.
Kompatibilität: Unterstützt in Chrome/Edge 68+, Firefox 70+, Safari 11+ sowie in OffscreenCanvasRenderingContext2D. Ältere Browser kennen die Methode nicht – dort muss die Matrix manuell mitgeführt werden.

Siehe auch

CanvasRenderingContext2D.setTransform() CanvasRenderingContext2D.transform() CanvasRenderingContext2D.resetTransform() CanvasRenderingContext2D.translate() CanvasRenderingContext2D.rotate() DOMMatrix