XRRenderState.depthNear — Eigenschaft · JavaScript-Referenz

Signatur

XRRenderState.depthNear

Beschreibung

XRRenderState.depthNear gibt an, wie weit die nahe Abschneideebene des Sichtvolumens (View Frustum) vom Auge des Betrachters entfernt ist, gemessen in Metern. Alles, was näher liegt, wird vom Rendering abgeschnitten. Zusammen mit depthFar legt der Wert fest, welche Tiefen in die Projektionsmatrizen einfließen, die die Laufzeitumgebung über XRView.projectionMatrix zur Verfügung stellt.

Die Eigenschaft ist schreibgeschützt. Ändern lässt sich der Wert nur über XRSession.updateRenderState({ depthNear }). Die Änderung gilt erst ab dem nächsten Animationsframe. Vorher meldet session.renderState.depthNear noch den alten Wert. Der Standardwert ist 0.1 (10 cm).

In der Praxis passt man depthNear an die Szene an: Kleine Werte erlauben es, Objekte sehr nah am Auge darzustellen, etwa Hände oder Controller. Sie verschlechtern aber die Genauigkeit des Tiefenpuffers und führen schneller zu Z-Fighting. Für große Außenszenen ist deshalb ein größerer Near-Wert sinnvoll.

Rückgabewert

Typ

number

Beschreibung

Abstand der nahen Abschneideebene in Metern (Gleitkommazahl, double). Standardwert ist 0.1.

Beispiele

Aktuellen Near-Wert einer Sitzung auslesen

const session = await navigator.xr.requestSession('immersive-vr');
console.log(`Nahe Ebene: ${session.renderState.depthNear} m`);
console.log(`Ferne Ebene: ${session.renderState.depthFar} m`);

Nahe Ebene: 0.1 m Ferne Ebene: 1000 m

Near- und Far-Ebene für eine Nahbereichsszene anpassen

const startXR = async (gl) => {
  const session = await navigator.xr.requestSession('immersive-vr');
  await gl.makeXRCompatible();

  session.updateRenderState({
    baseLayer: new XRWebGLLayer(session, gl),
    depthNear: 0.01, // 1 cm – Controller dicht am Auge sichtbar
    depthFar: 50
  });

  // Die Änderung wirkt erst im nächsten Frame
  console.log('Sofort:', session.renderState.depthNear);

  session.requestAnimationFrame(() => {
    console.log('Im nächsten Frame:', session.renderState.depthNear);
  });
  return session;
};

Sofort: 0.1 Im nächsten Frame: 0.01

Eigene Kamera an den Render-State angleichen (z. B. für Culling)

const onXRFrame = (time, frame) => {
  const session = frame.session;
  const { depthNear, depthFar } = session.renderState;

  // Objekte außerhalb des Tiefenbereichs gar nicht erst zeichnen
  const isVisible = (distance) => distance >= depthNear && distance <= depthFar;
  console.log(isVisible(0.05), isVisible(2));

  session.requestAnimationFrame(onXRFrame);
};

const session = await navigator.xr.requestSession('immersive-vr');
session.requestAnimationFrame(onXRFrame);

false true

// Wichtig · Fallstricke

Schreibgeschützt: Eine direkte Zuweisung wie renderState.depthNear = 0.01 hat keine Wirkung. Ändern lässt sich der Wert nur mit session.updateRenderState(), und die Änderung greift erst im nächsten Frame.
Tiefengenauigkeit: Je kleiner depthNear und je größer das Verhältnis depthFar / depthNear, desto ungenauer arbeitet der Tiefenpuffer (Z-Fighting). Wähle depthNear daher so groß, wie die Szene es zulässt.
Wertebereich: Negative Werte werden auf 0 begrenzt. depthNear darf größer als depthFar sein. Dann wird eine umgekehrte Tiefe (Reverse-Z) verwendet, die Tiefentest-Logik (gl.depthFunc) muss entsprechend angepasst werden.
Projektionsmatrix nutzen: Baue keine eigene Projektionsmatrix mit anderen Near-/Far-Werten, sondern verwende XRView.projectionMatrix. Sie berücksichtigt depthNear bereits.
Kompatibilität: WebXR funktioniert nur in einem sicheren Kontext (HTTPS) und wird derzeit hauptsächlich von Chromium-basierten Browsern unterstützt. Prüfe vorher mit navigator.xr?.isSessionSupported(), ob WebXR verfügbar ist.

Siehe auch

XRRenderState XRRenderState.depthFar XRRenderState.inlineVerticalFieldOfView XRSession.prototype.updateRenderState() XRSession.renderState XRView.projectionMatrix ScreenDetailed.isPrimary