/** * 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 * {@link AutoExposureEffect#minEv} and {@link AutoExposureEffect#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 * {@link CameraFrame}: * * ```javascript * const autoExposure = new AutoExposureEffect(app.graphicsDevice); * cameraFrame.addEffect(autoExposure); * cameraFrame.update(); * ``` * * @category Graphics */ export class AutoExposureEffect extends CameraFrameEffect { /** * @param {GraphicsDevice} device - The graphics device. */ constructor(device: GraphicsDevice); /** * 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. * * @type {number} */ compensation: number; /** * 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. * * @type {number} */ minEv: number; /** * 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. * * @type {number} */ maxEv: number; /** * 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. * * @type {number} */ speedDarkToLight: number; /** * 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. * * @type {number} */ speedLightToDark: number; /** * 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. * * @type {number} */ lowPercent: number; /** * 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. * * @type {number} */ highPercent: number; /** * 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. * * @type {number} */ centerWeight: number; /** * The passes of the effect, while they exist. * * @type {FramePassLuminanceHistogram|null} * @private */ private _pass; /** * The camera frame the passes were created for. They render for it until it next updates, even * once the effect is removed from it. * * @type {CameraFrame|null} * @private */ private _passesCameraFrame; /** * The latest histogram read back. * * @private */ private _histogram; /** * The log2 luminance of the average of the latest histogram, or null before the first one * arrives. * * @type {number|null} * @private */ private _averageLog2; /** * The adaptation, in EV relative to the exposure of the camera. * * @private */ private _ev; /** * Whether the next measurement is adapted to at once. * * @private */ private _snap; /** * Incremented by {@link AutoExposureEffect#reset}, and tagging each histogram measured, so that * the histograms measured before a reset - the view before a cut - are not adapted to. * * @private */ private _measurement; /** @private */ private _exposure; /** @private */ private _exposureScale; /** @private */ private _compensation; /** @private */ private _minEv; /** @private */ private _maxEv; /** @private */ private _speedDarkToLight; /** @private */ private _speedLightToDark; /** @private */ private _lowPercent; /** @private */ private _highPercent; /** @private */ private _centerWeight; /** @private */ private _bars; /** @private */ private _barsRange; /** @private */ private _markers; /** * 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. * * @type {number} */ get exposure(): number; /** * 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. * * @type {Uint32Array} */ get histogram(): Uint32Array; /** * 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. */ reset(): void; /** * Takes a histogram read back. * * @param {Uint32Array} histogram - The weight of each bin. * @param {number} rangeMin - The log2 luminance the first bin counts. * @param {number} rangeMax - The log2 luminance the last bin counts. * @param {number} tag - The measurement the histogram belongs to, see the reset. * @private */ private _measure; } import { CameraFrameEffect } from '../../render-passes/camera-frame-effect.js'; import type { GraphicsDevice } from '../../../platform/graphics/graphics-device.js';