CanvasPattern.setTransform() — Methode · JavaScript-Referenz

Signatur

CanvasPattern.prototype.setTransform(matrix)

Beschreibung

Mit setTransform() legst du fest, wie ein mit CanvasRenderingContext2D.createPattern() erzeugtes Muster im Koordinatensystem der Zeichenfläche liegt. So kannst du Kacheln skalieren, drehen oder verschieben, ohne die Transformation des gesamten Kontexts (ctx.setTransform(), ctx.rotate() …) zu ändern. Die gezeichneten Formen bleiben also an Ort und Stelle, nur die Füllung darin bewegt sich.

Die Matrix wird als 2D-Matrix interpretiert und entspricht den Werten a, b, c, d, e, f (bzw. m11, m12, m21, m22, m41, m42). Du kannst ein DOMMatrix-Objekt übergeben oder ein einfaches Objekt wie { a: 2, d: 2 }. Jeder Aufruf ersetzt die bisherige Mustermatrix vollständig – die Werte werden nicht kumuliert.

Typische Einsatzfälle sind animierte Hintergründe (z. B. scrollende Streifen), das Anpassen einer Textur an die Größe eines Objekts oder High-DPI-Korrekturen, bei denen die Musterkachel passend zum devicePixelRatio skaliert werden soll. Die Transformation wird zusätzlich zur aktuellen Kontexttransformation zum Zeitpunkt des Füllens angewendet.

Parameter

Name	Typ	Default	Beschreibung
$matrix	DOMMatrix \| DOMMatrix2DInit	Einheitsmatrix	Die Transformationsmatrix für das Muster. Ein `DOMMatrix` oder ein Objekt mit den Feldern `a`–`f` bzw. `m11`, `m12`, `m21`, `m22`, `m41`, `m42`. Ohne Argument wird die Einheitsmatrix gesetzt (Transformation zurücksetzen).

Beispiele

Muster skalieren und drehen

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

// Kleine Kachel mit Karo-Muster erzeugen
const tile = new OffscreenCanvas(20, 20);
const tctx = tile.getContext('2d');
tctx.fillStyle = '#eee';
tctx.fillRect(0, 0, 20, 20);
tctx.fillStyle = '#c33';
tctx.fillRect(0, 0, 10, 10);
tctx.fillRect(10, 10, 10, 10);

const pattern = ctx.createPattern(tile, 'repeat');

// Doppelt so groß und um 45° gedreht
const matrix = new DOMMatrix().scale(2).rotate(45);
pattern.setTransform(matrix);

ctx.fillStyle = pattern;
ctx.fillRect(0, 0, canvas.width, canvas.height);

Animierter Streifen-Hintergrund

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

const tile = document.createElement('canvas');
tile.width = tile.height = 16;
const tctx = tile.getContext('2d');
tctx.fillStyle = '#ffd400';
tctx.fillRect(0, 0, 16, 16);
tctx.fillStyle = '#222';
tctx.fillRect(0, 0, 8, 16);

const pattern = ctx.createPattern(tile, 'repeat');
let offset = 0;

const draw = () => {
  offset = (offset + 0.5) % 16;
  // Nur das Muster verschieben, nicht die Form
  pattern.setTransform(new DOMMatrix().translate(offset, 0).skewX(-30));
  ctx.fillStyle = pattern;
  ctx.fillRect(20, 20, 300, 40);
  requestAnimationFrame(draw);
};
draw();

Einfaches Objekt statt DOMMatrix und Zurücksetzen

const ctx = document.querySelector('canvas').getContext('2d');
const img = new Image();
img.src = 'textur.png';
await img.decode();

const pattern = ctx.createPattern(img, 'repeat');

// Halbe Größe, um 10px versetzt (a, b, c, d, e, f)
pattern.setTransform({ a: 0.5, b: 0, c: 0, d: 0.5, e: 10, f: 10 });
ctx.fillStyle = pattern;
ctx.fillRect(0, 0, 200, 200);

// Transformation wieder aufheben
pattern.setTransform();
ctx.fillRect(220, 0, 200, 200);

// Wichtig · Fallstricke

Ersetzen statt Kombinieren: Jeder Aufruf überschreibt die vorherige Mustermatrix. Für schrittweise Änderungen die Matrix selbst mit multiply(), translate() usw. aufbauen und dann komplett übergeben.
Kontexttransformation wirkt zusätzlich: Beim Füllen wird die aktuelle Transformation des Kontexts auf das Muster angewendet – ein bereits gedrehter Kontext dreht das Muster also mit.
Enthält die Matrix NaN oder Infinity, wird der Aufruf ignoriert. Inkonsistente Objekte (z. B. a und m11 mit unterschiedlichen Werten) lösen einen TypeError aus.
Ältere Implementierungen akzeptierten ausschließlich SVGMatrix; das Argument ist heute optional und wird als DOMMatrix2DInit behandelt. Alle aktuellen Browser (Chrome, Edge, Firefox, Safari) unterstützen die Methode, auch bei OffscreenCanvas.
Bei stark skalierten Mustern beeinflusst ctx.imageSmoothingEnabled die Darstellung – für Pixel-Art auf false setzen.

Siehe auch

new RTCRtpScriptTransform() CanvasRenderingContext2D.transform() CanvasRenderingContext2D.setTransform() SVGTransform.setTranslate() Translator.translate()