WebGLRenderingContext.getError() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getError()

Beschreibung

WebGL-Aufrufe werfen bei falscher Verwendung normalerweise keine Ausnahmen. Stattdessen setzt die Implementierung intern ein Fehler-Flag und ignoriert den fehlerhaften Aufruf stillschweigend. Mit getError() fragt man diese Flags ab: Die Methode liefert einen Fehlercode zurück und setzt das zugehörige Flag wieder auf gl.NO_ERROR.

Da mehrere Fehler-Flags gleichzeitig gesetzt sein können, sollte getError() in einer Schleife aufgerufen werden, bis gl.NO_ERROR zurückkommt. Mögliche Rückgabewerte sind:

gl.NO_ERROR (0) – kein Fehler aufgezeichnet.
gl.INVALID_ENUM (0x0500) – ein unzulässiger Enum-Wert wurde übergeben.
gl.INVALID_VALUE (0x0501) – ein numerisches Argument liegt außerhalb des gültigen Bereichs.
gl.INVALID_OPERATION (0x0502) – der Befehl ist im aktuellen Zustand nicht erlaubt.
gl.INVALID_FRAMEBUFFER_OPERATION (0x0506) – der gebundene Framebuffer ist nicht vollständig.
gl.OUT_OF_MEMORY (0x0505) – nicht genug Speicher; der Zustand von WebGL ist danach undefiniert.
gl.CONTEXT_LOST_WEBGL (0x9242) – der Kontext ging verloren (wird einmalig gemeldet).

Typischer Einsatz ist das Debugging während der Entwicklung: Nach verdächtigen Aufrufen (Texturen hochladen, Framebuffer binden, Zeichenaufrufe) prüft man gezielt auf Fehler. Im Produktivcode sollte man getError() sparsam einsetzen, da jeder Aufruf eine Synchronisation mit der GPU erzwingen kann.

Rückgabewert

Typ

GLenum (number)

Beschreibung

Ein Fehlercode wie gl.NO_ERROR, gl.INVALID_ENUM, gl.INVALID_VALUE, gl.INVALID_OPERATION, gl.INVALID_FRAMEBUFFER_OPERATION, gl.OUT_OF_MEMORY oder gl.CONTEXT_LOST_WEBGL.

Beispiele

Einfacher Fehler provozieren und abfragen

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

// Ungültiger Enum-Wert für enable()
gl.enable(gl.TEXTURE_2D); // TEXTURE_2D ist in WebGL kein gültiger Capability-Wert

const err = gl.getError();
console.log(err === gl.INVALID_ENUM); // true
console.log(gl.getError() === gl.NO_ERROR); // true – Flag wurde zurückgesetzt

true true

Alle anstehenden Fehler lesbar ausgeben

const glErrorName = (gl, code) => {
  const names = {
    [gl.INVALID_ENUM]: 'INVALID_ENUM',
    [gl.INVALID_VALUE]: 'INVALID_VALUE',
    [gl.INVALID_OPERATION]: 'INVALID_OPERATION',
    [gl.INVALID_FRAMEBUFFER_OPERATION]: 'INVALID_FRAMEBUFFER_OPERATION',
    [gl.OUT_OF_MEMORY]: 'OUT_OF_MEMORY',
    [gl.CONTEXT_LOST_WEBGL]: 'CONTEXT_LOST_WEBGL'
  };
  return names[code] ?? `UNBEKANNT (0x${code.toString(16)})`;
};

const checkGLErrors = (gl, label = '') => {
  const errors = [];
  let code;
  // Mehrere Flags können gesetzt sein – so lange lesen, bis NO_ERROR kommt
  while ((code = gl.getError()) !== gl.NO_ERROR) {
    errors.push(glErrorName(gl, code));
    if (code === gl.CONTEXT_LOST_WEBGL) break;
  }
  if (errors.length) console.warn(`WebGL-Fehler ${label}:`, errors.join(', '));
  return errors;
};

const gl = document.createElement('canvas').getContext('webgl');
gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(3), gl.STATIC_DRAW); // kein Buffer gebunden
checkGLErrors(gl, 'nach bufferData');

WebGL-Fehler nach bufferData: INVALID_OPERATION

Nur im Debug-Modus prüfen

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

const glCall = (fn, ...args) => {
  const result = fn.apply(gl, args);
  if (DEBUG) {
    const err = gl.getError();
    if (err !== gl.NO_ERROR) {
      throw new Error(`${fn.name} fehlgeschlagen: 0x${err.toString(16)}`);
    }
  }
  return result;
};

try {
  const tex = glCall(gl.createTexture);
  glCall(gl.bindTexture, gl.TEXTURE_2D, tex);
  glCall(gl.texParameteri, gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, 12345); // ungültig
} catch (e) {
  console.error(e.message);
}

texParameteri fehlgeschlagen: 0x500

// Wichtig · Fallstricke

Performance: Jeder getError()-Aufruf kann die Befehlswarteschlange leeren und eine CPU-GPU-Synchronisation erzwingen. In Render-Schleifen im Produktivbetrieb nicht nach jedem Aufruf verwenden – nur im Debug-Modus.
Mehrere Flags: Ein einziger Aufruf liefert nur einen Fehler. Immer in einer Schleife bis gl.NO_ERROR lesen, sonst tauchen alte Fehler später an falscher Stelle auf.
Kontextverlust: gl.CONTEXT_LOST_WEBGL wird nur beim ersten Aufruf nach dem Verlust gemeldet; danach liefert getError() gl.NO_ERROR. Für robuste Behandlung besser das Event webglcontextlost und gl.isContextLost() nutzen.
Shader-Fehler: Kompilier- und Linkfehler setzen kein Fehler-Flag – dafür getShaderParameter(shader, gl.COMPILE_STATUS), getShaderInfoLog() und getProgramParameter() verwenden.
Browser geben zusätzlich oft Warnungen in der Konsole aus (z. B. „WebGL: INVALID_ENUM: enable: invalid capability“); die Anzahl solcher Meldungen ist aber begrenzt.
Kompatibilität: in allen modernen Browsern verfügbar, identisch auch in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext WebGLRenderingContext.isContextLost() WebGLRenderingContext.getShaderInfoLog() WebGLRenderingContext.checkFramebufferStatus() PerformanceTimingConfidence.toJSON()