WebGLRenderingContext.clearDepth() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.clearDepth(depth)

Beschreibung

clearDepth() legt fest, auf welchen Wert jeder Pixel des Tiefenpuffers beim nächsten Aufruf von gl.clear(gl.DEPTH_BUFFER_BIT) zurückgesetzt wird. Die Methode löscht selbst nichts. Sie ändert nur einen Zustand des WebGL-Kontexts, der gültig bleibt, bis er wieder geändert wird.

Der Standardwert ist 1.0, also die größte mögliche Tiefe (die hintere Clipping-Ebene). Das passt zur üblichen Tiefenfunktion gl.LESS: Jedes Fragment, das näher liegt als der gelöschte Wert, besteht den Tiefentest. Arbeitet man mit einer umgekehrten Tiefenfunktion wie gl.GREATER (etwa bei „Reversed-Z“), muss man den Löschwert auf 0.0 setzen.

Den aktuellen Wert fragt man mit gl.getParameter(gl.DEPTH_CLEAR_VALUE) ab. Damit der Tiefenpuffer überhaupt verwendet wird, muss der Kontext einen haben (Kontextattribut depth: true, standardmäßig aktiv) und der Tiefentest muss mit gl.enable(gl.DEPTH_TEST) eingeschaltet sein.

Parameter

Name	Typ	Default	Beschreibung
$depth Pflicht	number (GLclampf)	1.0	Tiefenwert, mit dem der Tiefenpuffer gelöscht wird. Er wird auf den Bereich `0` bis `1` begrenzt (geclampt).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Farb- und Tiefenpuffer pro Frame löschen

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

gl.enable(gl.DEPTH_TEST);
gl.depthFunc(gl.LESS);

// Löschwerte einmalig setzen – sie bleiben Kontext-Zustand
gl.clearColor(0.1, 0.1, 0.1, 1.0);
gl.clearDepth(1.0);

const render = () => {
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
  // ... Zeichenaufrufe ...
  requestAnimationFrame(render);
};
requestAnimationFrame(render);

Aktuellen Löschwert abfragen

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

console.log(gl.getParameter(gl.DEPTH_CLEAR_VALUE));
gl.clearDepth(0.5);
console.log(gl.getParameter(gl.DEPTH_CLEAR_VALUE));

// Werte außerhalb von [0, 1] werden begrenzt
gl.clearDepth(8);
console.log(gl.getParameter(gl.DEPTH_CLEAR_VALUE));

1 0.5 1

Umgekehrter Tiefentest (Reversed-Z)

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

gl.enable(gl.DEPTH_TEST);
// Näher = größerer Tiefenwert
gl.depthFunc(gl.GREATER);
// Deshalb auf die kleinste Tiefe löschen
gl.clearDepth(0.0);
gl.clear(gl.DEPTH_BUFFER_BIT);

// Wichtig · Fallstricke

clearDepth() löscht nichts. Erst gl.clear(gl.DEPTH_BUFFER_BIT) wendet den Wert an.
Löschwert und Tiefenfunktion müssen zusammenpassen: Setzt man clearDepth(0.0) und verwendet dabei gl.LESS, besteht kein Fragment den Tiefentest und es wird nichts gezeichnet.
Wurde der Kontext mit { depth: false } erzeugt, gibt es keinen Tiefenpuffer. Der Aufruf hat dann keine sichtbare Wirkung.
gl.depthMask(false) verhindert auch das Löschen des Tiefenpuffers durch gl.clear().
Die Methode ist in WebGL 1 und WebGL 2 (WebGL2RenderingContext) in allen modernen Browsern verfügbar, auch in Web Workern über OffscreenCanvas.

Siehe auch

WebGLRenderingContext.clear() WebGLRenderingContext.clearColor() WebGLRenderingContext.clearStencil() WebGLRenderingContext.depthFunc() WebGLRenderingContext.depthMask() WebGLRenderingContext WebGLRenderingContext.lineWidth()