WebXR Lighting Estimation API Level 1

1. Introduction

The WebXR Lighting Estimation module expands the WebXR Device API, the WebXR Augmented Reality Module, and the WebXR Layers module with the ability to expose estimates of the lighting conditions of the user’s environment.

2. Light Primitives

2.1. XRLightProbe

An XRLightProbe collects estimated lighting information at a given point in the user’s environment.

[SecureContext, Exposed=Window]
interface XRLightProbe : EventTarget {
  readonly attribute XRSpace probeSpace;
  attribute EventHandler onreflectionchange;
};

The probeSpace attribute is an XRSpace that has a native origin tracking the position and orientation that the XRLightProbe's lighting estimations are being generated relative to.

The onreflectionchange attribute is an Event handler IDL attribute for the reflectionchange event type.

2.2. XRReflectionFormat

enum XRReflectionFormat {
  "srgba8",
  "rgba16f",
};

Reflection cube maps have an internal reflection format that indicates how the texture data is represented, and may change how applications choose to use the texture. Cube maps MAY be requested with the "srgba8" format or the preferredReflectionFormat of the light probe.

2.3. XRLightEstimate

An XRLightEstimate provides the estimated lighting values for an XRLightProbe at the time represented by an XRFrame. XRLightEstimates are queried by passing an XRLightProbe to the getLightEstimate() method of an XRFrame.

[SecureContext, Exposed=Window]
interface XRLightEstimate {
  readonly attribute Float32Array sphericalHarmonicsCoefficients;
  readonly attribute DOMPointReadOnly primaryLightDirection;
  readonly attribute DOMPointReadOnly primaryLightIntensity;
};

The sphericalHarmonicsCoefficients attribute returns a Float32Array containing 9 spherical harmonics coefficients. The array MUST be 27 elements in length, with every 3 elements defining the red, green, and blue components respectively of a single coefficient. The first term of the sphericalHarmonicsCoefficients, meaning the first 3 elements of the array, MUST be representative of a valid lighting estimate. All other terms are optional, and MAY be 0 if a corresponding lighting estimate is not available due to either user privacy settings or the capabilities of the platform.

The order of coefficients in sphericalHarmonicsCoefficients, is [C₀⁰, C₁^-1, C₁⁰, C₁¹, C₂^-2, C₂^-1, C₂⁰, C₂¹, C₂²], where C_l^m is the coefficient of spherical harmonic Y_l^m.

The primaryLightDirection represents the direction to the primary light source from the native origin of the probeSpace of the XRLightProbe that produced the XRLightEstimate. The value MUST be a unit length 3D vector and the w value MUST be 0.0. If estimated values from the users’s environment are not available the primaryLightDirection MUST be { x: 0.0, y: 1.0, z: 0.0, w: 0.0 }, representing a light shining straight down from above.

The primaryLightIntensity represents the direction to the primary light source from the origin of the probeSpace of the XRLightProbe that produced the XRLightEstimate. The value MUST represent an RGB value mapped to the x, y, and z values respectively where each component is greater than or equal to 0.0 and the w value MUST be 1.0. If estimated values from the users’s environment are not available the primaryLightIntensity MUST be {x: 0.0, y: 0.0, z: 0.0, w: 1.0}, representing no illumination.

3. WebXR Device API Integration

Both the XRSession and XRFrame interfaces from the WebXR Device API are expanded by this module.

3.1. Session Initialization

The string "light-estimation" is introduced by this module as a new valid feature descriptor. Applications that wish to use light estimation features MUST be requested with an the "light-estimation" feature descriptor.

3.2. XRSession

The XRSession interface is extended with the ability to create new XRLightProbe instances. XRLightProbe instances have a session object, which is the XRSession that created this XRLightProbe. And an reflection format object, which is the XRReflectionFormat that the light probe may retrieve.

The XRSession interface is further extended with an attribute preferredReflectionFormat, indicating the XRReflectionFormat most closely supported by the underlying XR device

dictionary XRLightProbeInit {
  XRReflectionFormat reflectionFormat = "srgba8";
};

partial interface XRSession {
  Promise<XRLightProbe> requestLightProbe(optional XRLightProbeInit options = {});
  readonly attribute XRReflectionFormat preferredReflectionFormat;
};

3.3. XRFrame

The XRFrame interface is extended with the ability to query the XRLightEstimate for a given XRLightProbe.

partial interface XRFrame {
  XRLightEstimate? getLightEstimate(XRLightProbe lightProbe);
};

4. WebXR Layers Integration

The XRWebGLBinding interface from the WebXR Layers module is expanded by this module.

4.1. XRWebGLBinding

The XRWebGLBinding interface is extended with the ability to query a reflection cube map for a given XRLightProbe.

partial interface XRWebGLBinding {
  WebGLTexture? getReflectionCubeMap(XRLightProbe lightProbe);
};

5. Events

The task source for all tasks queued in this specification is the XR task source, unless otherwise specified.

5.1. Event Types

The user agent MUST fire a reflectionchange event on an XRLightProbe object each time the contents of the cube map returned by calling getReflectionCubeMap() have changed. The event MUST be of type Event.

6. Privacy & Security Considerations