XRSession.depthUsage — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.depthUsage

Beschreibung

Die Eigenschaft depthUsage gehört zum WebXR-Modul Depth Sensing. Wenn man eine AR-Sitzung mit dem Feature "depth-sensing" anfordert, gibt man in depthSensing.usagePreference eine Liste bevorzugter Nutzungsarten an. Der Browser (User Agent) wählt daraus eine Nutzungsart aus. Welche er gewählt hat, steht danach in depthUsage.

Mögliche Werte:

"cpu-optimized": Die Tiefendaten werden im Arbeitsspeicher bereitgestellt. Man liest sie über XRFrame.getDepthInformation(view) aus und erhält ein XRCPUDepthInformation-Objekt mit data und getDepthInMeters(x, y). Das eignet sich für Physik, Kollisionsabfragen oder einzelne Messpunkte.
"gpu-optimized": Die Tiefendaten liegen als WebGL-Textur vor. Man holt sie über XRWebGLBinding.getDepthInformation(view) und erhält ein XRWebGLDepthInformation-Objekt mit texture. Das eignet sich für Verdeckungseffekte (Occlusion) direkt im Shader.

Der Wert ändert sich während der Sitzung nicht. Lies ihn deshalb gleich nach dem Start der Sitzung aus und wähle danach den passenden Code-Pfad (CPU oder GPU) zum Auslesen der Tiefendaten. Zusammen mit XRSession.depthDataFormat beschreibt er vollständig, wie die Tiefendaten zu verarbeiten sind.

Rückgabewert

Typ

"cpu-optimized" | "gpu-optimized"

Beschreibung

Ein String aus der Aufzählung XRDepthUsage. Er gibt an, welche Nutzungsart der Browser für die Tiefensensoren gewählt hat.

Beispiele

AR-Sitzung mit Tiefenerkennung starten und Nutzungsart prüfen

const startAR = async () => {
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['depth-sensing'],
    depthSensing: {
      usagePreference: ['cpu-optimized', 'gpu-optimized'],
      dataFormatPreference: ['luminance-alpha', 'float32']
    }
  });

  console.log('Nutzung:', session.depthUsage);
  console.log('Format:', session.depthDataFormat);
  return session;
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#ar-button').addEventListener('click', startAR);

Nutzung: cpu-optimized Format: luminance-alpha

Abstand zur Bildmitte auf der CPU messen

const onXRFrame = (time, frame) => {
  const session = frame.session;
  session.requestAnimationFrame(onXRFrame);

  if (session.depthUsage !== 'cpu-optimized') return;

  const pose = frame.getViewerPose(refSpace);
  if (!pose) return;

  for (const view of pose.views) {
    const depthInfo = frame.getDepthInformation(view);
    if (!depthInfo) continue;
    // Normierte Koordinaten 0..1
    const meters = depthInfo.getDepthInMeters(0.5, 0.5);
    console.log(`Abstand Mitte: ${meters.toFixed(2)} m`);
  }
};

session.requestAnimationFrame(onXRFrame);

Abstand Mitte: 1.37 m

Je nach Nutzungsart CPU- oder GPU-Pfad wählen

const setupDepth = (session, gl) => {
  if (session.depthUsage === 'gpu-optimized') {
    const binding = new XRWebGLBinding(session, gl);
    return (frame, view) => {
      const info = binding.getDepthInformation(view);
      // info.texture im Occlusion-Shader binden
      return info?.texture ?? null;
    };
  }
  // cpu-optimized
  return (frame, view) => frame.getDepthInformation(view)?.data ?? null;
};

const readDepth = setupDepth(session, gl);
console.log(typeof readDepth);

function

// Wichtig · Fallstricke

Nur mit angeforderter Tiefenerkennung: Wurde die Sitzung ohne das Feature "depth-sensing" erstellt, wirft der Zugriff auf depthUsage laut Spezifikation einen InvalidStateError (DOMException). Steht das Feature nur in optionalFeatures, muss man also damit rechnen, dass es fehlt, und den Zugriff in try...catch einschließen.
Falscher Pfad führt zu Fehlern: Wer bei "gpu-optimized" trotzdem XRFrame.getDepthInformation() aufruft (oder umgekehrt bei "cpu-optimized" die WebGL-Bindung nutzt), bekommt einen NotSupportedError. Verzweige deshalb immer anhand von depthUsage.
Präferenzliste wird nicht garantiert erfüllt: Die usagePreference ist ein Wunsch, keine Zusage. Wird keine der angegebenen Nutzungsarten unterstützt, schlägt die Anforderung fehl, wenn depth-sensing in requiredFeatures steht.
Kompatibilität: Die Eigenschaft ist experimentell und nur in Chromium-Browsern unter Android mit ARCore-Unterstützung verfügbar. Sie erfordert einen sicheren Kontext (HTTPS) und eine Nutzeraktion zum Starten der Sitzung. Firefox und Safari unterstützen sie nicht.
Datenschutz: Tiefendaten können Rückschlüsse auf die Umgebung des Nutzers zulassen. Browser können deshalb eine zusätzliche Zustimmung verlangen.

Siehe auch

XRSession.depthDataFormat XRSession XRFrame.getDepthInformation() XRWebGLBinding.getDepthInformation() XRCPUDepthInformation XRWebGLDepthInformation XRSystem.requestSession()