XRProjectionLayer.ignoreDepthValues — Eigenschaft · JavaScript-Referenz

Signatur

XRProjectionLayer.ignoreDepthValues

Beschreibung

Die Eigenschaft ignoreDepthValues der Schnittstelle XRProjectionLayer gibt an, ob der XR-Kompositor die Tiefeninformationen der Ebene nutzt. Ist der Wert true, verwendet der Kompositor den Tiefenpuffer nicht, etwa für tiefenbasierte Reprojektion (Positional Timewarp) oder für die korrekte Verdeckung zwischen mehreren Ebenen.

Der Wert wird beim Erzeugen der Ebene über XRWebGLBinding.createProjectionLayer() festgelegt. Wird dort kein Tiefenformat angegeben (depthFormat: 0), gibt es keinen Tiefenpuffer und ignoreDepthValues ist true. Das Gerät bzw. der Kompositor kann Tiefenwerte aber auch dann ignorieren, wenn es tiefenbasierte Verfahren grundsätzlich nicht unterstützt.

In der Praxis dient die Eigenschaft vor allem zur Laufzeitprüfung: Ist sie false, sollte die Anwendung gültige Tiefenwerte (mit passenden depthNear/depthFar-Werten der Sitzung) in die Tiefentextur schreiben. Bei true kann man sich den Aufwand sparen, die Tiefe für den Kompositor sauber zu füllen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Kompositor die Tiefenwerte der Ebene nicht verwendet, sonst false. Schreibgeschützt.

Beispiele

Projektionsebene mit Tiefenpuffer erzeugen und prüfen

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2', { xrCompatible: true });

const session = await navigator.xr.requestSession('immersive-vr', {
  requiredFeatures: ['layers']
});

const binding = new XRWebGLBinding(session, gl);
const layer = binding.createProjectionLayer({
  textureType: 'texture',
  colorFormat: gl.RGBA8,
  depthFormat: gl.DEPTH_COMPONENT24
});

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

Tiefe ignoriert: false

Ebene ohne Tiefenpuffer

const layer = binding.createProjectionLayer({
  textureType: 'texture',
  colorFormat: gl.RGBA8,
  depthFormat: 0 // kein Tiefenpuffer
});

console.log(layer.ignoreDepthValues);

true

Rendering abhängig von ignoreDepthValues anpassen

const renderFrame = (time, frame) => {
  const pose = frame.getViewerPose(refSpace);
  if (!pose) return;

  for (const view of pose.views) {
    const sub = binding.getViewSubImage(layer, view);
    gl.bindFramebuffer(gl.FRAMEBUFFER, fb);
    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0,
      gl.TEXTURE_2D, sub.colorTexture, 0);

    if (!layer.ignoreDepthValues && sub.depthStencilTexture) {
      // Kompositor nutzt die Tiefe: gültige Werte schreiben
      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT,
        gl.TEXTURE_2D, sub.depthStencilTexture, 0);
      gl.enable(gl.DEPTH_TEST);
    }

    const { x, y, width, height } = sub.viewport;
    gl.viewport(x, y, width, height);
    drawScene(view);
  }
  frame.session.requestAnimationFrame(renderFrame);
};

session.requestAnimationFrame(renderFrame);

// Wichtig · Fallstricke

Experimentell: Die WebXR Layers API ist bisher im Wesentlichen nur in Chromium-basierten Browsern verfügbar (v. a. Meta Quest Browser), und die Sitzung muss mit dem Feature 'layers' angefordert werden. Firefox und Safari unterstützen sie nicht. Vorher per 'XRWebGLBinding' in window prüfen.
Die Eigenschaft ist schreibgeschützt. Ändern lässt sich das Verhalten nur, indem man die Ebene mit einem anderen depthFormat neu erzeugt.
Der Wert false heißt nicht, dass die Tiefe automatisch korrekt ist: Ungültige oder nicht geschriebene Tiefenwerte können bei der Reprojektion zu Bildfehlern führen. Die Tiefe muss zu session.renderState.depthNear/depthFar passen.
Nur in einer sicheren Umgebung (HTTPS) verfügbar.

Siehe auch

XRProjectionLayer XRWebGLBinding.createProjectionLayer() XRProjectionLayer.fixedFoveation XRWebGLBinding.getViewSubImage() XRWebGLSubImage XRSession.updateRenderState()