WebGLRenderingContext.depthRange() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.depthRange(zNear, zFar)

Beschreibung

Nach der Projektion liegen die z-Werte der Vertices in normalisierten Gerätekoordinaten im Bereich -1 bis 1. depthRange() bestimmt, auf welchen Teilbereich des Tiefenpuffers (0 bis 1) diese Werte linear abgebildet werden. Die Standardwerte sind zNear = 0 und zFar = 1, also der gesamte Tiefenpuffer.

Die Abbildung lautet: z_fenster = ((zFar - zNear) / 2) * z_ndc + (zFar + zNear) / 2. Damit lässt sich der Tiefenpuffer in Bereiche aufteilen, sodass z. B. ein HUD, eine Waffe in einem Ego-Shooter oder eine Skybox gezielt vor bzw. hinter der restlichen Szene gezeichnet wird, ohne den Tiefenpuffer zu leeren.

Die Einstellung ist ein globaler Zustand des Kontexts und gilt für alle folgenden Zeichenaufrufe, bis sie erneut geändert wird. Der aktuelle Wert lässt sich mit gl.getParameter(gl.DEPTH_RANGE) auslesen. Damit der Bereich Wirkung zeigt, muss der Tiefentest mit gl.enable(gl.DEPTH_TEST) aktiviert und ein Tiefenpuffer vorhanden sein.

Parameter

Name	Typ	Default	Beschreibung
$zNear Pflicht	number	0	Abbildung der nahen Clipping-Ebene auf Fenster-Koordinaten. Wird auf `[0, 1]` begrenzt.
$zFar Pflicht	number	1	Abbildung der fernen Clipping-Ebene auf Fenster-Koordinaten. Wird auf `[0, 1]` begrenzt. In WebGL muss `zNear <= zFar` gelten.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Tiefenbereich setzen und auslesen

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

gl.enable(gl.DEPTH_TEST);
gl.depthRange(0.2, 0.7);

// Aktuellen Wert als Float32Array abfragen
console.log(gl.getParameter(gl.DEPTH_RANGE));

Float32Array(2) [0.20000000298023224, 0.699999988079071]

Waffe/HUD immer vor der Szene zeichnen

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

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

  // Welt nutzt den hinteren Teil des Tiefenpuffers
  gl.depthRange(0.1, 1.0);
  drawScene();

  // Waffe nutzt den vordersten Bereich – verdeckt nie durch Wände
  gl.depthRange(0.0, 0.1);
  drawWeapon();

  // Zustand zurücksetzen
  gl.depthRange(0.0, 1.0);
};

renderFrame(() => { /* gl.drawArrays(...) Szene */ }, () => { /* gl.drawArrays(...) Waffe */ });

Skybox auf die ferne Ebene zwingen

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

const drawSkybox = () => {
  // Alle Skybox-Fragmente landen bei Tiefe 1.0
  gl.depthRange(1.0, 1.0);
  gl.depthFunc(gl.LEQUAL); // sonst schlägt der Test bei geleertem Puffer (1.0) fehl
  // gl.drawArrays(gl.TRIANGLES, 0, 36);
  gl.depthFunc(gl.LESS);
  gl.depthRange(0.0, 1.0);
};

drawSkybox();

// Wichtig · Fallstricke

Einschränkung gegenüber OpenGL: In WebGL muss zNear <= zFar sein, sonst erzeugt der Aufruf den Fehler gl.INVALID_OPERATION (prüfbar mit gl.getError()). Ein invertierter Tiefenbereich (z. B. depthRange(1, 0)) ist daher nicht möglich.
Werte außerhalb von [0, 1] werden stillschweigend begrenzt.
Der Tiefenbereich ist globaler Zustand – nach Sonderfällen (HUD, Skybox) immer auf (0, 1) zurücksetzen, sonst wirken sich die Werte auf nachfolgende Draw-Calls aus.
Kleinere Bereiche reduzieren die effektive Tiefenpräzision und können Z-Fighting verstärken.
Ohne Tiefenpuffer (getContext('webgl', { depth: false })) oder ohne aktivierten DEPTH_TEST hat die Methode keinen sichtbaren Effekt.
Verfügbar in allen modernen Browsern, auch in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext.viewport() WebGLRenderingContext.depthFunc() WebGLRenderingContext.depthMask() WebGLRenderingContext.clearDepth() WebGLRenderingContext.enable() WebGLRenderingContext.getParameter()