HTMLCanvasElement: webglcontextcreationerror — Ereignis · JavaScript-Referenz

Signatur

canvas.addEventListener("webglcontextcreationerror", handler)

Beschreibung

Das Ereignis webglcontextcreationerror wird synchron während des Aufrufs von canvas.getContext("webgl") bzw. getContext("webgl2") ausgelöst, wenn der Browser keinen WebGL-Kontext erstellen kann. Das passiert zum Beispiel, wenn die GPU oder der Treiber auf einer Sperrliste steht, WebGL in den Einstellungen abgeschaltet ist, die Hardwarebeschleunigung fehlt oder die angeforderten Kontextattribute (etwa failIfMajorPerformanceCaveat: true) nicht erfüllbar sind.

Das Ereignisobjekt ist ein WebGLContextEvent. Seine Eigenschaft statusMessage kann einen browserspezifischen Klartext mit dem Grund für den Fehlschlag enthalten, der sich gut für Fehlermeldungen oder Telemetrie eignet.

Registrieren kannst du den Handler mit addEventListener("webglcontextcreationerror", handler) oder über die Eigenschaft canvas.onwebglcontextcreationerror (nicht in allen Browsern vorhanden, daher ist addEventListener vorzuziehen). Wichtig: Den Listener vor dem Aufruf von getContext() registrieren, sonst verpasst du das Ereignis.

Typischer Einsatz: sinnvolle Fehlermeldung anzeigen, auf einen 2D-Canvas oder statische Grafik zurückfallen oder den Grund zur Fehleranalyse protokollieren. getContext() gibt in diesem Fall zusätzlich null zurück.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"webglcontextcreationerror"`.
$handler Pflicht	(event: WebGLContextEvent) => void		Callback, der ein `WebGLContextEvent` erhält; `event.statusMessage` enthält ggf. den Fehlergrund.
$options	boolean\|AddEventListenerOptions	false	Optionale Listener-Optionen wie `{ once: true }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignis selbst ist ein WebGLContextEvent (nicht abbrechbar sinnvoll, bubbelt nicht).

Beispiele

Fehlergrund protokollieren und auf 2D zurückfallen

const canvas = document.querySelector('#scene');
let reason = 'unbekannt';

// Listener VOR getContext() registrieren
canvas.addEventListener('webglcontextcreationerror', (event) => {
  reason = event.statusMessage || 'unbekannt';
}, { once: true });

const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');

if (!gl) {
  console.warn(`WebGL nicht verfügbar: ${reason}`);
  const ctx = canvas.getContext('2d');
  ctx.font = '16px sans-serif';
  ctx.fillText('3D-Ansicht wird nicht unterstützt.', 10, 30);
}

WebGL nicht verfügbar: Hardware acceleration disabled (Beispiel, browserabhängig)

Nur hardwarebeschleunigte Kontexte zulassen

const canvas = document.createElement('canvas');

canvas.onwebglcontextcreationerror = (event) => {
  console.error('Kontext abgelehnt:', event.statusMessage);
};

// Scheitert bei Software-Rendering (z. B. SwiftShader)
const gl = canvas.getContext('webgl', { failIfMajorPerformanceCaveat: true });
console.log(gl ? 'GPU-Kontext aktiv' : 'Kein performanter Kontext');

Kontext abgelehnt: ... (falls nur Software-Rendering verfügbar) Kein performanter Kontext

Wiederverwendbare Hilfsfunktion mit Promise-Ergebnis

const createGLContext = (canvas, attrs = {}) => {
  let message = '';
  const onError = (e) => { message = e.statusMessage; };
  canvas.addEventListener('webglcontextcreationerror', onError);
  const gl = canvas.getContext('webgl2', attrs);
  canvas.removeEventListener('webglcontextcreationerror', onError);
  return gl
    ? { ok: true, gl }
    : { ok: false, error: message || 'WebGL2 nicht verfügbar' };
};

const result = createGLContext(document.querySelector('canvas'));
console.log(result.ok ? 'Bereit' : result.error);

Bereit

// Wichtig · Fallstricke

Reihenfolge: Das Ereignis feuert synchron innerhalb von getContext(). Ein danach registrierter Listener erhält es nicht.
statusMessage ist nicht standardisiert formuliert und kann leer sein; nicht für Programmlogik parsen, nur anzeigen/protokollieren.
Pro Canvas lässt sich nur ein Kontexttyp anfordern: Hat getContext('webgl') bereits erfolgreich einen Kontext geliefert, gibt ein späteres getContext('2d') null zurück. Für einen 2D-Fallback nach erfolgreichem WebGL ein neues Canvas verwenden.
Nicht verwechseln mit webglcontextlost: Dieses feuert, wenn ein bestehender Kontext verloren geht (z. B. GPU-Reset).
Die Eigenschaft onwebglcontextcreationerror wird nicht von allen Browsern angeboten; addEventListener funktioniert überall. Auch in OffscreenCanvas verfügbar.
Datenschutz: Manche Browser kürzen die Fehlermeldung absichtlich, um Fingerprinting über GPU-Details zu erschweren.

Siehe auch

WebGLContextEvent webglcontextlost webglcontextrestored HTMLCanvasElement.getContext() WebGLRenderingContext WebGL2RenderingContext OfflineAudioContext: complete