feat(fog): replace linear fog with EXP2 LUT

Precomputed 256-entry Float32Array LUT using 1 - exp(-(density*t)^2)
where t is normalized depth across [near, far]. Default density 2.5
gives ~99.8% fog at far regardless of scene scale — linear fog always
reached 100% at far. SceneTraversal now does a branchless LUT index
lookup per vertex instead of the linear (depth - near) * invRange.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude <noreply@anthropic.com>

Author: xsyetopz

src/pipeline/SceneTraversal.ts

@@ -65,6 +65,7 @@ interface SceneLike {
 		near: number;
 		far: number;
 		color: { r: number; g: number; b: number };
+		lut: Float32Array;
 	};
 	autoUpdate?: boolean;
 }
@@ -75,6 +76,8 @@ const VERT_STRIDE = 4;
 export class SceneTraversal {
 	#fogNear = 0;
 	#fogFar = 0;
+	#fogLutScale = 0;
+	#fogLut: Float32Array | null = null;
 	#hasFog = false;
 	#autoUpdate = false;
 
@@ -100,6 +103,9 @@ export class SceneTraversal {
 		this.#hasFog = !!fog;
 		this.#fogNear = fog?.near ?? 0;
 		this.#fogFar = fog?.far ?? 0;
+		this.#fogLut = fog?.lut ?? null;
+		this.#fogLutScale =
+			fog && fog.far - fog.near > 0 ? 255 / (fog.far - fog.near) : 0;
 
 		_vp.copy(camera.projectionMatrix).mul(camera.matrixWorldInverse);
 		_frustum.setFromProjectionMatrix(_vp);
@@ -470,8 +476,8 @@ export class SceneTraversal {
 
 		const hasFog = this.#hasFog;
 		const fogNear = this.#fogNear;
-		const fogInvRange =
-			this.#fogFar - fogNear > 0 ? 1 / (this.#fogFar - fogNear) : 0;
+		const fogLutScale = this.#fogLutScale;
+		const fogLut = this.#fogLut;
 		const wnLen = worldNormals.length;
 		const uvLen = uvs.length;
 		const wpLen = worldPositions.length;
@@ -511,13 +517,13 @@ export class SceneTraversal {
 			let ff0 = 0;
 			let ff1 = 0;
 			let ff2 = 0;
-			if (hasFog) {
-				const raw0 = (w0 - fogNear) * fogInvRange;
-				const raw1 = (w1 - fogNear) * fogInvRange;
-				const raw2 = (w2 - fogNear) * fogInvRange;
-				ff0 = raw0 < 0 ? 0 : raw0 > 1 ? 1 : raw0;
-				ff1 = raw1 < 0 ? 0 : raw1 > 1 ? 1 : raw1;
-				ff2 = raw2 < 0 ? 0 : raw2 > 1 ? 1 : raw2;
+			if (hasFog && fogLut) {
+				const i0f = ((w0 - fogNear) * fogLutScale) | 0;
+				const i1f = ((w1 - fogNear) * fogLutScale) | 0;
+				const i2f = ((w2 - fogNear) * fogLutScale) | 0;
+				ff0 = i0f <= 0 ? 0 : i0f >= 255 ? fogLut[255] : fogLut[i0f];
+				ff1 = i1f <= 0 ? 0 : i1f >= 255 ? fogLut[255] : fogLut[i1f];
+				ff2 = i2f <= 0 ? 0 : i2f >= 255 ? fogLut[255] : fogLut[i2f];
 			}
 
 			let fnx = 0;

src/scenes/Fog.ts

@@ -1,25 +1,46 @@
 import { Color } from "../math/Color.ts";
 
+const FOG_LUT_SIZE = 256;
+
 interface FogOptions {
 	color?: Color | number | string;
 	near?: number;
 	far?: number;
+	density?: number;
 }
 
 /**
- * Linear fog that blends fragment colors toward a configurable color based on
- * camera-space depth. Objects at `near` are unaffected; objects at `far` are
- * fully fogged.
+ * EXP2 fog. Blends fragments toward `color` with factor `1 - exp(-(density * t)^2)` where
+ * `t` is normalized depth (0 at `near`, 1 at `far`). Default density 2.5 gives ~99.8% fog
+ * at `far` regardless of scene scale. LUT is rebuilt when `density` changes.
  */
 export class Fog {
 	#color: Color;
 	#near: number;
 	#far: number;
+	#density: number;
+	#lut: Float32Array = new Float32Array(FOG_LUT_SIZE);
 
-	constructor({ color = 0x000000, near = 1, far = 100 }: FogOptions = {}) {
+	constructor({
+		color = 0x000000,
+		near = 1,
+		far = 100,
+		density = 2.5,
+	}: FogOptions = {}) {
 		this.#color = color instanceof Color ? color : new Color(color);
 		this.#near = near;
 		this.#far = far;
+		this.#density = density;
+		this.#buildLut();
+	}
+
+	#buildLut(): void {
+		const density = this.#density;
+		for (let i = 0; i < FOG_LUT_SIZE; i++) {
+			const t = i / (FOG_LUT_SIZE - 1);
+			const dd = density * t;
+			this.#lut[i] = 1 - Math.exp(-(dd * dd));
+		}
 	}
 
 	get color(): Color {
@@ -42,11 +63,25 @@ export class Fog {
 		this.#far = value;
 	}
 
+	get density(): number {
+		return this.#density;
+	}
+
+	set density(value: number) {
+		this.#density = value;
+		this.#buildLut();
+	}
+
+	get lut(): Float32Array {
+		return this.#lut;
+	}
+
 	clone(): Fog {
 		return new Fog({
 			color: this.#color.clone(),
 			near: this.#near,
 			far: this.#far,
+			density: this.#density,
 		});
 	}
 }

tests/scenes/Fog.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { Fog } from "@/scenes/Fog.js";
+
+describe("Fog", () => {
+	it("lut[0] is 0 (no fog at near)", () => {
+		const fog = new Fog();
+		expect(fog.lut[0]).toBeCloseTo(0, 6);
+	});
+
+	it("lut[255] approaches 1 at default density", () => {
+		const fog = new Fog(); // density=2.5 → 1-exp(-6.25) ≈ 0.998
+		expect(fog.lut[255]).toBeGreaterThan(0.99);
+	});
+
+	it("lut is monotonically non-decreasing", () => {
+		const fog = new Fog();
+		for (let i = 1; i < 256; i++) {
+			expect(fog.lut[i]).toBeGreaterThanOrEqual(fog.lut[i - 1]);
+		}
+	});
+
+	it("rebuilds lut when density changes", () => {
+		const fog = new Fog({ density: 0.5 });
+		const low = fog.lut[128];
+		fog.density = 2.5;
+		expect(fog.lut[128]).toBeGreaterThan(low);
+	});
+
+	it("near/far do not affect lut shape", () => {
+		const a = new Fog({ near: 0, far: 100, density: 2.5 });
+		const b = new Fog({ near: 50, far: 500, density: 2.5 });
+		for (let i = 0; i < 256; i++) {
+			expect(a.lut[i]).toBeCloseTo(b.lut[i], 6);
+		}
+	});
+
+	it("clone preserves density", () => {
+		const fog = new Fog({ near: 10, far: 200, density: 1.5 });
+		const c = fog.clone();
+		expect(c.density).toBe(1.5);
+		expect(c.near).toBe(10);
+		expect(c.far).toBe(200);
+	});
+
+	it("clone lut matches original", () => {
+		const fog = new Fog({ density: 1.8 });
+		const c = fog.clone();
+		for (let i = 0; i < 256; i++) {
+			expect(c.lut[i]).toBeCloseTo(fog.lut[i], 6);
+		}
+	});
+});