new WebGLContextEvent() — Methode · JavaScript-Referenz

Signatur

new WebGLContextEvent(type, options)

Beschreibung

Mit dem Konstruktor new WebGLContextEvent() legen Sie ein Ereignisobjekt an, das Zustandsänderungen eines WebGL-Kontexts beschreibt. Der Browser erzeugt solche Ereignisse normalerweise selbst und löst sie am <canvas>-Element aus. Die Typen sind webglcontextlost, webglcontextrestored und webglcontextcreationerror.

Selbst gebaut wird so ein Ereignis vor allem in Tests und bei der Fehlersuche. Damit können Sie prüfen, ob Ihre Handler für Kontextverlust und Wiederherstellung korrekt reagieren, ohne dass der Grafiktreiber wirklich ausfällt. Das Objekt erbt von Event und hat zusätzlich die Eigenschaft statusMessage. Sie enthält weitere Informationen, etwa den Grund, warum der Kontext nicht erstellt werden konnte.

Wichtig: Ein per dispatchEvent() ausgelöstes, selbst erzeugtes Ereignis ändert nicht den echten Zustand des WebGL-Kontexts. Ein tatsächlicher Kontextverlust lässt sich nur über die Erweiterung WEBGL_lose_context und deren Methode loseContext() herbeiführen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"webglcontextlost"`, `"webglcontextrestored"` oder `"webglcontextcreationerror"`. Groß- und Kleinschreibung wird beachtet.
$options	object	{}	Optionales Objekt. Neben den Feldern aus `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standardwert `false`) gibt es das Feld `statusMessage` (`string`, Standardwert `""`).

Rückgabewert

Typ

WebGLContextEvent

Beschreibung

Ein neues WebGLContextEvent-Objekt mit den angegebenen Eigenschaften. Es ist noch nicht ausgelöst; das geschieht erst mit dispatchEvent().

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const event = new WebGLContextEvent('webglcontextcreationerror', {
  statusMessage: 'GPU nicht verfügbar',
  cancelable: true
});

console.log(event.type);
console.log(event.statusMessage);
console.log(event.cancelable);
console.log(event instanceof Event);

webglcontextcreationerror GPU nicht verfügbar true true

Kontextverlust-Handler testen

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');

canvas.addEventListener('webglcontextlost', (e) => {
  // Ohne preventDefault() wird der Kontext nie wiederhergestellt
  e.preventDefault();
  console.log('Kontext verloren – Render-Schleife pausiert');
});

// Ereignis simulieren (der echte Kontext bleibt davon unberührt)
canvas.dispatchEvent(new WebGLContextEvent('webglcontextlost', { cancelable: true }));

Kontext verloren – Render-Schleife pausiert

Fehlermeldung beim Erstellen des Kontexts auswerten

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

canvas.addEventListener('webglcontextcreationerror', (e) => {
  console.warn(`WebGL nicht verfügbar: ${e.statusMessage || 'unbekannter Grund'}`);
}, { once: true });

// Simulation für einen Unit-Test
canvas.dispatchEvent(new WebGLContextEvent('webglcontextcreationerror', {
  statusMessage: 'Hardware-Beschleunigung deaktiviert'
}));

WebGL nicht verfügbar: Hardware-Beschleunigung deaktiviert

Echten Kontextverlust auslösen (zum Vergleich)

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
const ext = gl.getExtension('WEBGL_lose_context');

canvas.addEventListener('webglcontextlost', (e) => {
  e.preventDefault();
  console.log('Echter Verlust:', gl.isContextLost());
  setTimeout(() => ext.restoreContext(), 500);
});
canvas.addEventListener('webglcontextrestored', () => {
  console.log('Kontext wiederhergestellt – Ressourcen neu anlegen');
});

ext?.loseContext();

Echter Verlust: true Kontext wiederhergestellt – Ressourcen neu anlegen

// Wichtig · Fallstricke

Nur eine Simulation: Ein selbst erzeugtes und ausgelöstes WebGLContextEvent ändert den Kontext nicht. gl.isContextLost() liefert weiterhin false. Für echte Tests verwenden Sie WEBGL_lose_context.
preventDefault(): Bei webglcontextlost müssen Sie preventDefault() aufrufen, sonst stellt der Browser den Kontext nicht wieder her. Bei selbst erzeugten Ereignissen wirkt das nur, wenn Sie cancelable: true setzen.
Ereignisse steigen nicht auf: Standardmäßig ist bubbles auf false gesetzt. Registrieren Sie die Handler deshalb direkt am <canvas>-Element.
Ressourcen neu anlegen: Nach webglcontextrestored sind alle Texturen, Puffer und Shader ungültig und müssen neu erzeugt werden.
Kompatibilität: In allen modernen Browsern verfügbar, auch in Web Workern mit OffscreenCanvas. In Node.js gibt es die Klasse nicht (höchstens über Pakete wie headless-gl).

Siehe auch

WebGLContextEvent WebGLContextEvent.statusMessage EventTarget.dispatchEvent() new BlobEvent() new CloseEvent()