VRDisplay.depthNear — Eigenschaft · JavaScript-Referenz

Signatur

VRDisplay.depthNear

Beschreibung

VRDisplay.depthNear ist eine les- und schreibbare Eigenschaft der veralteten WebVR-API. Sie legt in Metern fest, wie weit die Nahebene (near clipping plane) des Sichtkegels (Frustum) vom Auge entfernt liegt. Alles, was näher als dieser Wert an der Kamera liegt, wird abgeschnitten und nicht gerendert. Der Standardwert ist 0.01 (1 cm).

Zusammen mit depthFar bestimmt der Wert die Projektionsmatrizen, die in VRFrameData.leftProjectionMatrix und VRFrameData.rightProjectionMatrix geliefert werden, wenn VRDisplay.getFrameData() aufgerufen wird. Ändert man depthNear, wirkt sich das erst auf die nächsten abgefragten Frame-Daten aus.

In der Praxis wählt man den Wert so groß wie möglich, ohne dass nahe Objekte (z. B. Hände oder Controller-Modelle) abgeschnitten werden. Ein zu kleiner Wert verschlechtert die Genauigkeit des Tiefenpuffers deutlich und führt zu Z-Fighting bei weit entfernten Flächen, da die Tiefenauflösung nicht linear verteilt ist.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0.01	Neuer Abstand der Nahebene in Metern beim Schreiben der Eigenschaft. Sollte positiv und kleiner als `depthFar` sein.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle Abstand der Nahebene in Metern (Gleitkommazahl, Standard 0.01).

Beispiele

Aktuellen Wert auslesen

if (navigator.getVRDisplays) {
  navigator.getVRDisplays().then((displays) => {
    if (displays.length === 0) return;
    const vrDisplay = displays[0];
    console.log(`Nahebene: ${vrDisplay.depthNear} m`);
    console.log(`Fernebene: ${vrDisplay.depthFar} m`);
  });
} else {
  console.log('WebVR wird nicht unterstützt');
}

Nahebene: 0.01 m Fernebene: 10000 m

Tiefenbereich für bessere Z-Puffer-Genauigkeit anpassen

const setupDepthRange = async () => {
  const [vrDisplay] = await navigator.getVRDisplays();
  if (!vrDisplay) return null;

  // Szene enthält nichts näher als 10 cm und nichts weiter als 500 m
  vrDisplay.depthNear = 0.1;
  vrDisplay.depthFar = 500;

  const frameData = new VRFrameData();
  vrDisplay.getFrameData(frameData);
  // Projektionsmatrizen berücksichtigen nun den neuen Bereich
  return frameData.leftProjectionMatrix;
};

setupDepthRange().then((m) => console.log(m ? m.length : 'Kein Display'));

16

Moderne Alternative mit WebXR

const startXR = async () => {
  if (!navigator.xr) return console.log('WebXR nicht verfügbar');
  const session = await navigator.xr.requestSession('immersive-vr');
  // Entspricht depthNear/depthFar aus WebVR
  await session.updateRenderState({ depthNear: 0.1, depthFar: 500 });
  console.log(session.renderState.depthNear);
};

document.querySelector('#enter-vr').addEventListener('click', startXR);

0.1

// Wichtig · Fallstricke

Veraltet: Die WebVR-API wurde nie standardisiert und ist aus allen aktuellen Browsern entfernt bzw. nur hinter Flags verfügbar (früher Firefox, Chrome für Android/Daydream, Oculus Browser). Für neue Projekte XRRenderState.depthNear über XRSession.updateRenderState() verwenden.
Ein sehr kleiner Wert (z. B. 0.0001) reduziert die Tiefenpuffer-Präzision stark und verursacht Flimmern (Z-Fighting) bei entfernten Objekten.
depthNear sollte stets kleiner als depthFar sein, sonst entstehen unbrauchbare Projektionsmatrizen.
Die Änderung wirkt erst beim nächsten getFrameData()-Aufruf; bereits abgefragte Matrizen werden nicht aktualisiert.
Die API ist nur in sicheren Kontexten (HTTPS) sinnvoll nutzbar.

Siehe auch

VRDisplay VRDisplay.depthFar VRDisplay.getFrameData() VRFrameData XRRenderState.depthNear XRSession.updateRenderState() Translator.inputQuota