WebGLRenderingContext.isEnabled() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.isEnabled(cap)

Beschreibung

Mit isEnabled() fragt man den aktuellen Zustand einer Fähigkeit des WebGL-Zustandsautomaten ab. Aktiviert und deaktiviert werden diese Fähigkeiten mit gl.enable() und gl.disable(). Dazu gehören etwa Tiefentest, Blending, Face-Culling, Scissor-Test oder Stencil-Test.

Gebraucht wird die Methode vor allem in Bibliotheken, Render-Hilfsfunktionen und beim Debuggen. Wenn eine Funktion den globalen Zustand vorübergehend ändert, zum Beispiel für ein transparentes Overlay, kann sie den ursprünglichen Zustand vorher sichern und danach wiederherstellen. So beeinflusst sie den übrigen Rendercode nicht.

Standardmäßig sind alle Fähigkeiten deaktiviert, mit Ausnahme von gl.DITHER, das anfangs aktiviert ist. In WebGL 2 (WebGL2RenderingContext) kommt zusätzlich gl.RASTERIZER_DISCARD hinzu.

Parameter

Name	Typ	Default	Beschreibung
$cap Pflicht	GLenum (number)		Die abzufragende Fähigkeit. In WebGL 1: `gl.BLEND`, `gl.CULL_FACE`, `gl.DEPTH_TEST`, `gl.DITHER`, `gl.POLYGON_OFFSET_FILL`, `gl.SAMPLE_ALPHA_TO_COVERAGE`, `gl.SAMPLE_COVERAGE`, `gl.SCISSOR_TEST`, `gl.STENCIL_TEST`. In WebGL 2 zusätzlich `gl.RASTERIZER_DISCARD`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Fähigkeit aktiviert ist, sonst false. Bei einem ungültigen cap ist das Ergebnis false, und es wird der Fehler gl.INVALID_ENUM gesetzt.

Beispiele

Zustand des Tiefentests abfragen

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

console.log(gl.isEnabled(gl.DEPTH_TEST)); // Standard: deaktiviert
gl.enable(gl.DEPTH_TEST);
console.log(gl.isEnabled(gl.DEPTH_TEST));
console.log(gl.isEnabled(gl.DITHER)); // standardmäßig aktiv

false true true

Zustand sichern und wiederherstellen (Overlay mit Blending)

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

const withState = (cap, enabled, drawFn) => {
  const previous = gl.isEnabled(cap);
  enabled ? gl.enable(cap) : gl.disable(cap);
  try {
    drawFn();
  } finally {
    // Ursprünglichen Zustand wiederherstellen
    previous ? gl.enable(cap) : gl.disable(cap);
  }
};

withState(gl.BLEND, true, () => {
  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
  // ... transparentes HUD zeichnen
});

console.log('Blend nach Overlay:', gl.isEnabled(gl.BLEND));

Blend nach Overlay: false

Debug-Ausgabe aller Fähigkeiten

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

const caps = ['BLEND', 'CULL_FACE', 'DEPTH_TEST', 'DITHER',
  'POLYGON_OFFSET_FILL', 'SAMPLE_ALPHA_TO_COVERAGE',
  'SAMPLE_COVERAGE', 'SCISSOR_TEST', 'STENCIL_TEST'];

const state = Object.fromEntries(
  caps.map((name) => [name, gl.isEnabled(gl[name])])
);
console.table(state);

BLEND: false, CULL_FACE: true, DEPTH_TEST: false, DITHER: true, … (alle übrigen false)

// Wichtig · Fallstricke

Performance: Abfragen wie isEnabled() oder getParameter() können eine Synchronisation mit der GPU bzw. dem GPU-Prozess erzwingen, besonders in Chrome mit seiner Mehrprozess-Architektur. In zeitkritischen Render-Schleifen verfolgt man den Zustand besser selbst in JavaScript (Zustands-Cache), statt ihn in jedem Frame abzufragen.
Ein ungültiger Wert für cap wirft keine Exception. Stattdessen gibt die Methode false zurück und setzt gl.INVALID_ENUM. Das lässt sich mit gl.getError() prüfen.
gl.RASTERIZER_DISCARD gibt es nur in einem WebGL2RenderingContext. In WebGL 1 ist die Konstante undefined.
Nach einem Kontextverlust (webglcontextlost) gibt die Methode immer false zurück.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt, auch in OffscreenCanvas und Web Workern.

Siehe auch

WebGLRenderingContext.enable() WebGLRenderingContext.disable() WebGLRenderingContext.getParameter() WebGLRenderingContext.getError() WebGLRenderingContext WebGL2RenderingContext