# XrLightEstimation

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: XR

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/xr/xr-light-estimation.js#L26

Light Estimation provides illumination data from the real world, which is estimated by the
underlying AR system. It provides a reflection Cube Map, that represents the reflection
estimation from the viewer position. A more simplified approximation of light is provided by L2
Spherical Harmonics data. And the most simple level of light estimation is the most prominent
directional light, its rotation, intensity and color.

## Accessors

### available

```ts
get available(): boolean
```

True if estimated light information is available.

**Example**

```ts
if (app.xr.lightEstimation.available) {
    entity.light.intensity = app.xr.lightEstimation.intensity;
}
```

### color

```ts
get color(): Color | null
```

Color of what is estimated to be the most prominent directional light. Or null if data is
not available.

### intensity

```ts
get intensity(): number | null
```

Intensity of what is estimated to be the most prominent directional light. Or null if data
is not available.

### rotation

```ts
get rotation(): Quat | null
```

Rotation of what is estimated to be the most prominent directional light. Or null if data is
not available.

### sphericalHarmonics

```ts
get sphericalHarmonics(): Float32Array<ArrayBufferLike> | null
```

Spherical harmonic coefficients of estimated ambient light. Or null if data is not available.

### supported

```ts
get supported(): boolean
```

True if Light Estimation is supported. This information is available only during an active AR
session.

## Methods

### end

```ts
end(): void
```

End estimation of illumination data.

### start

```ts
start(): void
```

Start estimation of illumination data. Availability of such data will come later and an
`available` event will be fired. If it failed to start estimation, an `error` event will be
fired.

**Example**

```ts
app.xr.on('start', () => {
    if (app.xr.lightEstimation.supported) {
        app.xr.lightEstimation.start();
    }
});
```

## Events

### EVENT_AVAILABLE

```ts
static EVENT_AVAILABLE: string = 'available'
```

Fired when light estimation data becomes available.

**Example**

```ts
app.xr.lightEstimation.on('available', () => {
    console.log('Light estimation is available');
});
```

### EVENT_ERROR

```ts
static EVENT_ERROR: string = 'error'
```

Fired when light estimation has failed to start. The handler is passed the Error object
related to failure of light estimation start.

**Example**

```ts
app.xr.lightEstimation.on('error', (error) => {
    console.error(error.message);
});
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`