XRWebGLLayer.ignoreDepthValues — Eigenschaft · JavaScript-Referenz

Signatur

XRWebGLLayer.ignoreDepthValues

Beschreibung

Die Eigenschaft ignoreDepthValues einer XRWebGLLayer zeigt an, ob der XR-Compositor die Werte im Tiefenpuffer der Ebene beachtet. Der Compositor ist der Teil der Laufzeitumgebung, der dein gerendertes Bild für das Headset aufbereitet. Ist der Wert false, liest er den Tiefenpuffer aus und erwartet, dass dieser die Szene korrekt abbildet. Damit kann er zum Beispiel die Reprojektion verbessern (Positions-Timewarp) oder die Szene richtig mit Systemebenen und der realen Umgebung überlagern. Ist der Wert true, ignoriert er die Tiefenwerte vollständig.

Du legst den Wert nicht direkt fest, sondern gibst beim Erzeugen der Ebene über das Wörterbuch XRWebGLLayerInit einen Wunsch an (ignoreDepthValues: true). Welchen Wert die Eigenschaft danach tatsächlich hat, entscheidet der Browser. Auch wenn du false anforderst, kann sie true sein, etwa wenn der Compositor grundsätzlich keine Tiefeninformationen nutzt oder die Ebene keinen Tiefenpuffer hat (depth: false).

Nützlich ist die Eigenschaft vor allem, um das eigene Rendering anzupassen. Liefert sie false, sollte dein Tiefenpuffer echte, lineare Szenentiefen enthalten. depthNear und depthFar im XRRenderState müssen dann zu deiner Projektion passen. Tricks, die den Tiefenpuffer „missbrauchen“, sind in diesem Fall problematisch, zum Beispiel Skyboxen auf maximaler Tiefe oder UI-Elemente mit manipulierter Tiefe. Liefert sie true, darfst du den Tiefenpuffer frei für eigene Zwecke nutzen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der XR-Compositor die Tiefenwerte der Ebene ignoriert. false, wenn er sie auswertet und du deshalb korrekte Szenentiefen liefern musst. Der Wert ist schreibgeschützt und steht nach dem Erzeugen der Ebene fest.

Beispiele

Ebene mit ignorierten Tiefenwerten anlegen und prüfen

const startXR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-vr'))) {
    console.log('immersive-vr wird nicht unterstützt');
    return;
  }

  // Muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
  const session = await navigator.xr.requestSession('immersive-vr');
  const canvas = document.createElement('canvas');
  const gl = canvas.getContext('webgl2', { xrCompatible: true });

  const layer = new XRWebGLLayer(session, gl, {
    antialias: true,
    depth: true,
    ignoreDepthValues: true // Wunsch: Compositor soll die Tiefe ignorieren
  });

  session.updateRenderState({ baseLayer: layer });
  console.log('Tiefe ignoriert:', layer.ignoreDepthValues);
};

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

Tiefe ignoriert: true

Rendering an die Auswertung der Tiefe anpassen

const configureDepth = (session, layer) => {
  if (layer.ignoreDepthValues) {
    // Compositor liest den Tiefenpuffer nicht aus: freie Nutzung möglich
    console.log('Tiefenpuffer darf frei genutzt werden (z. B. Skybox-Trick)');
  } else {
    // Compositor wertet die Tiefe aus: korrekte Werte liefern
    session.updateRenderState({ depthNear: 0.1, depthFar: 100 });
    console.log('Echte Szenentiefe erforderlich, depthNear/depthFar gesetzt');
  }
};

// Aufruf nach dem Erzeugen der Ebene:
// configureDepth(session, session.renderState.baseLayer);

Echte Szenentiefe erforderlich, depthNear/depthFar gesetzt

Aktive Basisebene während der Sitzung abfragen

const logDepthMode = (session) => {
  const layer = session.renderState.baseLayer;
  if (!layer) {
    console.log('Keine Basisebene gesetzt');
    return;
  }
  console.log(
    `Compositor nutzt Tiefenwerte: ${!layer.ignoreDepthValues ? 'ja' : 'nein'}`
  );
};

// z. B. innerhalb des Frame-Callbacks:
// session.requestAnimationFrame((time, frame) => logDepthMode(frame.session));

Compositor nutzt Tiefenwerte: ja

// Wichtig · Fallstricke

Nur ein Wunsch: Mit ignoreDepthValues in XRWebGLLayerInit äußerst du nur eine Präferenz. Verlass dich nicht darauf, sondern lies nach dem Erzeugen immer die Eigenschaft aus. Wenn der Compositor keine Tiefe unterstützt, ist sie auch dann true, wenn du false angefordert hast.
Schreibgeschützt: Eine Zuweisung wie layer.ignoreDepthValues = false hat keine Wirkung und wirft im Strict Mode einen TypeError. Um den Wert zu ändern, musst du eine neue XRWebGLLayer erzeugen und per updateRenderState() setzen.
Korrekte Tiefe liefern: Ist der Wert false, führen falsche Tiefenwerte oder abweichende depthNear/depthFar-Werte zu Artefakten bei der Reprojektion und bei der Überlagerung (Zittern, falsche Verdeckung).
Kompatibilität: Die WebXR Device API gibt es nur in sicheren Kontexten (HTTPS). Unterstützt wird sie vor allem in Chromium-Browsern und im Meta Quest Browser. Firefox und Safari (Desktop) unterstützen sie nicht. Prüfe daher vorher auf navigator.xr. Für neue Projekte mit mehreren Ebenen lohnt sich ein Blick auf die WebXR Layers API (XRProjectionLayer).

Siehe auch

XRWebGLLayer XRWebGLLayer.antialias XRWebGLLayer.framebuffer XRRenderState.depthNear XRRenderState.depthFar XRSession.updateRenderState()