XRRenderState.depthFar — Eigenschaft · JavaScript-Referenz

Signatur

XRRenderState.depthFar

Beschreibung

Die Eigenschaft depthFar des XRRenderState-Objekts einer XRSession gibt an, wie weit die ferne Clipping-Ebene vom Betrachter entfernt ist, in Metern. Geometrie hinter dieser Ebene wird nicht gezeichnet. Zusammen mit depthNear legt sie das Sichtvolumen (Frustum) fest, aus dem der Browser die Projektionsmatrizen berechnet. Diese Matrizen erhältst du pro Frame über XRView.projectionMatrix.

Der Standardwert ist 1000.0 (also 1 km). Ändern kannst du ihn nur über XRSession.updateRenderState({ depthFar }). Direkt zuweisen lässt sich die Eigenschaft nicht, denn session.renderState ist ein unveränderlicher Schnappschuss. Die neuen Werte gelten erst ab dem nächsten Animations-Frame.

Wähle den Wert passend zur Szene. Ist depthFar zu groß und depthNear gleichzeitig sehr klein, sinkt die Genauigkeit des Tiefenpuffers und es kommt zu Z-Fighting: Flächen, die dicht hintereinander liegen, flackern. Bei Innenraum- oder AR-Szenen reichen oft 20–100 m.

Rückgabewert

Typ

number

Beschreibung

Abstand der fernen Clipping-Ebene in Metern (Gleitkommazahl, Standard 1000). Er ist immer größer als depthNear, es sei denn, das Gerät unterstützt eine umgekehrte Tiefe (Reversed-Z).

Beispiele

Aktuellen Wert auslesen

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

Clipping: 0.1 m bis 1000 m

Far Plane für eine Innenraum-Szene verkleinern

const session = await navigator.xr.requestSession('immersive-ar');

// Bessere Tiefenpuffer-Genauigkeit für einen Raum von ca. 20 m
session.updateRenderState({ depthNear: 0.05, depthFar: 50 });

session.requestAnimationFrame((time, frame) => {
  // Ab diesem Frame gilt der neue Wert
  console.log(session.renderState.depthFar);
});

50

Kamera einer 3D-Engine synchronisieren

const syncCamera = (session, camera) => {
  const { depthNear, depthFar } = session.renderState;
  camera.near = depthNear;
  camera.far = depthFar;
  camera.updateProjectionMatrix?.();
};

const onFrame = (time, frame) => {
  syncCamera(frame.session, myCamera);
  frame.session.requestAnimationFrame(onFrame);
};
xrSession.requestAnimationFrame(onFrame);

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie session.renderState.depthFar = 100 bleibt wirkungslos. Setze den Wert stattdessen mit updateRenderState().
Verzögerte Wirkung: Nach updateRenderState() meldet renderState den neuen Wert erst im nächsten Frame.
Die Werte werden an den Grenzen des Geräts beschnitten (Clamping). Der tatsächlich verwendete Wert kann deshalb vom gewünschten abweichen. Lies ihn im Frame immer erneut aus.
Nutze für das Rendering immer XRView.projectionMatrix und berechne keine eigene Matrix aus depthNear/depthFar. Die Projektion kann asymmetrisch sein.
Kompatibilität: WebXR erfordert einen sicheren Kontext (HTTPS). Chromium-basierte Browser und XR-Headsets unterstützen es. Firefox und Safari (Desktop) unterstützen WebXR nicht. Visions Safari unterstützt WebXR teilweise.

Siehe auch

XRRenderState XRRenderState.depthNear XRSession.updateRenderState() XRSession.renderState XRView.projectionMatrix ByteLengthQueuingStrategy.highWaterMark ScreenDetailed.isInternal