WebGLRenderingContext.cullFace() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.cullFace(mode)

Beschreibung

cullFace() bestimmt, welche Seiten von Dreiecken die GPU beim Rasterisieren verwirft. Welche Seite als Vorderseite gilt, ergibt sich aus der Windungsreihenfolge der Eckpunkte im Bildschirmraum. Standardmäßig ist das gegen den Uhrzeigersinn (gl.CCW), festgelegt über gl.frontFace().

Die Methode wirkt nur, wenn Face Culling vorher mit gl.enable(gl.CULL_FACE) eingeschaltet wurde. Ohne diesen Aufruf ändert cullFace() zwar den gespeicherten Zustand, am Rendering ändert sich aber nichts.

Meist nutzt man es, um bei geschlossenen, undurchsichtigen Körpern wie Würfeln, Kugeln oder Modellen die Rückseiten zu verwerfen, die man ohnehin nicht sieht. Das spart Fragment-Shader-Arbeit und kann die Leistung spürbar verbessern. Die Vorderseiten verwirft man dagegen gezielt, etwa beim Rendern von Skyboxen von innen, bei Shadow Maps (gegen „Shadow Acne“) oder bei Outline-Effekten.

Punkte und Linien sind vom Culling nicht betroffen, nur Polygone (Dreiecke).

Parameter

Name	Typ	Default	Beschreibung
$mode Pflicht	GLenum	gl.BACK	Welche Seiten verworfen werden: `gl.FRONT` (Vorderseiten), `gl.BACK` (Rückseiten, Standard) oder `gl.FRONT_AND_BACK` (alle Polygone; Punkte und Linien werden weiterhin gezeichnet).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Rückseiten-Culling für geschlossene Körper aktivieren

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

// Culling einschalten – ohne enable() hat cullFace() keine Wirkung
gl.enable(gl.CULL_FACE);
gl.frontFace(gl.CCW);   // gegen den Uhrzeigersinn = Vorderseite (Standard)
gl.cullFace(gl.BACK);   // Rückseiten verwerfen

console.log(gl.getParameter(gl.CULL_FACE_MODE) === gl.BACK);

true

Skybox von innen rendern: Vorderseiten verwerfen

const drawScene = (gl, drawSkybox, drawModels) => {
  gl.enable(gl.CULL_FACE);

  // Die Skybox ist ein Würfel, die Kamera sitzt darin
  gl.cullFace(gl.FRONT);
  drawSkybox();

  // Normale Objekte: Rückseiten verwerfen
  gl.cullFace(gl.BACK);
  drawModels();
};

const gl = document.createElement('canvas').getContext('webgl');
drawScene(gl, () => console.log('Skybox gezeichnet'), () => console.log('Modelle gezeichnet'));

Skybox gezeichnet Modelle gezeichnet

Aktuellen Culling-Zustand auslesen und wiederherstellen

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

const withCulling = (mode, fn) => {
  const wasEnabled = gl.isEnabled(gl.CULL_FACE);
  const prevMode = gl.getParameter(gl.CULL_FACE_MODE);
  gl.enable(gl.CULL_FACE);
  gl.cullFace(mode);
  try {
    fn();
  } finally {
    gl.cullFace(prevMode);
    if (!wasEnabled) gl.disable(gl.CULL_FACE);
  }
};

withCulling(gl.FRONT, () => console.log('Shadow-Pass mit Front-Culling'));
console.log(gl.isEnabled(gl.CULL_FACE));

Shadow-Pass mit Front-Culling false

// Wichtig · Fallstricke

Häufigster Fehler: gl.enable(gl.CULL_FACE) vergessen. Culling ist standardmäßig aus.
Verschwinden Objekte nach dem Aktivieren, stimmt meist die Windungsreihenfolge der Eckpunkte nicht. Dann die Indizes korrigieren oder gl.frontFace(gl.CW) setzen. Achtung: Eine negative Skalierung (Spiegelung) in der Modellmatrix kehrt die Windungsreihenfolge ebenfalls um.
Bei transparenten oder offenen Flächen (Blätter, Ebenen, Stoffe) ist Rückseiten-Culling meist unerwünscht. Dann Culling abschalten.
Ein ungültiger mode-Wert löst den Fehler gl.INVALID_ENUM aus, abzufragen über gl.getError().
Den aktuellen Wert liefert gl.getParameter(gl.CULL_FACE_MODE).
Kompatibilität: Die Methode gibt es in WebGL 1 und WebGL 2 (WebGL2RenderingContext) in allen modernen Browsern.

Siehe auch

WebGLRenderingContext.frontFace() WebGLRenderingContext.enable() WebGLRenderingContext.disable() WebGLRenderingContext.isEnabled() WebGLRenderingContext.getParameter() WebGLRenderingContext