# AutoExposureEffect

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

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/extras/effects/auto-exposure/auto-exposure-effect.js#L52

The auto exposure effect, which adapts the exposure of the camera to the brightness of what it
sees, like the eye adapting to the dark or to the daylight. Every frame, it measures a histogram
of the brightness of the screen and averages the part of it between two fractions of the
screen, leaving out the darkest and the brightest parts, such as deep shadows and the sun. It
then changes the exposure gradually towards the one which displays that average as middle
gray.

The exposure it adapts is the one the camera renders with: the exposure of the scene, or the
exposure of the physical camera with physical units, which it scales by up to
[AutoExposureEffect#minEv](https://api.playcanvas.com/engine/classes/AutoExposureEffect.md#minev) and [AutoExposureEffect#maxEv](https://api.playcanvas.com/engine/classes/AutoExposureEffect.md#maxev) stops. Every part of the
frame which uses the exposure follows it, the tone mapping of the composition and the
anti-aliasing among them. It has no effect without tone mapping, as the composition then applies
no exposure.

The histogram is read back to the CPU, so the exposure follows the screen a frame or two late,
which the gradual adaptation hides. It is not registered by default - add it to a
[CameraFrame](https://api.playcanvas.com/engine/classes/CameraFrame.md):

```javascript
const autoExposure = new AutoExposureEffect(app.graphicsDevice);
cameraFrame.addEffect(autoExposure);
cameraFrame.update();
```

## Constructors

### constructor

```ts
new AutoExposureEffect(device: GraphicsDevice)
```

**Parameters**

- `device` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device.

## Properties

### centerWeight

```ts
centerWeight: number = 0.5
```

How much the brightness of the center of the screen counts over its edges, 0-1 range. 0
meters the whole screen equally, 1 mostly its center. Defaults to 0.5.

### compensation

```ts
compensation: number = 0
```

The exposure compensation in EV: how much brighter than middle gray the average of the
screen is displayed. Positive values brighten the image, negative values darken it, each
step doubling or halving it. Defaults to 0.

### highPercent

```ts
highPercent: number = 0.9
```

The fraction of the screen, 0-1, below which the average is taken, the brightest part above
it left out, such as the sun and bright highlights. Defaults to 0.9.

### lowPercent

```ts
lowPercent: number = 0.1
```

The fraction of the screen, 0-1, which is left out of the average as the darkest part of it,
such as deep shadows. Higher values meter the brighter parts of the screen, darkening the
image. Defaults to 0.1.

### maxEv

```ts
maxEv: number = 6
```

The highest exposure the effect adapts to, in EV relative to the exposure of the camera: 2
lets it brighten the image four times, for dark scenes. Defaults to 6.

### minEv

```ts
minEv: number = -6
```

The lowest exposure the effect adapts to, in EV relative to the exposure of the camera: -2
lets it darken the image to a quarter of its brightness, for bright scenes. Defaults to -6.

### speedDarkToLight

```ts
speedDarkToLight: number = 3
```

How fast the exposure adapts when the scene gets brighter, as from a dark interior into the
daylight. Higher values adapt faster - the exposure covers about two thirds of the change in
1 / speedDarkToLight seconds. Defaults to 3.

### speedLightToDark

```ts
speedLightToDark: number = 1
```

How fast the exposure adapts when the scene gets darker, as from the daylight into a dark
interior. Higher values adapt faster - the exposure covers about two thirds of the change in
1 / speedLightToDark seconds. The eye adapts to the dark more slowly than to the light.
Defaults to 1.

## Accessors

### active

```ts
get active(): boolean
```

Gets whether the effect contributes to the frame: while enabled, and while the composition
applies tone mapping, as without it no exposure is applied.

### cameraExposureScale

```ts
get cameraExposureScale(): number
```

Gets the scale the adaptation applies to the exposure of the camera this frame, 2 raised to
the adaptation in EV.

### exposure

```ts
get exposure(): number
```

Gets the exposure the camera renders with this frame: the exposure of the scene, or of the
physical camera with physical units, scaled by the adaptation.

### histogram

```ts
get histogram(): Uint32Array<ArrayBufferLike>
```

Gets the latest histogram of the brightness of the screen read back, the weight of each of
its 64 bins, from the darkest to the brightest. The bins span the brightness the limits of
the exposure display as middle gray, and 4 EV beyond on either side; brightness outside of
that counts in the bin at the end. The array is updated in place as histograms arrive.

## Methods

### frameUpdate

```ts
frameUpdate(frame: CameraFrameEffectContext): void
```

**Parameters**

- `frame` ([`CameraFrameEffectContext`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectContext.md)): The values of this frame.

### reset

```ts
reset(): void
```

Adapts the exposure to the next measurement at once, rather than gradually - for a cut to a
different view, after which a gradual adaptation would look out of place.

### update

```ts
update(): void
```

Applies the effect's parameters. Called by [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update) while the effect is
active: set the uniform values with [CameraFrameEffect#setUniform](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setuniform) here, and the
defines which depend on the parameters.
Everything it sets is what the frames rendered until the next update use.

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

- `cameraFrame: CameraFrame | null = null`

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

- `device: GraphicsDevice`
- `enabled: boolean = true`
- `get chunkName(): string`
- `get debugViews(): string[]`
- `get defineName(): string`
- `get entryPoint(): string`
- `get glsl(): string | null`
- `get id(): string`
- `get requires(): string[]`
- `get slot(): string | null`
- `get wgsl(): string | null`
- `buildKey(): string`
- `destroy(): void`
- `getChunk(shaderLanguage: string): string | null`
- `resolveScene(scene: CameraFrameEffectScene): void`
- `setDefine(name: string, value: any): void`
- `setUniform(name: string, value: number | number[] | ArrayBufferView<ArrayBufferLike> | Texture): void`
