WebGLRenderingContext.disable() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.disable(capability)

Beschreibung

Mit disable() schaltet man eine Fähigkeit der WebGL-Zustandsmaschine ab, zum Beispiel den Tiefentest (gl.DEPTH_TEST), das Farbmischen (gl.BLEND) oder das Weglassen von Rückseiten (gl.CULL_FACE). Das Gegenstück ist enable(). Ob eine Fähigkeit gerade aktiv ist, fragt man mit isEnabled() ab.

WebGL ist eine globale Zustandsmaschine: Eine deaktivierte Fähigkeit bleibt so lange aus, bis man sie wieder aktiviert. Das gilt für alle folgenden Zeichenbefehle (drawArrays(), drawElements()). In der Praxis schaltet man Fähigkeiten gezielt pro Render-Durchgang um, etwa den Tiefentest für ein HUD- oder UI-Overlay abschalten oder Blending für undurchsichtige Geometrie aus- und für transparente wieder einschalten.

Diese Fähigkeiten lassen sich in WebGL 1 abschalten:

gl.BLEND – Farbmischen (Transparenz)
gl.CULL_FACE – Polygone je nach Ausrichtung weglassen
gl.DEPTH_TEST – Tiefenvergleich und Aktualisierung des Tiefenpuffers
gl.DITHER – Dithering der Farbkomponenten (standardmäßig aktiv)
gl.POLYGON_OFFSET_FILL – Tiefen-Offset für Polygone
gl.SAMPLE_ALPHA_TO_COVERAGE – Abdeckung aus dem Alphawert berechnen
gl.SAMPLE_COVERAGE – Abdeckung mit dem Wert aus sampleCoverage() verknüpfen
gl.SCISSOR_TEST – Zeichnen auf das Scissor-Rechteck beschränken
gl.STENCIL_TEST – Stencil-Test und Aktualisierung des Stencil-Puffers

In einem WebGL2RenderingContext gibt es außerdem gl.RASTERIZER_DISCARD. Damit werden Primitive direkt vor der Rasterisierung verworfen, was etwa bei reinem Transform Feedback nützlich ist.

Parameter

Name	Typ	Default	Beschreibung
$capability Pflicht	GLenum (number)		Die Konstante der Fähigkeit, die abgeschaltet werden soll, z. B. `gl.DEPTH_TEST`, `gl.BLEND` oder `gl.CULL_FACE`. In WebGL 2 zusätzlich `gl.RASTERIZER_DISCARD`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Bei einer ungültigen Konstante wird gl.INVALID_ENUM gesetzt, das man mit getError() auslesen kann.

Beispiele

Tiefentest ein- und wieder ausschalten

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

gl.enable(gl.DEPTH_TEST);
console.log(gl.isEnabled(gl.DEPTH_TEST));

gl.disable(gl.DEPTH_TEST);
console.log(gl.isEnabled(gl.DEPTH_TEST));

true false

3D-Szene mit Tiefentest, danach UI-Overlay ohne Tiefentest

const renderFrame = (gl, drawScene, drawHud) => {
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

  // 3D-Geometrie: Tiefentest und Culling aktiv
  gl.enable(gl.DEPTH_TEST);
  gl.enable(gl.CULL_FACE);
  drawScene();

  // HUD soll immer oben liegen und transparent sein
  gl.disable(gl.DEPTH_TEST);
  gl.disable(gl.CULL_FACE);
  gl.enable(gl.BLEND);
  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
  drawHud();

  // Zustand für den nächsten Frame aufräumen
  gl.disable(gl.BLEND);
};

Scissor-Test nur für einen Teilbereich nutzen

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

// Nur ein 100×100-Rechteck rot färben
gl.enable(gl.SCISSOR_TEST);
gl.scissor(0, 0, 100, 100);
gl.clearColor(1, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

// Wieder abschalten, sonst wirkt der Ausschnitt auf alle weiteren clear()-Aufrufe
gl.disable(gl.SCISSOR_TEST);
gl.clearColor(0, 0, 0, 0);
console.log(gl.isEnabled(gl.SCISSOR_TEST));

false

Ungültige Konstante erkennen

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

gl.disable(0x1234); // keine gültige Fähigkeit
console.log(gl.getError() === gl.INVALID_ENUM);

true

// Wichtig · Fallstricke

Der Zustand bleibt bestehen: disable() wirkt auf alle späteren Zeichenbefehle, nicht nur auf den nächsten. Wer Fähigkeiten vergisst zurückzusetzen, bekommt schwer auffindbare Fehler, etwa fehlende Tiefensortierung oder ungewollte Transparenz. Setze den Zustand deshalb pro Render-Durchgang ausdrücklich.
Standardwerte: Außer gl.DITHER sind alle Fähigkeiten anfangs abgeschaltet. Ein disable() ohne vorheriges enable() ändert also meist nichts.
Performance: Überflüssige Zustandswechsel kosten Zeit auf der CPU. In großen Render-Schleifen lohnt es sich, den aktuellen Zustand selbst mitzuführen, statt immer wieder isEnabled() abzufragen (das kann die Grafik-Pipeline synchronisieren).
Fehler: Eine ungültige Konstante erzeugt keine Ausnahme, sondern setzt still INVALID_ENUM. Das sieht man nur mit getError(). gl.RASTERIZER_DISCARD gibt es nur in WebGL 2.
Kontextverlust: Nach einem webglcontextlost-Ereignis und der Wiederherstellung ist der gesamte Zustand zurückgesetzt und muss neu gesetzt werden.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt (WebGL 1 und WebGL 2) und steht auch in Web Workers über OffscreenCanvas zur Verfügung.

Siehe auch

WebGLRenderingContext.enable() WebGLRenderingContext.isEnabled() WebGLRenderingContext.blendFunc() WebGLRenderingContext.depthFunc() WebGLRenderingContext.scissor() WebGLRenderingContext.getError() WebGLRenderingContext WebGL2RenderingContext