rayzee 11.3.0 → 11.4.0

package/src/Stages/AutoExposure.js

@@ -1,705 +1,695 @@
-import { Fn, wgslFn, vec4, float, int, uint, ivec2, uvec2, uniform, If, max,
-	textureLoad, textureStore, workgroupBarrier, localId, workgroupId,
-	attributeArray, atomicAdd, atomicStore, atomicLoad, Loop } from 'three/tsl';
-import { RenderTarget, TextureNode, StorageTexture, ReadbackBuffer } from 'three/webgpu';
-import { FloatType, RGBAFormat, NearestFilter } from 'three';
+import { Fn, float, int, uint, ivec2, vec2, vec4, uniform, If, Loop, max, min, select, exp, log2, dot,
+	textureLoad, workgroupArray, workgroupBarrier, localId, workgroupId, attributeArray,
+	atomicAdd, atomicLoad, atomicStore, floatBitsToUint } from 'three/tsl';
+import { TextureNode, ReadbackBuffer } from 'three/webgpu';
+import { Matrix3, Vector2, Vector3 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
-import { luminance } from '../TSL/Common.js';
+import { getWorkingMatrix } from '../Color/WorkingMatrix.js';
 
-// ── Histogram constants ────────────────────────────────────
 export const AUTO_EXPOSURE_DEFAULTS = {
 	autoExposure: false,
+	autoExposureMetering: 'center',
+	autoExposureStrength: 0.3,
 	autoExposureKeyValue: 0.18,
-	autoExposureMinExposure: 0.1,
-	autoExposureMaxExposure: 20.0,
+	autoExposureMinExposure: 2 ** - 8, // how far it may go from the manual exposure, as Bevy's range: ±8 stops
+	autoExposureMaxExposure: 2 ** 8,
 	autoExposureAdaptSpeedBright: 3.0,
-	autoExposureAdaptSpeedDark: 0.5,
+	autoExposureAdaptSpeedDark: 1.0,
 };
 
-const NUM_BINS = 256;
-const MIN_LOG_LUM = - 8.0; // ln(~0.00034)  — very dark
-const MAX_LOG_LUM = 6.0; // ln(~403)     — bright specular
-const LOG_LUM_RANGE = MAX_LOG_LUM - MIN_LOG_LUM; // 14 nats ≈ 20 stops
-const BIN_WIDTH = LOG_LUM_RANGE / NUM_BINS;
-const WEIGHT_SCALE = 10000; // float → uint quantisation for metering weights
+export const METERING_MODES = [ 'average', 'center', 'spot' ];
+
+const GRID = 64; // metering tiles per axis at most
+const MIN_TILE = 8; // pixels per tile side at least, so a one-sample image averages enough of them
+const WG = 8;
+const BINS = 256;
+const LOG2_MIN = - 16;
+const LOG2_MAX = 12;
+const BIN_STOPS = ( LOG2_MAX - LOG2_MIN ) / BINS;
+// A tile below this has no light to meter: a black or transparent background is not part of the exposure.
+const BLACK = 2 ** - 24;
+const WEIGHT_SCALE = 65536;
+const MAX_TILE_READS = 256;
+const SPOT_FALLOFF = 128; // Gaussian over image heights: σ ≈ 6 % of the frame height
+const TRANSITION_STOPS = 1.5;
+const SETTLED_STOPS = 0.01;
+// Seconds for an accumulating image's exposure to close the gap by e: it lands in ~0.3 s. Easing is for a picture
+// that keeps changing; a still one is being looked at, and a low-sample render finishes before an eased exposure lands.
+const LAND_SECONDS = 0.06;
+const MAX_STEP_SECONDS = 0.25;
+const ROOM_SECONDS = 4; // camera motion the room level takes to follow
+const MOTION_HOLD = 0.3; // a metering of a new view counts as motion for this long
+const DAMP_UNTIL = 1.5; // stops from the manual exposure: the room level is damped up to here...
+const FOLLOW_FROM = 3; // ...and followed fully from here
+const REC709_Y = [ 0.2126, 0.7152, 0.0722 ];
 
-// ── Metering ────────────────────────────────────────────────
-// Centre-weighted Gaussian is the only mode — spot and uniform
-// are unnecessary given the percentile clipping already handles
-// extreme highlights/shadows. The centerWeight uniform controls
-// the Gaussian falloff steepness.
+/**
+ * One adaptation step in stops: constant speed while far, exponential near the target, never past it.
+ * @param {number} current - exposure, log2
+ * @param {number} target - exposure, log2
+ * @param {number} dt - seconds; Infinity lands on the target
+ * @param {number} speedBright - stops a second while the scene gets brighter (exposure falls)
+ * @param {number} speedDark - stops a second while it gets darker
+ */
+export function adaptExposureEV( current, target, dt, speedBright, speedDark ) {
 
-// ── wgslFn helpers ──────────────────────────────────────────
+	const delta = target - current;
+	if ( delta === 0 || ! ( dt > 0 ) ) return current;
+	const speed = Math.max( delta < 0 ? speedBright : speedDark, 1e-3 );
+	if ( dt === Infinity ) return target;
+	const step = Math.min( speed * dt, Math.abs( delta ) * ( 1 - Math.exp( - speed * dt / TRANSITION_STOPS ) ) );
+	return current + Math.sign( delta ) * step;
+
+}
 
 /**
- * Temporal adaptation: map luminance → target exposure, smooth asymmetrically.
- *
- * Returns vec4f(exposure, luminance, targetExposure, 1.0).
+ * Where the exposure aims, in stops from the manual exposure: the room level, damped to `strength` near the
+ * manual exposure and followed far from it, plus the view's difference from the room at `strength`.
  */
-const adaptExposure = /*@__PURE__*/ wgslFn( `
-	fn adaptExposure(
-		geoMean: f32,
-		prevExposure: f32,
-		keyValue: f32,
-		minExp: f32,
-		maxExp: f32,
-		speedBright: f32,
-		speedDark: f32,
-		dt: f32,
-		isFirstFrame: f32
-	) -> vec4f {
-
-		let targetExp = clamp( keyValue / max( geoMean, 0.001 ), minExp, maxExp );
-		var newExposure = targetExp;
-
-		// Temporal smoothing (skip on first frame)
-		if ( isFirstFrame < 0.5 ) {
-
-			// Asymmetric speed: brighter scenes adapt faster
-			let speed = select( speedDark, speedBright, targetExp < prevExposure );
-			let alpha = 1.0 - exp( -dt * speed );
-			newExposure = mix( prevExposure, targetExp, alpha );
+export function blendExposureEV( room, view, strength ) {
 
-		}
+	const a = Math.abs( room );
+	const w = a <= DAMP_UNTIL ? strength : a >= FOLLOW_FROM ? 1 : strength + ( 1 - strength ) * ( a - DAMP_UNTIL ) / ( FOLLOW_FROM - DAMP_UNTIL );
+	return room * w + strength * ( view - room );
 
-		return vec4f( newExposure, geoMean, targetExp, 1.0 );
+}
 
-	}
-` );
+// Luminance weights of the working space: Rec.709's Y row through the working matrix's inverse.
+function workingLuminance( matrix, out ) {
+
+	if ( ! matrix ) return out.fromArray( REC709_Y );
+	const inv = new Matrix3().set( ...matrix ).invert().elements; // column-major
+	return out.set(
+		REC709_Y[ 0 ] * inv[ 0 ] + REC709_Y[ 1 ] * inv[ 1 ] + REC709_Y[ 2 ] * inv[ 2 ],
+		REC709_Y[ 0 ] * inv[ 3 ] + REC709_Y[ 1 ] * inv[ 4 ] + REC709_Y[ 2 ] * inv[ 5 ],
+		REC709_Y[ 0 ] * inv[ 6 ] + REC709_Y[ 1 ] * inv[ 7 ] + REC709_Y[ 2 ] * inv[ 8 ],
+	);
+
+}
+
+// Fewer meterings as the image converges: its metered brightness settles like the noise does.
+const meterInterval = samples => samples < 16 ? 1 : samples < 64 ? 4 : 16;
 
 /**
- * WebGPU Auto-Exposure Stage — Histogram-Based with Centre-Weighted Metering
- *
- * GPU-based automatic exposure control with human eye-like adaptation.
- * Uses histogram-based luminance analysis with percentile clipping
- * and centre-weighted spatial metering for robust exposure estimation.
- *
- * Algorithm:
- *   1. Downsample (compute): full res → 64×64 log-luminance grid
- *   2. Histogram (compute): build 256-bin weighted histogram from the 64×64
- *      grid. Single workgroup of 256 threads; each loads 16 texels, applies
- *      centre-weighted Gaussian, and scatters via atomicAdd into a storage buffer.
- *   3. Analyze (compute): single thread reads the histogram, computes CDF,
- *      extracts percentile-clipped weighted mean (ignoring bottom/top
- *      extremes), and writes the geometric mean to a 1×1 storage texture.
- *   4. Adaptation (compute): temporal smoothing with prev exposure; writes
- *      vec4(exposure, luminance, targetExposure, 1) into a 1-element buffer.
- *   5. Async readback via `renderer.getArrayBufferAsync(attr, ReadbackBuffer)`.
- *
- * Execution: ALWAYS
+ * Auto exposure: meters the accumulated image on the GPU and adapts on the CPU.
  *
- * Events listened:
- *   pipeline:reset              — soft reset (keeps the exposure, discards an in-flight readback)
- *   pipeline:lightingChanged    — a new model or environment: start the exposure history over
+ * Tiles are averaged in linear light, weighted by alpha, so a one-sample image meters like the
+ * converged one; the percentile-clipped mean of their log2 histogram is read back. It aims at a room
+ * level learned while the view changes plus a damped share of each view (`blendExposureEV`), moves in
+ * stops every loop frame (`update()`: eased while the image restarts every frame, landing in ~0.3 s once
+ * it accumulates), in video time (`advance()`, eased), or with each metering (`instant`), and is applied
+ * as 2^EV × the manual exposure.
  *
- * Textures published:  (none — publishes state, not textures)
- * Textures read:       edgeFiltering:output > asvgf:output > pathtracer:color
- * State published:     autoexposure:value, autoexposure:avgLuminance
+ * Events listened: pipeline:reset, pipeline:lightingChanged (lands on the next metering)
+ * Textures read: pathtracer:color
+ * State published: autoexposure:value, autoexposure:avgLuminance
  */
 export class AutoExposure extends RenderStage {
 
 	constructor( renderer, options = {} ) {
 
-		super( 'AutoExposure', {
-			...options,
-			executionMode: StageExecutionMode.ALWAYS
-		} );
+		super( 'AutoExposure', { ...options, executionMode: StageExecutionMode.ALWAYS } );
 
 		this.renderer = renderer;
 
-		// Reduction constant
-		this.REDUCTION_SIZE = 64;
+		this.metering = options.metering ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMetering;
+		this.meteringPoint = new Vector2( 0.5, 0.5 ); // image uv, y down
+		this.keyValue = options.keyValue ?? AUTO_EXPOSURE_DEFAULTS.autoExposureKeyValue;
+		this.minExposure = options.minExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMinExposure;
+		this.maxExposure = options.maxExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMaxExposure;
+		this.adaptSpeedBright = options.adaptSpeedBright ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedBright;
+		this.adaptSpeedDark = options.adaptSpeedDark ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedDark;
+		this.centerWeight = options.centerWeight ?? 8.0;
+		this.strength = options.strength ?? AUTO_EXPOSURE_DEFAULTS.autoExposureStrength;
+		this.instant = false;
+		// Readings of an image with fewer samples leave an existing exposure where it is (a final render's first
+		// samples meter its many bounces noisily); a reading through meter() is always taken.
+		this.holdSamples = 0;
+		/** Called when a metering moves the target, or a change needs a frame; the viewer wakes its loop. */
+		this.onChange = null;
+
+		this._lowU = uniform( options.lowPercentile ?? 0.10 );
+		this._highU = uniform( options.highPercentile ?? 0.90 );
+		this._falloffU = uniform( new Vector2() );
+		this._pointU = uniform( new Vector2( 0.5, 0.5 ) );
+		this._lumWeightsU = uniform( new Vector3().fromArray( REC709_Y ) );
+		this._widthU = uniform( 1, 'int' );
+		this._heightU = uniform( 1, 'int' );
+		this._strideU = uniform( 1, 'int' );
+		this._gridXU = uniform( GRID, 'int' );
+		this._gridYU = uniform( GRID, 'int' );
+		this._inputNode = new TextureNode();
+		this._workingMatrix = undefined;
+
+		this._histogram = attributeArray( BINS, 'uint' ).toAtomic();
+		this._result = attributeArray( 1, 'vec4' );
+		this._readback = new ReadbackBuffer( 16 );
+		this._readback.name = 'AutoExposure';
+		this._kernels = [ this._buildTileKernel(), this._buildResolveKernel() ];
+
+		this._compensation = 1;
+		this._exposureEV = 0;
+		this._targetEV = null;
+		this._viewEV = null;
+		this._roomEV = null;
+		this._clock = 0;
+		this._movingUntil = - 1;
+		this._viewMoves = 0;
+		this._landed = null;
+		this._meteredLog2 = null;
+		this._snap = true;
+		this._lastUpdate = null;
+		this._accumulating = false;
+		this._emittedEV = null;
+		this._pending = null;
+		this._generation = 0;
+		this._restarts = 0;
+		this._meteredAt = { restarts: - 1, samples: - 1 };
+		this._stale = false;
+		this._disposed = false;
 
-		// ── Adaptation uniforms ──────────────────────────
+	}
 
-		this.keyValueU = uniform( options.keyValue ?? AUTO_EXPOSURE_DEFAULTS.autoExposureKeyValue );
-		this.minExposureU = uniform( options.minExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMinExposure );
-		this.maxExposureU = uniform( options.maxExposure ?? AUTO_EXPOSURE_DEFAULTS.autoExposureMaxExposure );
-		this.adaptSpeedBrightU = uniform( options.adaptSpeedBright ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedBright );
-		this.adaptSpeedDarkU = uniform( options.adaptSpeedDark ?? AUTO_EXPOSURE_DEFAULTS.autoExposureAdaptSpeedDark );
-		this.epsilonU = uniform( options.epsilon ?? 0.0001 );
-		this.deltaTimeU = uniform( 1.0 / 60.0 );
-		this.isFirstFrameU = uniform( 1.0 ); // 1.0 = true
-		this.previousExposureU = uniform( options.initialExposure ?? 1.0 );
+	// ── Kernels ──────────────────────────────────────────────
 
-		// ── Histogram & metering uniforms ────────────────
+	_buildTileKernel() {
 
-		this.lowPercentileU = uniform( options.lowPercentile ?? 0.10 );
-		this.highPercentileU = uniform( options.highPercentile ?? 0.90 );
-		this.centerWeightU = uniform( options.centerWeight ?? 8.0 );
+		const input = this._inputNode;
+		const hist = this._histogram;
+		const width = this._widthU, height = this._heightU, stride = this._strideU, gridX = this._gridXU, gridY = this._gridYU;
+		const lumWeights = this._lumWeightsU, falloff = this._falloffU, point = this._pointU;
 
-		// ── Input resolution uniforms (for downsample compute) ──
+		return Fn( () => {
 
-		this.inputResW = uniform( 1 );
-		this.inputResH = uniform( 1 );
+			const lid = localId.y.mul( uint( WG ) ).add( localId.x );
+			const tx = int( workgroupId.x ), ty = int( workgroupId.y );
+			const x0 = tx.mul( width ).div( gridX ).toVar(), x1 = tx.add( int( 1 ) ).mul( width ).div( gridX ).toVar();
+			const y0 = ty.mul( height ).div( gridY ).toVar(), y1 = ty.add( int( 1 ) ).mul( height ).div( gridY ).toVar();
+			const step = stride.mul( int( WG ) );
 
-		// ── Input texture nodes (swap .value, no recompile) ──
+			const sum = float( 0 ).toVar();
+			const cover = float( 0 ).toVar();
 
-		this._inputTexNode = new TextureNode();
-		this._reductionReadTexNode = new TextureNode();
+			// Whole 8×8 blocks, every stride-th: skipping single pixels would still fetch their memory.
+			Loop( { start: y0.add( int( localId.y ) ), end: y1, type: 'int', condition: '<', update: step, name: 'py' }, ( { py } ) => {
 
-		// ── CPU-side state ───────────────────────────────
+				Loop( { start: x0.add( int( localId.x ) ), end: x1, type: 'int', condition: '<', update: step, name: 'px' }, ( { px } ) => {
 
-		this.currentExposure = options.initialExposure ?? 1.0;
-		this.currentLuminance = 0.18;
-		this.targetExposure = 1.0;
-		this.lastTime = performance.now();
-		this.isFirstFrame = true;
-		this._pendingReadback = false;
-		this._readbackGeneration = 0;
+					const c = textureLoad( input, ivec2( px, py ) );
+					const lum = dot( c.xyz, lumWeights ).toVar();
+					// NaN or Inf would poison the whole tile.
+					const finite = floatBitsToUint( lum ).bitAnd( uint( 0x7f800000 ) ).notEqual( uint( 0x7f800000 ) );
+					const alpha = c.w.clamp( 0.0, 1.0 );
+					sum.addAssign( select( finite, lum.clamp( 0.0, 1e6 ), float( 0 ) ).mul( alpha ) );
+					cover.addAssign( alpha );
 
-		// ── Render targets & storage textures ────────────
+				} );
 
-		this._initRenderTargets();
-		this._buildCompute();
+			} );
 
-	}
+			const sharedSum = workgroupArray( 'float', WG * WG );
+			const sharedCover = workgroupArray( 'float', WG * WG );
+			sharedSum.element( lid ).assign( sum );
+			sharedCover.element( lid ).assign( cover );
+			workgroupBarrier();
 
-	_initRenderTargets() {
-
-		const rtOpts = {
-			type: FloatType,
-			format: RGBAFormat,
-			minFilter: NearestFilter,
-			magFilter: NearestFilter,
-			depthBuffer: false,
-			stencilBuffer: false
-		};
-
-		// Downsample RenderTarget (64×64) — copy destination from compute StorageTexture
-		this._downsampleTarget = new RenderTarget( this.REDUCTION_SIZE, this.REDUCTION_SIZE, rtOpts );
-
-		// Downsample StorageTexture (64×64) — compute writes here
-		this._downsampleStorageTex = new StorageTexture( this.REDUCTION_SIZE, this.REDUCTION_SIZE );
-		this._downsampleStorageTex.type = FloatType;
-		this._downsampleStorageTex.format = RGBAFormat;
-		this._downsampleStorageTex.minFilter = NearestFilter;
-		this._downsampleStorageTex.magFilter = NearestFilter;
-
-		// 1×1 StorageTexture for histogram analysis output
-		this._reductionStorageTex = new StorageTexture( 1, 1 );
-		this._reductionStorageTex.type = FloatType;
-		this._reductionStorageTex.format = RGBAFormat;
-		this._reductionStorageTex.minFilter = NearestFilter;
-		this._reductionStorageTex.magFilter = NearestFilter;
-
-		// 1×1 RenderTarget — readable copy of analysis output (cross-dispatch reads
-		// from StorageTexture return zeros — must copy to RenderTarget first)
-		this._reductionReadTarget = new RenderTarget( 1, 1, rtOpts );
-
-		// Adaptation result — 1×vec4 storage buffer attribute. Compute writes
-		// vec4(exposure, luminance, targetExposure, 1) here; CPU reads via
-		// getArrayBufferAsync + a pooled ReadbackBuffer (16 bytes).
-		this._adaptationResult = attributeArray( 1, 'vec4' );
-		this._readbackBuffer = new ReadbackBuffer( 16 );
-		this._readbackBuffer.name = 'AutoExposureAdaptation';
-
-		// ── Histogram storage buffer (atomic uint, 256 bins) ─────
-		this._histogramBuffer = attributeArray( NUM_BINS, 'uint' ).toAtomic();
+			for ( let s = ( WG * WG ) >> 1; s > 0; s >>= 1 ) {
 
-	}
+				If( lid.lessThan( uint( s ) ), () => {
 
-	// ──────────────────────────────────────────────────
-	// TSL shader builders
-	// ──────────────────────────────────────────────────
+					sharedSum.element( lid ).addAssign( sharedSum.element( lid.add( uint( s ) ) ) );
+					sharedCover.element( lid ).addAssign( sharedCover.element( lid.add( uint( s ) ) ) );
 
-	_buildCompute() {
+				} );
+				workgroupBarrier();
 
-		this._buildDownsampleCompute();
-		this._buildHistogramCompute();
-		this._buildHistogramAnalyzeCompute();
-		this._buildAdaptationCompute();
+			}
 
-	}
+			If( lid.equal( uint( 0 ) ), () => {
 
-	/**
-	 * Downsample (compute): full resolution → 64×64
-	 *
-	 * Dispatch: [8, 8, 1] workgroups of [8, 8, 1] = 64×64 threads total.
-	 * Each thread (one output pixel) samples a NxN grid from the input texture.
-	 *
-	 * Output: R = Σ log(L + ε), G = valid pixel count
-	 */
-	_buildDownsampleCompute() {
+				const total = sharedSum.element( uint( 0 ) ).toVar();
+				const covered = sharedCover.element( uint( 0 ) ).toVar();
+				const readsAlong = ( span ) => span.div( step ).mul( int( WG ) ).add( min( span.mod( step ), int( WG ) ) );
+				const reads = float( readsAlong( x1.sub( x0 ) ).mul( readsAlong( y1.sub( y0 ) ) ) );
 
-		const inputTex = this._inputTexNode;
-		const outputTex = this._downsampleStorageTex;
-		const epsilon = this.epsilonU;
-		const resW = this.inputResW;
-		const resH = this.inputResH;
+				If( covered.greaterThan( 0.0 ).and( total.greaterThan( covered.mul( BLACK ) ) ), () => {
 
-		const SAMPLES = 4;
-		const OUT_SIZE = 64;
-		const WG_SIZE = 8;
+					const level = log2( total.div( covered ) );
+					const bin = uint( level.sub( LOG2_MIN ).div( BIN_STOPS ).floor().clamp( 0.0, BINS - 1 ) );
+					const uv = vec2( float( x0.add( x1 ) ).div( float( width ) ), float( y0.add( y1 ) ).div( float( height ) ) ).mul( 0.5 );
+					const d = uv.sub( point );
+					const weight = exp( dot( d.mul( d ), falloff ).negate() ).mul( covered.div( max( reads, 1.0 ) ) );
+					const q = uint( weight.mul( WEIGHT_SCALE ).add( 0.5 ) );
+					If( q.greaterThan( uint( 0 ) ), () => {
+
+						atomicAdd( hist.element( bin ), q );
+
+					} );
 
-		const computeFn = Fn( () => {
+				} );
 
-			// Global thread ID → output pixel coordinate
-			const gx = int( workgroupId.x ).mul( WG_SIZE ).add( int( localId.x ) );
-			const gy = int( workgroupId.y ).mul( WG_SIZE ).add( int( localId.y ) );
+			} );
 
-			// Block size in input pixels: how many input pixels each output pixel covers
-			const blockW = resW.div( float( OUT_SIZE ) );
-			const blockH = resH.div( float( OUT_SIZE ) );
+		} )().compute( [ GRID, GRID, 1 ], [ WG, WG, 1 ] );
 
-			// Block origin in input pixel space
-			const blockOriginX = float( gx ).mul( blockW );
-			const blockOriginY = float( gy ).mul( blockH );
+	}
 
-			const logLumSum = float( 0.0 ).toVar();
-			const validCount = float( 0.0 ).toVar();
+	_buildResolveKernel() {
 
-			// Sample a SAMPLES×SAMPLES grid within the block
-			for ( let sy = 0; sy < SAMPLES; sy ++ ) {
+		const hist = this._histogram;
+		const result = this._result;
+		const low = this._lowU, high = this._highU;
 
-				for ( let sx = 0; sx < SAMPLES; sx ++ ) {
+		return Fn( () => {
 
-					// Offset within block: (sx+0.5)/SAMPLES normalised to block size
-					const inputX = int( blockOriginX.add( float( ( sx + 0.5 ) / SAMPLES ).mul( blockW ) ) );
-					const inputY = int( blockOriginY.add( float( ( sy + 0.5 ) / SAMPLES ).mul( blockH ) ) );
+			const t = localId.x;
+			const weight = float( atomicLoad( hist.element( t ) ) ).toVar();
+			atomicStore( hist.element( t ), uint( 0 ) );
 
-					const sample = textureLoad( inputTex, ivec2( inputX, inputY ) );
-					const lum = luminance( sample.xyz );
+			const scan = workgroupArray( 'float', BINS );
+			const levels = workgroupArray( 'float', BINS );
+			scan.element( t ).assign( weight );
+			workgroupBarrier();
 
-					If( lum.greaterThan( epsilon ), () => {
+			for ( let offset = 1; offset < BINS; offset <<= 1 ) {
 
-						logLumSum.addAssign( lum.add( epsilon ).log() );
-						validCount.addAssign( 1.0 );
+				const v = scan.element( t ).toVar();
+				If( t.greaterThanEqual( uint( offset ) ), () => {
 
-					} );
+					v.addAssign( scan.element( t.sub( uint( offset ) ) ) );
 
-				}
+				} );
+				workgroupBarrier();
+				scan.element( t ).assign( v );
+				workgroupBarrier();
 
 			}
 
-			textureStore(
-				outputTex,
-				uvec2( uint( gx ), uint( gy ) ),
-				vec4( logLumSum, validCount, 0.0, 1.0 )
-			).toWriteOnly();
+			const total = scan.element( uint( BINS - 1 ) ).toVar();
+			const above = scan.element( t ).toVar();
+			workgroupBarrier();
 
-		} );
+			// Only the bin's share inside the percentiles: a bin crossing one moves the mean smoothly.
+			const part = max( min( above, total.mul( high ) ).sub( max( above.sub( weight ), total.mul( low ) ) ), 0.0 );
+			scan.element( t ).assign( part );
+			levels.element( t ).assign( part.mul( float( t ).add( 0.5 ).mul( BIN_STOPS ).add( LOG2_MIN ) ) );
+			workgroupBarrier();
 
-		this._downsampleComputeNode = computeFn().compute(
-			[ OUT_SIZE / WG_SIZE, OUT_SIZE / WG_SIZE, 1 ],
-			[ WG_SIZE, WG_SIZE, 1 ]
-		);
+			for ( let s = BINS >> 1; s > 0; s >>= 1 ) {
 
-	}
+				If( t.lessThan( uint( s ) ), () => {
 
-	/**
-	 * Histogram Build (compute): 64×64 downsample → 256-bin weighted histogram
-	 *
-	 * Single workgroup of 256 threads. Each thread processes 16 texels from
-	 * the downsample grid, applies spatial metering weight, and atomically
-	 * scatters into the histogram storage buffer.
-	 *
-	 * Phase 1: Clear all 256 bins (one per thread)
-	 * Phase 2: Build histogram with metering-weighted atomic scatter
-	 */
-	_buildHistogramCompute() {
+					scan.element( t ).addAssign( scan.element( t.add( uint( s ) ) ) );
+					levels.element( t ).addAssign( levels.element( t.add( uint( s ) ) ) );
 
-		const downsampleTex = this._downsampleTarget.texture;
-		const histogram = this._histogramBuffer;
-		const centerWeight = this.centerWeightU;
+				} );
+				workgroupBarrier();
 
-		const WGSIZE = 256;
-		const TEXELS_PER_THREAD = 16; // 4096 / 256
-		const TEX_SIZE = 64;
+			}
 
-		const computeFn = Fn( () => {
+			If( t.equal( uint( 0 ) ), () => {
 
-			const tid = localId.x;
+				const kept = scan.element( uint( 0 ) );
+				result.element( uint( 0 ) ).assign( vec4( levels.element( uint( 0 ) ).div( max( kept, 1e-6 ) ), total.div( WEIGHT_SCALE ), kept.div( WEIGHT_SCALE ), 1.0 ) );
 
-			// ── Phase 1: Clear histogram ──────────────────
-			atomicStore( histogram.element( tid ), uint( 0 ) );
-			workgroupBarrier();
+			} );
 
-			// ── Phase 2: Build histogram ──────────────────
-			for ( let t = 0; t < TEXELS_PER_THREAD; t ++ ) {
+		} )().compute( [ 1, 1, 1 ], [ BINS, 1, 1 ] );
 
-				const linearIdx = tid.mul( TEXELS_PER_THREAD ).add( t );
-				const px = linearIdx.mod( TEX_SIZE );
-				const py = linearIdx.div( TEX_SIZE );
+	}
 
-				const data = textureLoad( downsampleTex, ivec2( int( px ), int( py ) ) );
-				const logLumSum = data.x;
-				const validCount = data.y;
+	// ── Pipeline ─────────────────────────────────────────────
 
-				If( validCount.greaterThan( 0.0 ), () => {
+	setupEventListeners() {
 
-					// Per-cell average log-luminance (natural log, matches downsample output)
-					const avgLogLum = logLumSum.div( validCount );
+		this.on( 'pipeline:reset', () => this._restarts ++ );
+		this.on( 'pipeline:lightingChanged', () => this.resetHistory() );
 
-					// Map to histogram bin [0, NUM_BINS-1]
-					const normalized = avgLogLum.sub( float( MIN_LOG_LUM ) ).div( float( LOG_LUM_RANGE ) );
-					const bin = uint( normalized.mul( float( NUM_BINS ) ).floor().clamp( 0.0, float( NUM_BINS - 1 ) ) );
+	}
 
-					// ── Centre-weighted metering ──────────
-					const uvx = float( px ).add( 0.5 ).div( float( TEX_SIZE ) );
-					const uvy = float( py ).add( 0.5 ).div( float( TEX_SIZE ) );
-					const dx = uvx.sub( 0.5 );
-					const dy = uvy.sub( 0.5 );
-					const dist2 = dx.mul( dx ).add( dy.mul( dy ) );
+	render( context ) {
 
-					// Gaussian falloff: 1.0 at centre, ~0.02 at corners
-					const weight = dist2.mul( centerWeight ).negate().exp();
+		if ( ! this.enabled ) return;
 
-					const weightUint = uint( weight.mul( float( WEIGHT_SCALE ) ) );
-					atomicAdd( histogram.element( bin ), weightUint );
+		const samples = context.getState( 'pathtracer:samples' ) ?? 0;
+		// Two samples since the last restart: no camera move or playback is restarting it every frame.
+		this._accumulating = samples >= 2;
 
-				} );
+		if ( ! this._pending ) {
 
-			}
+			const last = this._meteredAt;
+			const due = this._stale || this._targetEV === null || last.restarts !== this._restarts || samples - last.samples >= meterInterval( samples );
+			const held = samples < this.holdSamples && this._targetEV !== null && ! this._stale;
+			if ( due && ! held ) this._meter( context, samples );
 
-		} );
+		}
 
-		this._histogramComputeNode = computeFn().compute( [ 1, 1, 1 ], [ WGSIZE, 1, 1 ] );
+		context.setState( 'autoexposure:value', this.renderer.toneMappingExposure );
+		context.setState( 'autoexposure:avgLuminance', this.luminance );
 
 	}
 
 	/**
-	 * Histogram Analysis (compute): extract percentile-clipped geometric mean
-	 *
-	 * Single thread. Reads the 256-bin histogram, computes the CDF, clips
-	 * the bottom and top percentiles, and computes the weighted geometric
-	 * mean of luminance within the accepted range.
-	 *
-	 * Output: StorageTexture(1×1) = vec4(geometricMean, totalCount, avgLogLum, 1)
+	 * Meters the current image once, after any metering in flight, and resolves to the metered
+	 * luminance (log2), or null when nothing could be metered. Does not move the exposure.
 	 */
-	_buildHistogramAnalyzeCompute() {
+	async meter( context = this.context ) {
 
-		const histogram = this._histogramBuffer;
-		const outputTex = this._reductionStorageTex;
-		const lowPercentile = this.lowPercentileU;
-		const highPercentile = this.highPercentileU;
+		while ( this._pending ) await this._pending;
+		const done = this._meter( context, context?.getState( 'pathtracer:samples' ) ?? 0 );
+		return done ? ( await done ) : null;
 
-		const computeFn = Fn( () => {
+	}
 
-			// ── Pass 1: compute total weight ──────────────
-			const totalWeight = float( 0.0 ).toVar();
+	_meter( context, samples ) {
 
-			Loop( NUM_BINS, ( { i } ) => {
+		const input = context?.getTexture( 'pathtracer:color' );
+		const width = input?.image?.width | 0, height = input?.image?.height | 0;
+		if ( ! input || width < 1 || height < 1 || this._disposed ) return null;
 
-				totalWeight.addAssign( float( atomicLoad( histogram.element( i ) ) ) );
+		this._meteredAt.restarts = this._restarts;
+		this._meteredAt.samples = samples;
+		this._stale = false;
 
-			} );
+		const matrix = getWorkingMatrix();
+		if ( matrix !== this._workingMatrix ) {
 
-			// Percentile thresholds (in quantised weight units)
-			const lowThreshold = totalWeight.mul( lowPercentile );
-			const highThreshold = totalWeight.mul( highPercentile );
+			this._workingMatrix = matrix;
+			workingLuminance( matrix, this._lumWeightsU.value );
 
-			// ── Pass 2: percentile-clipped weighted mean ──
-			const cumWeight = float( 0.0 ).toVar();
-			const logLumAccum = float( 0.0 ).toVar();
-			const validWeight = float( 0.0 ).toVar();
-			const prevCum = float( 0.0 ).toVar();
+		}
 
-			Loop( NUM_BINS, ( { i } ) => {
+		const gridX = Math.min( GRID, Math.max( 1, Math.floor( width / MIN_TILE ) ) );
+		const gridY = Math.min( GRID, Math.max( 1, Math.floor( height / MIN_TILE ) ) );
+		const tileReads = ( width / gridX ) * ( height / gridY );
+		this._gridXU.value = gridX;
+		this._gridYU.value = gridY;
+		this._kernels[ 0 ].dispatchSize = [ gridX, gridY, 1 ];
+		this._strideU.value = Math.max( 1, Math.round( Math.sqrt( tileReads / MAX_TILE_READS ) ) );
+		this._widthU.value = width;
+		this._heightU.value = height;
+		this._updateMeteringPattern( width / height );
+		this._inputNode.value = input;
 
-				const binWeight = float( atomicLoad( histogram.element( i ) ) );
-				prevCum.assign( cumWeight );
-				cumWeight.addAssign( binWeight );
+		this.renderer.compute( this._kernels );
 
-				// Include bin if it overlaps the [lowThreshold, highThreshold] range
-				If( prevCum.lessThan( highThreshold ).and( cumWeight.greaterThan( lowThreshold ) ), () => {
+		const generation = this._generation;
+		const image = { restarts: this._restarts, moves: this._viewMoves };
+		const pending = this.renderer.getArrayBufferAsync( this._result.value, this._readback ).then( ( readback ) => {
 
-					// Bin centre in log-luminance space
-					const binCenter = float( MIN_LOG_LUM ).add(
-						float( i ).add( 0.5 ).mul( float( BIN_WIDTH ) )
-					);
-					logLumAccum.addAssign( binCenter.mul( binWeight ) );
-					validWeight.addAssign( binWeight );
+			const data = readback?.buffer ? new Float32Array( readback.buffer.slice( 0, 16 ) ) : null;
+			this._readback.release();
+			return data && generation === this._generation && ! this._disposed ? this._applyMetering( data, image ) : null;
 
-				} );
+		}, () => {
 
-			} );
+			if ( ! this._disposed && this._readback._mapped ) this._readback.release();
+			return null;
 
-			const safeWeight = max( validWeight, float( 1.0 ) );
-			const avgLogLum = logLumAccum.div( safeWeight );
-			const geometricMean = avgLogLum.exp();
+		} ).finally( () => {
 
-			textureStore(
-				outputTex,
-				uvec2( uint( 0 ), uint( 0 ) ),
-				vec4( geometricMean, totalWeight, avgLogLum, 1.0 )
-			).toWriteOnly();
+			if ( this._pending === pending ) this._pending = null;
 
 		} );
 
-		this._histogramAnalyzeNode = computeFn().compute( 1, [ 1, 1, 1 ] );
+		this._pending = pending;
+		return pending;
 
 	}
 
-	/**
-	 * Adaptation (compute): temporal smoothing
-	 *
-	 * Single-thread compute dispatch [1, 1, 1], workgroup [1, 1, 1].
-	 * Reads geometric mean from analysis RenderTarget, applies asymmetric
-	 * temporal smoothing using the previous-exposure uniform, and writes
-	 * vec4(exposure, luminance, targetExposure, 1) into a 1-element storage
-	 * buffer which the CPU reads via getArrayBufferAsync + ReadbackBuffer.
-	 */
-	_buildAdaptationCompute() {
+	_updateMeteringPattern( aspect ) {
 
-		const reductionTex = this._reductionReadTexNode;
-		const resultBuf = this._adaptationResult;
-		const keyValue = this.keyValueU;
-		const minExp = this.minExposureU;
-		const maxExp = this.maxExposureU;
-		const speedBright = this.adaptSpeedBrightU;
-		const speedDark = this.adaptSpeedDarkU;
-		const dt = this.deltaTimeU;
-		const isFirst = this.isFirstFrameU;
-		const prevExposure = this.previousExposureU;
+		const falloff = this._falloffU.value;
+		const point = this._pointU.value;
 
-		const computeFn = Fn( () => {
+		if ( this.metering === 'average' ) {
 
-			// Read geometric mean from histogram analysis result (1×1 RenderTarget)
-			const geoMean = textureLoad( reductionTex, ivec2( int( 0 ), int( 0 ) ) ).x;
+			falloff.set( 0, 0 );
 
-			const result = adaptExposure(
-				geoMean, prevExposure, keyValue,
-				minExp, maxExp, speedBright, speedDark,
-				dt, isFirst
-			);
+		} else if ( this.metering === 'spot' ) {
 
-			resultBuf.element( uint( 0 ) ).assign( result );
+			falloff.set( SPOT_FALLOFF * aspect * aspect, SPOT_FALLOFF );
+			point.copy( this.meteringPoint );
+			return;
 
-		} );
+		} else {
 
-		this._adaptationComputeNode = computeFn().compute( 1, [ 1, 1, 1 ] );
+			falloff.set( this.centerWeight, this.centerWeight );
 
-	}
+		}
 
-	// ──────────────────────────────────────────────────
-	// Event listeners
-	// ──────────────────────────────────────────────────
+		point.set( 0.5, 0.5 );
 
-	setupEventListeners() {
+	}
 
-		this.on( 'pipeline:reset', () => this.reset() );
-		this.on( 'pipeline:lightingChanged', () => this.resetHistory() );
+	// `image` is the restart and view count it was metered at; none re-reads the same image.
+	_applyMetering( data, image = this._landed ) {
 
-	}
+		const [ level, total, kept ] = data;
+		if ( ! this.enabled || ! ( total > 0 && kept > 0 ) || ! Number.isFinite( level ) ) return null;
 
-	// ──────────────────────────────────────────────────
-	// Render
-	// ──────────────────────────────────────────────────
+		const before = this._viewEV;
+		this._meteredLog2 = level;
+		// Unclamped: the range caps where the exposure lands, not what the curve is told the scene needs.
+		this._viewEV = Math.log2( this.keyValue ) - level;
 
-	render( context ) {
+		if ( this._roomEV === null ) {
 
-		if ( ! this.enabled ) return;
+			this._roomEV = this._viewEV;
 
-		// Resolve input texture (fallback chain)
-		const inputTex = context.getTexture( 'edgeFiltering:output' )
-			|| context.getTexture( 'asvgf:output' )
-			|| context.getTexture( 'pathtracer:color' );
+		} else if ( image?.moves !== this._landed?.moves ) {
 
-		if ( ! inputTex ) return;
+			this._movingUntil = this._clock + MOTION_HOLD;
 
-		// Delta time
-		const now = performance.now();
-		const dt = Math.min( ( now - this.lastTime ) / 1000, 0.1 );
-		this.lastTime = now;
-		this.deltaTimeU.value = this.isFirstFrame ? 1.0 : dt;
-		this.isFirstFrameU.value = this.isFirstFrame ? 1.0 : 0.0;
-		this.previousExposureU.value = this.currentExposure;
+		} else {
 
-		// Update input resolution uniforms for downsample compute
-		this.inputResW.value = inputTex.image?.width || 1;
-		this.inputResH.value = inputTex.image?.height || 1;
+			// Under a still camera the room moves with every reading: the scene changed, or the image reads better as it
+			// fills in. Held at a render's first reading, a final render's 1-bounce frame 0 (0.75 stops dark) became the
+			// room, and the finished image was exposed +2.1 stops where it asked for +1.95.
+			this._roomEV += this._viewEV - before;
 
-		// ── Pass 1: Downsample full res → 64×64 (compute) ──
+		}
 
-		this._inputTexNode.value = inputTex;
-		this.renderer.compute( this._downsampleComputeNode );
-		this.renderer.copyTextureToTexture( this._downsampleStorageTex, this._downsampleTarget.texture );
+		this._landed = image;
 
-		// ── Pass 2: Histogram build (compute) ───────────────
+		const target = this._aim();
+		const moved = this._targetEV === null || Math.abs( target - this._targetEV ) > SETTLED_STOPS;
+		this._targetEV = target;
+		if ( moved || this.settling ) this.onChange?.();
+		return level;
 
-		this.renderer.compute( this._histogramComputeNode );
+	}
 
-		// ── Pass 3: Histogram analysis → 1×1 result ─────────
+	// ── Adaptation ───────────────────────────────────────────
 
-		this.renderer.compute( this._histogramAnalyzeNode );
-		this.renderer.copyTextureToTexture( this._reductionStorageTex, this._reductionReadTarget.texture );
+	/**
+	 * Steps the exposure by the wall-clock time since the last call. Returns whether it changed.
+	 * @param {number} [now=performance.now()]
+	 */
+	update( now = performance.now() ) {
 
-		// ── Pass 4: Temporal adaptation (compute) ───────────
+		const dt = this._lastUpdate === null ? 0 : Math.min( ( now - this._lastUpdate ) / 1000, MAX_STEP_SECONDS );
+		const changed = this.advance( dt, this._accumulating );
+		// Settled and still, the loop may sleep: the time until the next metering is not adaptation time.
+		this._lastUpdate = this.settling || this._clock <= this._movingUntil ? now : null;
+		return changed;
 
-		this._reductionReadTexNode.value = this._reductionReadTarget.texture;
-		this.renderer.compute( this._adaptationComputeNode );
+	}
 
-		// ── Async readback via pooled ReadbackBuffer ─────
-		// getArrayBufferAsync reuses the ReadbackBuffer's internal staging
-		// GPUBuffer across frames. ReadbackBuffer.release() must be called
-		// before it can be reused — the _pendingReadback flag gates reentry.
+	/**
+	 * Steps the exposure by `seconds` towards the last metering; Infinity lands on it. Returns whether it changed.
+	 * @param {number} seconds
+	 * @param {boolean} [still=false] - the image is accumulating: land in ~0.3 s instead of easing
+	 */
+	advance( seconds, still = false ) {
 
-		if ( ! this._pendingReadback ) {
+		if ( ! this.enabled || this._targetEV === null ) return false;
 
-			this._pendingReadback = true;
-			const generation = this._readbackGeneration;
+		// The room level learns only while the view changes: staring at one view does not make it the room.
+		if ( seconds > 0 && seconds !== Infinity ) {
 
-			this.renderer.getArrayBufferAsync(
-				this._adaptationResult.value, this._readbackBuffer
-			).then( ( readback ) => {
+			this._clock += seconds;
+			if ( this._clock <= this._movingUntil ) {
 
-				// Copy the 4 floats out of the mapped buffer before release(),
-				// because release() nulls readback.buffer and unmaps the GPU buffer.
-				const data = readback && readback.buffer
-					? new Float32Array( readback.buffer.slice( 0 ) )
-					: null;
-				this._readbackBuffer.release();
-				this._pendingReadback = false;
+				this._roomEV += ( this._viewEV - this._roomEV ) * ( 1 - Math.exp( - Math.min( seconds, MAX_STEP_SECONDS ) / ROOM_SECONDS ) );
+				this._targetEV = this._aim();
 
-				// Discard stale readback from before a reset
-				if ( data && generation === this._readbackGeneration ) {
+			}
 
-					this._applyReadback( data );
+		}
 
-				}
+		const before = this._exposureEV;
+		if ( this._snap || this.instant ) {
 
-			} ).catch( () => {
+			this._exposureEV = this._targetEV;
+			this._snap = false;
 
-				try {
+		} else {
 
-					this._readbackBuffer.release();
+			this._exposureEV = still
+				? before + ( this._targetEV - before ) * ( 1 - Math.exp( - seconds / LAND_SECONDS ) )
+				: adaptExposureEV( before, this._targetEV, seconds, this.adaptSpeedBright, this.adaptSpeedDark );
+			if ( Math.abs( this._targetEV - this._exposureEV ) <= SETTLED_STOPS ) this._exposureEV = this._targetEV;
 
-				} catch { /* buffer may not be mapped on error */ }
+		}
 
-				this._pendingReadback = false;
+		if ( this._exposureEV === before ) return false;
+		this._apply();
+		return true;
 
-			} );
+	}
 
-		}
+	_inRange( ev ) {
 
-		// ── Publish state ────────────────────────────────
+		return Math.min( Math.max( ev, Math.log2( this.minExposure ) ), Math.log2( this.maxExposure ) );
 
-		context.setState( 'autoexposure:value', this.currentExposure );
-		context.setState( 'autoexposure:avgLuminance', this.currentLuminance );
+	}
 
-		this.emit( 'autoexposure:updated', {
-			exposure: this.currentExposure,
-			luminance: this.currentLuminance,
-			targetExposure: this.targetExposure
-		} );
+	_aim() {
 
-		this.isFirstFrame = false;
+		return this._inRange( blendExposureEV( this._roomEV, this._viewEV, this.strength ) );
 
 	}
 
-	/**
-	 * Process async readback data from 1×1 adaptation target.
-	 */
-	_applyReadback( data ) {
+	/** The camera moved: readings until it stops are of other views, not of a changed scene. */
+	noteViewChanged() {
 
-		if ( ! this.enabled || ! data || data.length < 3 ) return;
+		this._viewMoves ++;
 
-		let exposure = data[ 0 ];
-		let luminance = data[ 1 ];
-		let targetExp = data[ 2 ];
+	}
+
+	/** Whether the exposure is still on its way to the last metering. */
+	get settling() {
 
-		// Validate
-		if ( ! isFinite( exposure ) || exposure <= 0 ) exposure = 1.0;
-		if ( ! isFinite( luminance ) || luminance <= 0 ) luminance = 0.18;
-		if ( ! isFinite( targetExp ) || targetExp <= 0 ) targetExp = exposure;
+		return this.enabled && this._targetEV !== null && ( this._snap || Math.abs( this._targetEV - this._exposureEV ) > 0 );
+
+	}
 
-		this.currentExposure = exposure;
-		this.currentLuminance = luminance;
-		this.targetExposure = targetExp;
+	/** Whether the image on screen should be metered again though no new samples arrive. */
+	get wantsMetering() {
 
-		// Apply to renderer
-		this.renderer.toneMappingExposure = exposure;
+		return this.enabled && ! this._pending && ( this._stale || this._targetEV === null );
 
 	}
 
-	// ──────────────────────────────────────────────────
-	// Lifecycle
-	// ──────────────────────────────────────────────────
+	_apply() {
 
-	/**
-	 * Soft reset: preserve exposure state, let temporal smoothing adapt.
-	 * Called on pipeline:reset (camera moves, parameter changes).
-	 */
-	reset() {
+		this.renderer.toneMappingExposure = this.enabled ? 2 ** this._exposureEV * this._compensation : this._compensation;
+		if ( ! this.enabled || ( this._emittedEV !== null && Math.abs( this._exposureEV - this._emittedEV ) < 0.005 ) ) return;
 
-		this.lastTime = performance.now();
-		// Bump generation so any in-flight readback is discarded
-		this._readbackGeneration ++;
-		this._pendingReadback = false;
+		this._emittedEV = this._exposureEV;
+		this.emit( 'autoexposure:updated', {
+			exposure: this.renderer.toneMappingExposure,
+			autoExposure: this.getExposure(),
+			targetExposure: this._targetEV === null ? null : 2 ** this._targetEV,
+			luminance: this.luminance,
+		} );
 
 	}
 
+	// ── State ────────────────────────────────────────────────
+
 	/**
-	 * Hard reset: wipe exposure history for a clean start.
-	 * Called on scene/environment changes where previous exposure is meaningless.
+	 * @param {boolean} enabled
+	 * @param {number} [compensation] - the manual exposure, multiplied in while on and applied alone while off
 	 */
-	resetHistory() {
+	setEnabled( enabled, compensation = this._compensation ) {
+
+		this._compensation = compensation;
+		if ( enabled === this.enabled ) {
+
+			this._apply();
+			return;
+
+		}
+
+		this.enabled = enabled;
+		this._emittedEV = null;
+		if ( enabled ) {
 
-		this.isFirstFrame = true;
-		this.currentExposure = 1.0;
-		this.currentLuminance = 0.18;
-		this.targetExposure = 1.0;
-		this.lastTime = performance.now();
-		this._readbackGeneration ++;
-		this._pendingReadback = false;
+			// From the manual exposure, not one left from when it was last on, perhaps on another scene.
+			this.resetHistory();
+			this._exposureEV = 0;
+
+		}
+
+		this._apply();
+		this.onChange?.();
 
 	}
 
-	setSize( /* width, height */ ) {
+	/** The manual exposure: a bias in stops on top of the metered exposure while auto exposure is on. */
+	setCompensation( value ) {
 
-		// Downsample and histogram targets are fixed-size (64×64 → 256 bins → 1×1)
-		// No resizing needed — the downsample compute shader reads input
-		// resolution from uniforms and computes block sizes dynamically.
+		this._compensation = value;
+		this._apply();
 
 	}
 
-	setExposure( value ) {
+	/** Forget the exposure history: the next metering is applied at once. */
+	resetHistory() {
 
-		this.currentExposure = value;
-		this.previousExposureU.value = value;
-		this.renderer.toneMappingExposure = value;
+		this._generation ++;
+		this._targetEV = null;
+		this._viewEV = null;
+		this._roomEV = null;
+		this._landed = null;
+		this._meteredLog2 = null;
+		this._snap = true;
 
 	}
 
+	/** The metered exposure, without compensation. */
 	getExposure() {
 
-		return this.currentExposure;
+		return 2 ** this._exposureEV;
+
+	}
+
+	/** Geometric mean luminance of the last metering, or null. */
+	get luminance() {
+
+		return this._meteredLog2 === null ? null : 2 ** this._meteredLog2;
 
 	}
 
 	getLuminance() {
 
-		return this.currentLuminance;
+		return this.luminance;
 
 	}
 
 	updateParameters( params ) {
 
-		if ( params.keyValue !== undefined ) this.keyValueU.value = params.keyValue;
-		if ( params.minExposure !== undefined ) this.minExposureU.value = params.minExposure;
-		if ( params.maxExposure !== undefined ) this.maxExposureU.value = params.maxExposure;
-		if ( params.adaptSpeedBright !== undefined ) this.adaptSpeedBrightU.value = params.adaptSpeedBright;
-		if ( params.adaptSpeedDark !== undefined ) this.adaptSpeedDarkU.value = params.adaptSpeedDark;
-		if ( params.lowPercentile !== undefined ) this.lowPercentileU.value = params.lowPercentile;
-		if ( params.highPercentile !== undefined ) this.highPercentileU.value = params.highPercentile;
-		if ( params.centerWeight !== undefined ) this.centerWeightU.value = params.centerWeight;
+		const metering = params.metering;
+		if ( metering !== undefined && METERING_MODES.includes( metering ) ) this.metering = metering;
+		if ( params.meteringPoint ) this.meteringPoint.set( params.meteringPoint.x, params.meteringPoint.y );
+		for ( const key of [ 'keyValue', 'minExposure', 'maxExposure', 'adaptSpeedBright', 'adaptSpeedDark', 'centerWeight', 'strength' ] ) {
+
+			if ( params[ key ] !== undefined ) this[ key ] = params[ key ];
+
+		}
+
+		if ( params.lowPercentile !== undefined ) this._lowU.value = params.lowPercentile;
+		if ( params.highPercentile !== undefined ) this._highU.value = params.highPercentile;
+
+		this._stale = true;
+		if ( this._meteredLog2 !== null ) this._applyMetering( [ this._meteredLog2, 1, 1 ] );
+		this.onChange?.();
 
 	}
 
+	reset() {}
+
+	setSize() {}
+
 	dispose() {
 
-		this._downsampleComputeNode?.dispose();
-		this._histogramComputeNode?.dispose();
-		this._histogramAnalyzeNode?.dispose();
-		this._adaptationComputeNode?.dispose();
-		this._downsampleTarget?.dispose();
-		this._downsampleStorageTex?.dispose();
-		this._reductionStorageTex?.dispose();
-		this._reductionReadTarget?.dispose();
-		this._readbackBuffer?.dispose();
-		this._inputTexNode?.dispose();
-		this._reductionReadTexNode?.dispose();
+		this._disposed = true;
+		this.onChange = null;
+		for ( const kernel of this._kernels ) kernel.dispose();
+		this._readback.dispose();
+		this._inputNode.dispose();
 
 	}