XRSession.preferredReflectionFormat — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.preferredReflectionFormat

Beschreibung

Die Eigenschaft preferredReflectionFormat gehört zur WebXR Lighting Estimation API. Sie gibt an, in welchem Format das XR-Gerät bzw. die Plattform Reflexionsdaten (Umgebungs-Cubemaps) von sich aus am effizientesten bereitstellt. Mögliche Werte des Aufzählungstyps XRReflectionFormat sind:

"srgba8": 8 Bit pro Kanal, sRGB-kodiert (RGBA). Dieses Format wird immer unterstützt.
"rgba16f": 16-Bit-Gleitkommazahlen pro Kanal (HDR), also ein größerer Dynamikumfang für realistischere Reflexionen.

Du nutzt den Wert typischerweise beim Aufruf von XRSession.requestLightProbe({ reflectionFormat }). Wählst du das bevorzugte Format, muss der Browser die Daten nicht umrechnen. Das spart Rechenzeit und erhält die Qualität. Die Cubemap selbst bekommst du danach über XRWebGLBinding.getReflectionCubeMap(lightProbe) als WebGLTexture.

Damit die Eigenschaft sinnvoll genutzt werden kann, muss die Sitzung als "immersive-ar" mit dem Feature "light-estimation" angefordert worden sein. Die Eigenschaft ist schreibgeschützt und ändert sich während der Sitzung nicht.

Rückgabewert

Typ

string ("srgba8" | "rgba16f")

Beschreibung

Das bevorzugte XRReflectionFormat der Sitzung als Zeichenkette.

Beispiele

Bevorzugtes Format auslesen

const startAR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-ar'))) {
    console.log('immersive-ar wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['light-estimation']
  });
  console.log('Bevorzugtes Reflexionsformat:', session.preferredReflectionFormat);
};

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

Bevorzugtes Reflexionsformat: srgba8

Light Probe im bevorzugten Format anfordern

const setupLighting = async (session) => {
  const lightProbe = await session.requestLightProbe({
    reflectionFormat: session.preferredReflectionFormat
  });

  lightProbe.addEventListener('reflectionchange', () => {
    console.log('Neue Umgebungsreflexion verfügbar');
  });

  return lightProbe;
};

Reflexions-Cubemap mit WebGL2 abrufen

const initReflections = async (session, gl) => {
  // gl muss ein XR-kompatibler WebGL2RenderingContext sein
  const binding = new XRWebGLBinding(session, gl);

  // rgba16f nur verwenden, wenn WebGL2 vorhanden ist, sonst sicheres srgba8
  const format = session.preferredReflectionFormat === 'rgba16f' &&
    gl instanceof WebGL2RenderingContext
      ? 'rgba16f'
      : 'srgba8';

  const lightProbe = await session.requestLightProbe({ reflectionFormat: format });

  let cubeMap = null;
  lightProbe.addEventListener('reflectionchange', () => {
    cubeMap = binding.getReflectionCubeMap(lightProbe);
    gl.bindTexture(gl.TEXTURE_CUBE_MAP, cubeMap);
  });

  console.log('Verwendetes Format:', format);
};

Verwendetes Format: rgba16f

// Wichtig · Fallstricke

Experimentell: Die API wird bisher nur von Chromium-Browsern auf Android mit ARCore unterstützt (Chrome 90+). Firefox und Safari unterstützen sie nicht. Frage vorher mit 'preferredReflectionFormat' in XRSession.prototype ab, ob sie vorhanden ist.
Die Eigenschaft ist erst nutzbar, wenn die Sitzung mit dem Feature "light-estimation" angefordert wurde. Fehlt das Feature, schlägt requestLightProbe() mit einem NotSupportedError fehl.
"srgba8" wird immer unterstützt. Für "rgba16f" braucht getReflectionCubeMap() einen WebGL2-Kontext oder in WebGL1 die Erweiterung OES_texture_half_float. Andernfalls kann ein Fehler auftreten.
Schreibzugriffe auf die Eigenschaft werden ignoriert (im strikten Modus lösen sie einen TypeError aus).
WebXR gibt es nur in sicheren Kontexten (HTTPS). Außerdem muss die Seite per Permissions-Policy xr-spatial-tracking zugelassen sein.

Siehe auch

XRSession XRSession.requestLightProbe() XRLightProbe XRWebGLBinding.getReflectionCubeMap() XRLightEstimate XRSystem.requestSession() XRSession.enabledFeatures