CanvasRenderingContext2D.imageSmoothingEnabled — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.imageSmoothingEnabled

Beschreibung

Die Eigenschaft imageSmoothingEnabled des CanvasRenderingContext2D steuert, ob der Browser beim Vergrößern oder Verkleinern von Bildern interpoliert. Standardmäßig ist sie true: Beim Skalieren werden Zwischenpixel berechnet, damit das Ergebnis weich aussieht. Mit false wird mit der Methode Nearest Neighbor skaliert. Jeder Pixel bleibt dann ein scharf abgegrenzter Block.

Das ist vor allem bei Pixel-Art, Retro-Spielen, Sprite-Sheets, Kachel-Karten (Tilemaps) und Zoom-Ansichten in Bildeditoren wichtig. Mit Glättung würden kleine Grafiken dort verschwommen aussehen. Auch wenn man einzelne Pixel sichtbar machen will, etwa bei QR-Codes oder Heatmaps aus Rohdaten, schaltet man die Glättung ab.

Die Einstellung betrifft Operationen, die Bilddaten skalieren: drawImage(), Muster (createPattern()) und transformiertes Zeichnen, z. B. mit scale(). Pfade, Text und Formen werden dagegen weiterhin mit Kantenglättung (Antialiasing) gerastert. Die Eigenschaft gehört zum Zeichenzustand. Sie wird also mit save() gesichert und mit restore() wiederhergestellt. Mit imageSmoothingQuality lässt sich außerdem die Qualität der Glättung einstellen, wenn sie aktiv ist.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	true	Beim Setzen: `true` schaltet die Glättung beim Skalieren ein, `false` schaltet sie aus (Nearest Neighbor).

Rückgabewert

Typ

boolean

Beschreibung

Der aktuelle Zustand: true, wenn skalierte Bilder geglättet werden, sonst false.

Beispiele

Pixel-Art-Sprite scharf vergrößern

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

const sprite = new Image();
sprite.src = 'held-16x16.png';

sprite.addEventListener('load', () => {
  // Glättung aus: Die Pixel bleiben scharfe Blöcke
  ctx.imageSmoothingEnabled = false;
  // 16×16-Sprite auf 128×128 vergrößern (Faktor 8)
  ctx.drawImage(sprite, 0, 0, 128, 128);
  console.log(ctx.imageSmoothingEnabled);
});

false

Vergleich: geglättet und ungeglättet nebeneinander

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

// Kleines Quellbild (4×4 Schachbrett) erzeugen
const src = new OffscreenCanvas(4, 4);
const sctx = src.getContext('2d');
for (let y = 0; y < 4; y++) {
  for (let x = 0; x < 4; x++) {
    sctx.fillStyle = (x + y) % 2 ? '#222' : '#f5c518';
    sctx.fillRect(x, y, 1, 1);
  }
}

ctx.imageSmoothingEnabled = true;   // links: verschwommen
ctx.drawImage(src, 0, 0, 160, 160);

ctx.imageSmoothingEnabled = false;  // rechts: scharfe Kanten
ctx.drawImage(src, 170, 0, 160, 160);

Einstellung mit save()/restore() nur vorübergehend ändern

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

const drawZoomed = (img, x, y, factor) => {
  ctx.save();
  ctx.imageSmoothingEnabled = false;
  ctx.drawImage(img, x, y, img.width * factor, img.height * factor);
  ctx.restore(); // Glättung wieder im vorherigen Zustand
};

const img = new Image();
img.src = 'icon.png';
img.onload = () => {
  drawZoomed(img, 0, 0, 6);
  console.log(ctx.imageSmoothingEnabled);
};

true

Zustand nach Größenänderung des Canvas erneut setzen

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

const resize = () => {
  canvas.width = window.innerWidth;
  canvas.height = window.innerHeight;
  // Ändern von width/height setzt den gesamten Kontext-Zustand zurück!
  ctx.imageSmoothingEnabled = false;
};

window.addEventListener('resize', resize);
resize();

// Wichtig · Fallstricke

Zurücksetzen beim Ändern der Größe: Wird canvas.width oder canvas.height neu gesetzt, geht der gesamte Kontext-Zustand verloren. imageSmoothingEnabled ist dann wieder true. Setze die Eigenschaft nach jeder Größenänderung erneut.
Nur für Bilddaten: Auf Text, Linien und Pfade wirkt die Eigenschaft nicht, dort bleibt das Antialiasing aktiv. Für scharfe Linien helfen stattdessen halbe Pixel-Koordinaten (z. B. 0.5) oder ganzzahlige Werte.
CSS-Skalierung: Wird das Canvas-Element selbst per CSS vergrößert, glättet der Browser trotzdem. Dagegen hilft zusätzlich image-rendering: pixelated im CSS.
Nicht ganzzahlige Faktoren: Bei Skalierungsfaktoren wie 2,5 sind die Pixel ohne Glättung ungleich groß. Für saubere Pixel-Art sollte man ganzzahlig skalieren und ganzzahlig positionieren.
Kompatibilität: Alle aktuellen Browser unterstützen die Eigenschaft ohne Präfix. Die alten Varianten mozImageSmoothingEnabled, webkitImageSmoothingEnabled und msImageSmoothingEnabled sind veraltet und nur für sehr alte Browser relevant.

Siehe auch

CanvasRenderingContext2D.imageSmoothingQuality CanvasRenderingContext2D.drawImage() CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D.createPattern() CanvasRenderingContext2D