XRSession.requestLightProbe() — Methode · JavaScript-Referenz

Signatur

XRSession.prototype.requestLightProbe(options)

Beschreibung

Die Methode requestLightProbe() gehört zur WebXR-Erweiterung Lighting Estimation. Sie erzeugt ein XRLightProbe-Objekt. Über dieses Objekt schätzt der Browser in AR-Sitzungen, wie die reale Umgebung beleuchtet ist. Damit können virtuelle Objekte glaubwürdig in die Kamerasicht eingeblendet werden: mit passender Umgebungshelligkeit, Farbe, Richtung der Hauptlichtquelle und Spiegelungen.

Die Sonde selbst liefert noch keine Lichtwerte. Die eigentlichen Daten fragst du in jedem Frame mit XRFrame.getLightEstimate(lightProbe) ab. Das Ergebnis ist ein XRLightEstimate mit sphärischen Harmonischen (sphericalHarmonicsCoefficients), primaryLightDirection und primaryLightIntensity. Eine Würfeltextur (Cube Map) für Spiegelungen erhältst du über XRWebGLBinding.getReflectionCubeMap(lightProbe). Das Ereignis reflectionchange der Sonde meldet, wann sich die Cube Map geändert hat.

Voraussetzung: Die Sitzung muss mit dem Feature "light-estimation" angefordert worden sein, als requiredFeatures oder optionalFeatures in navigator.xr.requestSession(). In der Praxis ist das meist eine "immersive-ar"-Sitzung. Die Sonde forderst du idealerweise einmal nach dem Start der Sitzung an und verwendest sie dann in allen Frames.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt.
$options.reflectionFormat	"srgba8" \| "rgba16f"	"srgba8"	Internes Format der Cube Map für Spiegelungen. `"srgba8"` wird immer unterstützt. `"rgba16f"` (HDR) funktioniert nur, wenn es dem Wert von `XRSession.preferredReflectionFormat` entspricht.

Rückgabewert

Typ

Promise<XRLightProbe>

Beschreibung

Ein Promise, das mit einem XRLightProbe-Objekt erfüllt wird. Es wird abgelehnt mit NotSupportedError, wenn das Feature "light-estimation" nicht aktiviert ist oder das gewünschte reflectionFormat nicht unterstützt wird, und mit InvalidStateError, wenn die Sitzung bereits beendet ist.

Beispiele

AR-Sitzung mit Lichtschätzung starten und Sonde anfordern

const startAR = async () => {
  if (!(await navigator.xr?.isSessionSupported('immersive-ar'))) {
    console.log('AR wird nicht unterstützt');
    return;
  }

  const session = await navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['light-estimation']
  });

  try {
    const lightProbe = await session.requestLightProbe();
    console.log('Lichtsonde bereit:', lightProbe.probeSpace);
  } catch (err) {
    console.warn('Keine Lichtschätzung verfügbar:', err.name);
  }
};

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

Lichtsonde bereit: XRSpace {}

Lichtwerte pro Frame auslesen

const refSpace = await session.requestReferenceSpace('local');
const lightProbe = await session.requestLightProbe();

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

  const estimate = frame.getLightEstimate(lightProbe);
  if (!estimate) return; // noch keine Schätzung vorhanden

  const { x, y, z } = estimate.primaryLightDirection;
  const i = estimate.primaryLightIntensity;
  // z. B. gerichtetes Licht in der 3D-Engine anpassen
  sunLight.position.set(x, y, z);
  sunLight.intensity = Math.max(i.x, i.y, i.z);
  // estimate.sphericalHarmonicsCoefficients: Float32Array mit 27 Werten (9 × RGB)
};

session.requestAnimationFrame(onFrame);

HDR-Spiegelungen mit bevorzugtem Format

const format = session.preferredReflectionFormat; // "srgba8" oder "rgba16f"
const lightProbe = await session.requestLightProbe({ reflectionFormat: format });

const glBinding = new XRWebGLBinding(session, gl);

lightProbe.addEventListener('reflectionchange', () => {
  const cubeMap = glBinding.getReflectionCubeMap(lightProbe);
  if (cubeMap) {
    // WebGLTexture als Umgebungs-Map für PBR-Materialien verwenden
    updateEnvironmentMap(cubeMap);
  }
});

console.log('Spiegelungsformat:', format);

Spiegelungsformat: srgba8

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell. Sie funktioniert derzeit praktisch nur in Chromium-Browsern unter Android mit ARCore. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher, ob die Funktion existiert ('requestLightProbe' in XRSession.prototype).
Ohne das Feature "light-estimation" beim Start der Sitzung schlägt das Promise mit NotSupportedError fehl. Wenn du das Feature als optional anforderst, kann die Sitzung trotzdem ohne Lichtschätzung starten. Fange den Fehler also ab.
Fordere "rgba16f" nur an, wenn session.preferredReflectionFormat diesen Wert meldet. Andernfalls wird das Promise abgelehnt.
frame.getLightEstimate() kann in den ersten Frames null liefern. Prüfe den Wert deshalb vor der Verwendung.
WebXR erfordert einen sicheren Kontext (HTTPS). Die Sitzung darf nur nach einer Nutzeraktion angefordert werden.
Datenschutz: Beleuchtungsdaten können Rückschlüsse auf die Umgebung des Nutzers zulassen. Browser können die Werte deshalb ungenauer machen oder eine Zustimmung verlangen.

Siehe auch

XRLightProbe XRLightEstimate XRFrame.getLightEstimate() XRWebGLBinding.getReflectionCubeMap() XRSession.preferredReflectionFormat XRSystem.requestSession() XRSession