CanvasRenderingContext2D.isContextLost() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.isContextLost()

Beschreibung

Die Methode isContextLost() prüft, ob ein CanvasRenderingContext2D gerade verloren ist. Das kann passieren, wenn der Browser die GPU-Ressourcen hinter einem hardwarebeschleunigten Canvas freigibt, etwa bei einem Absturz oder Reset des Grafiktreibers, bei knappem Speicher oder wenn ein Tab lange im Hintergrund liegt. Solange der Kontext verloren ist, haben Zeichenbefehle keine Wirkung, und der bisherige Inhalt des Canvas ist weg.

Die Methode ist vor allem für Anwendungen mit viel Zeichenarbeit gedacht, zum Beispiel Spiele, Datenvisualisierungen oder Zeichenprogramme. Bevor du aufwendig zeichnest, kannst du damit prüfen, ob sich das Zeichnen überhaupt lohnt. Außerdem erkennst du so einen Zustand, in dem du die Szene später neu aufbauen musst.

Zusammen mit isContextLost() gibt es zwei Events am <canvas>-Element: contextlost (der Kontext ist verloren) und contextrestored (der Browser hat den Kontext zurückgesetzt und er ist wieder nutzbar). Nach dem Zurücksetzen ist der Kontext im Ausgangszustand. Transformationen, Stile und der gesamte Bildinhalt müssen also neu gesetzt bzw. neu gezeichnet werden.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Kontext verloren ist und noch nicht wiederhergestellt wurde, sonst false.

Beispiele

Einfache Prüfung des Kontext-Zustands

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

// Methode nur aufrufen, wenn der Browser sie kennt
if (typeof ctx.isContextLost === 'function') {
  console.log('Kontext verloren?', ctx.isContextLost());
} else {
  console.log('isContextLost() wird nicht unterstützt');
}

Kontext verloren? false

Render-Schleife pausiert bei verlorenem Kontext

const canvas = document.querySelector('#spiel');
const ctx = canvas.getContext('2d');
let x = 0;

const zeichnen = () => {
  // Ohne gültigen Kontext nicht zeichnen
  if (!ctx.isContextLost?.()) {
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.fillStyle = 'tomato';
    ctx.fillRect(x, 50, 40, 40);
    x = (x + 2) % canvas.width;
  }
  requestAnimationFrame(zeichnen);
};

requestAnimationFrame(zeichnen);

Mit contextlost / contextrestored die Szene neu aufbauen

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

const szeneAufbauen = () => {
  // Nach dem Zurücksetzen sind alle Zustände weg – neu setzen
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.font = '20px sans-serif';
  ctx.fillStyle = '#333';
  ctx.fillText('Hallo Canvas', 20, 40);
};

canvas.addEventListener('contextlost', (event) => {
  console.warn('Kontext verloren:', ctx.isContextLost());
  // event.preventDefault() würde das automatische Zurücksetzen verhindern
});

canvas.addEventListener('contextrestored', () => {
  console.log('Kontext zurückgesetzt:', !ctx.isContextLost());
  szeneAufbauen();
});

szeneAufbauen();

Kontext verloren: true Kontext zurückgesetzt: true

// Wichtig · Fallstricke

Browser-Unterstützung: In Chromium-Browsern gibt es die Methode seit Version 99. Firefox und Safari unterstützen sie nicht überall. Prüfe daher vorher, ob es sie gibt, zum Beispiel mit ctx.isContextLost?.(). Wenn nicht, liefert der Ausdruck undefined, und das wird wie „nicht verloren“ behandelt.
Ein verlorener 2D-Kontext kommt in der Praxis selten vor. Am ehesten passiert es bei GPU-beschleunigten Canvas-Elementen, bei vielen oder sehr großen Canvas-Elementen oder auf Mobilgeräten mit wenig Speicher.
Nach contextrestored ist der Kontext komplett zurückgesetzt, wie nach einem Aufruf von reset(). Transformationen, Clipping, Stile und der Bildinhalt sind verloren. Halte deshalb die Daten deiner Szene getrennt vom Canvas vor, damit du alles neu zeichnen kannst.
Wenn du im contextlost-Handler event.preventDefault() aufrufst, versucht der Browser nicht, den Kontext wiederherzustellen.
Nicht verwechseln mit WebGLRenderingContext.isContextLost(): Dort gelten andere Events (webglcontextlost/webglcontextrestored) und eine andere Logik für die Wiederherstellung.
Die Methode gibt es auch bei OffscreenCanvasRenderingContext2D.

Siehe auch

CanvasRenderingContext2D CanvasRenderingContext2D.reset() WebGLRenderingContext.isContextLost() HTMLCanvasElement.getContext() CanvasRenderingContext2D.getContextAttributes()