WebGLRenderingContext.enable() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.enable(cap)

Beschreibung

Mit enable() schaltest du eine Fähigkeit der WebGL-Zustandsmaschine ein. Fast alle diese Fähigkeiten sind beim Erzeugen eines Kontexts ausgeschaltet. Die einzige Ausnahme ist gl.DITHER, das standardmäßig aktiv ist. Wenn du z. B. 3D-Objekte richtig verdecken willst, musst du den Tiefentest ausdrücklich mit gl.enable(gl.DEPTH_TEST) einschalten.

Die Einstellung ist ein globaler Zustand des Kontexts. Sie bleibt aktiv, bis du sie mit disable() wieder ausschaltest, und gilt für alle folgenden Zeichenaufrufe (drawArrays, drawElements). In der Praxis schaltet man Fähigkeiten oft pro Render-Durchlauf um, z. B. zuerst undurchsichtige Objekte mit Tiefentest, dann durchsichtige Objekte mit Blending.

Mögliche Werte in WebGL 1:

gl.BLEND: Blending der Farbwerte (mit blendFunc() konfigurieren)
gl.CULL_FACE: Polygone ausblenden, die von der Kamera wegzeigen (mit cullFace() konfigurieren)
gl.DEPTH_TEST: Tiefenvergleich (mit depthFunc() konfigurieren)
gl.DITHER: Dithering der Farbkomponenten
gl.POLYGON_OFFSET_FILL: Tiefen-Versatz für Polygone (mit polygonOffset())
gl.SAMPLE_ALPHA_TO_COVERAGE: Coverage aus dem Alphawert berechnen
gl.SAMPLE_COVERAGE: Coverage mit dem Wert aus sampleCoverage() verknüpfen
gl.SCISSOR_TEST: Zeichnen auf ein Rechteck beschränken (mit scissor())
gl.STENCIL_TEST: Stencil-Test und Stencil-Buffer-Aktualisierung

In WebGL2RenderingContext kommt außerdem gl.RASTERIZER_DISCARD hinzu. Damit werden Primitive vor der Rasterung verworfen, was z. B. bei Transform Feedback nützlich ist.

Parameter

Name	Typ	Default	Beschreibung
$cap Pflicht	GLenum (number)		Konstante der Fähigkeit, die eingeschaltet werden soll, z. B. `gl.DEPTH_TEST`, `gl.BLEND` oder `gl.CULL_FACE`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Bei einem ungültigen Wert für cap wird intern der Fehler gl.INVALID_ENUM gesetzt.

Beispiele

Tiefentest und Face-Culling für eine 3D-Szene

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

// Verdeckte Flächen korrekt behandeln
gl.enable(gl.DEPTH_TEST);
gl.depthFunc(gl.LEQUAL);

// Rückseiten nicht zeichnen (spart Rechenzeit)
gl.enable(gl.CULL_FACE);
gl.cullFace(gl.BACK);

gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

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

true

Alpha-Blending für durchsichtige Objekte

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

const renderFrame = (drawOpaque, drawTransparent) => {
  // 1. Undurchsichtige Objekte ohne Blending
  gl.disable(gl.BLEND);
  gl.depthMask(true);
  drawOpaque();

  // 2. Durchsichtige Objekte mit Standard-Alpha-Blending
  gl.enable(gl.BLEND);
  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
  gl.depthMask(false); // Tiefe nicht überschreiben
  drawTransparent();
  gl.depthMask(true);
};

renderFrame(() => {}, () => {});
console.log(gl.isEnabled(gl.BLEND));

true

Scissor-Test: nur einen Bildausschnitt löschen

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

// Ganze Fläche blau
gl.clearColor(0, 0, 1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

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

console.log(gl.getError() === gl.NO_ERROR);

true

// Wichtig · Fallstricke

Häufiger Fehler: Der Tiefentest ist standardmäßig aus. Ohne gl.enable(gl.DEPTH_TEST) zeichnet WebGL einfach in Aufrufreihenfolge, sodass hintere Objekte vordere überdecken können. Außerdem muss der Kontext einen Tiefenpuffer haben (getContext('webgl', { depth: true }), das ist die Voreinstellung).
Auch der Stencil-Test wirkt nur, wenn ein Stencil-Puffer vorhanden ist. Dieser ist nicht standardmäßig dabei und muss mit { stencil: true } angefordert werden.
Ungültige Konstanten werfen keine Ausnahme. Sie setzen still gl.INVALID_ENUM, das du nur über gl.getError() siehst. gl.RASTERIZER_DISCARD ist in einem WebGL‑1-Kontext ungültig.
Den Zustand fragst du mit gl.isEnabled(cap) ab. Weil der Zustand global ist, sollten Bibliotheken oder Render-Durchläufe ihn nach Gebrauch zurücksetzen, sonst beeinflussen sie sich gegenseitig.
Geht der Kontext verloren (webglcontextlost), ist danach der gesamte Zustand weg. Aktivierte Fähigkeiten musst du nach webglcontextrestored neu setzen.
Browser-Unterstützung: in allen modernen Browsern verfügbar, auch in WebGL2RenderingContext und OffscreenCanvas-Kontexten.

Siehe auch

WebGLRenderingContext.disable() WebGLRenderingContext.isEnabled() WebGLRenderingContext.blendFunc() WebGLRenderingContext.depthFunc() WebGLRenderingContext.cullFace() WebGLRenderingContext.scissor() WebGLRenderingContext