Skip to content

Code-first video & image, rendered natively on WebGPU.

16.9 KB
Raw Blame
/**
 * WebGPU 3D Lighting & Material Shading engine.
 * Supports Ambient, Directional, Point, and Spot light sources,
 * normal matrix computation for non-uniform surface scaling,
 * and binary uniform buffer packing for WGSL shaders.
 */

import {
	type Environment3DOptions,
	resolveEnvironment,
	type ShadowUniformInfo,
} from "./environment3d.js";
import { type Mat4, Matrix4Math } from "./matrix4.js";
import { type Vec3, Vector3Math } from "./vector3.js";

export type LightKind = "ambient" | "directional" | "point" | "spot" | "rect";

export interface Light3DOptions {
	id?: string;
	lightType?: LightKind;
	type?: LightKind;
	color?:
		| string
		| [number, number, number]
		| [number, number, number, number]
		| { r: number; g: number; b: number; a?: number }
		| unknown;
	intensity?: number;
	x?: number;
	y?: number;
	z?: number;
	position?: [number, number, number];
	targetX?: number;
	targetY?: number;
	targetZ?: number;
	target?: [number, number, number];
	direction?: [number, number, number];
	radius?: number; // Distance cutoff / range
	decay?: number; // Attenuation exponent (default 2.0)
	angle?: number; // Outer cone half-angle in degrees (default 45)
	penumbra?: number; // Softness fraction [0, 1] (default 0.2)
	/** Area light width in world px (default 240, rect lights only). */
	width?: number;
	/** Area light height in world px (default 140, rect lights only). */
	height?: number;
	/** Emit from both faces of a rect light (default false). */
	twoSided?: boolean;
	/** In-plane roll angle in degrees around the light's forward axis (default 0). */
	rotation?: number;
	/** Directional, spot, point, or rect: render a shadow map. */
	castShadow?: boolean;
	/** Shadow edge blur in shadow-map texels (default 2). */
	shadowSoftness?: number;
	/** 0..1, how dark shadows get (default 1). */
	shadowDarkness?: number;
}

export interface GPULightData {
	/** xyz = position, w = type (0=ambient, 1=directional, 2=point, 3=spot, 4=rect) */
	posType: [number, number, number, number];
	/** xyz = normalized direction, w = radius */
	dirRadius: [number, number, number, number];
	/** rgb = linear color, w = intensity */
	colorIntensity: [number, number, number, number];
	/** x = cos(outer), y = cos(inner), z = decay, w = twoSided (rect) */
	spotParams: [number, number, number, number];
	/** xyz = normalized right axis of rect area light, w = halfWidth */
	rectRight: [number, number, number, number];
	/** xyz = normalized up axis of rect area light, w = halfHeight */
	rectUp: [number, number, number, number];
}

/** Slots retained in the legacy uniform prefix; actual direct lights use storage. */
export const MAX_LIGHTS = 8;
/**
 * 16 (ambient) + 16 (params) + 8 * 64 (lights), then the physical-shading
 * block appended after them: 8 vec4 (128) + shadow matrix (64) +
 * floorParams (16) + HDRI irradiance SH (9 vec4, 144) + screen indirect (16).
 */
export const LIGHT_UNIFORM_SIZE_BYTES = 544 + 128 + 64 + 16 + 144 + 16;

/**
 * Which half of a screen-space indirect (SSR / GI) frame a pass draws:
 * `radiance` writes the unfogged scene radiance the traces read; `apply`
 * shades with the traced reflections and bounce light.
 */
export type ScreenIndirectPass = "radiance" | "apply";

/** A prefiltered HDRI as the lights uniform describes it. */
export interface HdriUniforms {
	/** Highest mip of the radiance cubemap (roughness 1). */
	maxMip: number;
	/** 9 L2 irradiance SH coefficients, one vec4 (rgb + pad) each. */
	sh: Float32Array;
}

export interface LightsUniformData {
	ambientColor: [number, number, number, number];
	params: [number, number, number, number];
	lights: GPULightData[];
}

/**
 * Parses CSS / hex / rgb color strings, arrays, or color objects into normalized linear [r, g, b] floats in [0, 1].
 */
export function parseColorToRgb(
	color?:
		| string
		| [number, number, number]
		| [number, number, number, number]
		| { r: number; g: number; b: number; a?: number }
		| unknown,
): [number, number, number] {
	if (!color) return [1, 1, 1];
	if (Array.isArray(color)) {
		const r = color[0] ?? 1;
		const g = color[1] ?? 1;
		const b = color[2] ?? 1;
		return [r > 1 ? r / 255 : r, g > 1 ? g / 255 : g, b > 1 ? b / 255 : b];
	}
	if (typeof color === "object" && color !== null) {
		const r = (color as { r?: number }).r ?? 1;
		const g = (color as { g?: number }).g ?? 1;
		const b = (color as { b?: number }).b ?? 1;
		return [r > 1 ? r / 255 : r, g > 1 ? g / 255 : g, b > 1 ? b / 255 : b];
	}
	if (typeof color !== "string") return [1, 1, 1];
	const str = color.trim().toLowerCase();

	if (str.startsWith("#")) {
		const hex = str.slice(1);
		if (hex.length === 3) {
			const r = Number.parseInt(hex[0] + hex[0], 16) / 255;
			const g = Number.parseInt(hex[1] + hex[1], 16) / 255;
			const b = Number.parseInt(hex[2] + hex[2], 16) / 255;
			return [r, g, b];
		}
		if (hex.length >= 6) {
			const r = Number.parseInt(hex.slice(0, 2), 16) / 255;
			const g = Number.parseInt(hex.slice(2, 4), 16) / 255;
			const b = Number.parseInt(hex.slice(4, 6), 16) / 255;
			return [r, g, b];
		}
	}

	const rgbMatch = str.match(
		/rgba?\s*\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/,
	);
	if (rgbMatch) {
		const r = Number.parseFloat(rgbMatch[1]) / 255;
		const g = Number.parseFloat(rgbMatch[2]) / 255;
		const b = Number.parseFloat(rgbMatch[3]) / 255;
		return [
			Math.max(0, Math.min(1, r)),
			Math.max(0, Math.min(1, g)),
			Math.max(0, Math.min(1, b)),
		];
	}

	const hslMatch = str.match(
		/hsla?\s*\(\s*([\d.]+)\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?/,
	);
	if (hslMatch) {
		const h = Number.parseFloat(hslMatch[1]) / 360;
		const s = Number.parseFloat(hslMatch[2]) / 100;
		const l = Number.parseFloat(hslMatch[3]) / 100;
		return hslToRgb(h, s, l);
	}

	return [1, 1, 1];
}

function hslToRgb(h: number, s: number, l: number): [number, number, number] {
	if (s === 0) return [l, l, l];
	const hue2rgb = (p: number, q: number, t: number) => {
		let tt = t;
		if (tt < 0) tt += 1;
		if (tt > 1) tt -= 1;
		if (tt < 1 / 6) return p + (q - p) * 6 * tt;
		if (tt < 1 / 2) return q;
		if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
		return p;
	};
	const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
	const p = 2 * l - q;
	return [hue2rgb(p, q, h + 1 / 3), hue2rgb(p, q, h), hue2rgb(p, q, h - 1 / 3)];
}

export const DIRECT_LIGHT_FLOATS = 48;

export const Light3D = {
	/**
	 * Computes the 3x3 normal matrix (stored in 4x4 layout) from a 4x4 Model matrix.
	 * Evaluates N = (M^-1)^T to preserve true orthogonal surface normals under non-uniform scaling.
	 */
	computeNormalMatrix(modelMatrix: Mat4): Mat4 {
		const inv = Matrix4Math.invert(modelMatrix);
		if (!inv) {
			return Matrix4Math.identity();
		}
		// Transpose of the inverted matrix
		const normMat: Mat4 = [
			inv[0],
			inv[4],
			inv[8],
			0,
			inv[1],
			inv[5],
			inv[9],
			0,
			inv[2],
			inv[6],
			inv[10],
			0,
			0,
			0,
			0,
			1,
		];
		return normMat;
	},

	/**
	 * Converts high-level light options into uniform data ready for GPU packing.
	 */
	processLight(opt: Light3DOptions): GPULightData {
		const color = parseColorToRgb(opt.color);
		const intensity = opt.intensity ?? 1.0;
		const posX = opt.position ? opt.position[0] : (opt.x ?? 0);
		const posY = opt.position ? opt.position[1] : (opt.y ?? 0);
		const posZ = opt.position ? opt.position[2] : (opt.z ?? 0);

		const kind = opt.lightType ?? opt.type ?? "directional";
		let typeVal = 1.0; // default directional
		if (kind === "ambient") typeVal = 0.0;
		else if (kind === "directional") typeVal = 1.0;
		else if (kind === "point") typeVal = 2.0;
		else if (kind === "spot") typeVal = 3.0;
		else if (kind === "rect") typeVal = 4.0;

		let dir: Vec3 = [0, 0, -1];
		if (opt.direction) {
			dir = Vector3Math.normalize(opt.direction);
		} else if (
			opt.target ||
			opt.targetX !== undefined ||
			opt.targetY !== undefined ||
			opt.targetZ !== undefined
		) {
			const targetX = opt.target ? opt.target[0] : (opt.targetX ?? posX);
			const targetY = opt.target ? opt.target[1] : (opt.targetY ?? posY);
			const targetZ = opt.target ? opt.target[2] : (opt.targetZ ?? posZ);
			const target: Vec3 = [targetX, targetY, targetZ];
			const fromLight = Vector3Math.subtract(target, [posX, posY, posZ]);
			const len = Vector3Math.length(fromLight);
			if (len > 1e-4) {
				dir = Vector3Math.normalize(fromLight);
			}
		}

		const radius = Math.max(1.0, opt.radius ?? 1000);
		const decay = opt.decay ?? 2.0;
		const angleDeg = Math.max(0.1, Math.min(180, opt.angle ?? 45));
		const penumbraFrac = Math.max(0, Math.min(1, opt.penumbra ?? 0.2));

		const outerRad = (angleDeg * Math.PI) / 180;
		const innerRad = outerRad * (1 - penumbraFrac);
		const cosOuter = Math.cos(outerRad);
		const cosInner = Math.cos(innerRad);

		const worldUp: Vec3 = Math.abs(dir[1]) > 0.999 ? [0, 0, 1] : [0, 1, 0];
		const baseRight = Vector3Math.normalize(Vector3Math.cross(worldUp, dir));
		const baseUp = Vector3Math.normalize(Vector3Math.cross(dir, baseRight));
		const rollRad = ((opt.rotation ?? 0) * Math.PI) / 180;
		const cosR = Math.cos(rollRad);
		const sinR = Math.sin(rollRad);
		const right: Vec3 = [
			baseRight[0] * cosR + baseUp[0] * sinR,
			baseRight[1] * cosR + baseUp[1] * sinR,
			baseRight[2] * cosR + baseUp[2] * sinR,
		];
		const up: Vec3 = [
			-baseRight[0] * sinR + baseUp[0] * cosR,
			-baseRight[1] * sinR + baseUp[1] * cosR,
			-baseRight[2] * sinR + baseUp[2] * cosR,
		];
		const halfWidth = Math.max(0.5, (opt.width ?? 240) * 0.5);
		const halfHeight = Math.max(0.5, (opt.height ?? 140) * 0.5);
		const twoSidedFlag = opt.twoSided ? 1.0 : 0.0;

		return {
			posType: [posX, posY, posZ, typeVal],
			dirRadius: [dir[0], dir[1], dir[2], radius],
			colorIntensity: [color[0], color[1], color[2], intensity],
			spotParams: [cosOuter, cosInner, decay, twoSidedFlag],
			rectRight: [right[0], right[1], right[2], halfWidth],
			rectUp: [up[0], up[1], up[2], halfHeight],
		};
	},

	/**
	 * Packs active scene lights into a Float32Array matching WGSL LightsUniforms layout.
	 */
	packLightsUniforms(
		lights: Light3DOptions[],
		environment?: Environment3DOptions | null,
		shadow?: ShadowUniformInfo | null,
		isReflectionPass = false,
		hdri?: HdriUniforms,
		screenIndirect?: ScreenIndirectPass,
	): Float32Array {
		const buffer = new Float32Array(LIGHT_UNIFORM_SIZE_BYTES / 4);
		Light3D.packPhysicalBlock(
			buffer,
			lights ?? [],
			environment,
			shadow,
			isReflectionPass,
			hdri,
			screenIndirect,
		);

		if ((!lights || lights.length === 0) && !environment) {
			// No lights: params.y = 0.0 indicates unlit mode
			buffer[4] = 0.0; // lightCount = 0
			buffer[5] = 0.0; // hasLights = 0.0 (unlit)
			return buffer;
		}

		let ambientR = 0;
		let ambientG = 0;
		let ambientB = 0;

		const directLights: GPULightData[] = [];

		for (const l of lights) {
			const kind = l.lightType ?? l.type;
			if (kind === "ambient") {
				const col = parseColorToRgb(l.color);
				const int = l.intensity ?? 1.0;
				ambientR += col[0] * int;
				ambientG += col[1] * int;
				ambientB += col[2] * int;
			} else {
				directLights.push(Light3D.processLight(l));
			}
		}

		// Offset 0: ambientColor (vec4<f32>)
		buffer[0] = ambientR;
		buffer[1] = ambientG;
		buffer[2] = ambientB;
		buffer[3] = 1.0;

		// Offset 4: params (vec4<f32>)
		buffer[4] = directLights.length;
		buffer[5] = 1.0; // hasLights = 1.0 (lit mode)
		// z = physical shading, w = tone mapping (set by packPhysicalBlock)

		// Offset 8 onwards: array<GPULightData, 8> (each light = 16 floats = 64 bytes)
		let offset = 8;
		for (let i = 0; i < MAX_LIGHTS; i++) {
			if (i < directLights.length) {
				const dl = directLights[i];
				// posType
				buffer[offset + 0] = dl.posType[0];
				buffer[offset + 1] = dl.posType[1];
				buffer[offset + 2] = dl.posType[2];
				buffer[offset + 3] = dl.posType[3];
				// dirRadius
				buffer[offset + 4] = dl.dirRadius[0];
				buffer[offset + 5] = dl.dirRadius[1];
				buffer[offset + 6] = dl.dirRadius[2];
				buffer[offset + 7] = dl.dirRadius[3];
				// colorIntensity
				buffer[offset + 8] = dl.colorIntensity[0];
				buffer[offset + 9] = dl.colorIntensity[1];
				buffer[offset + 10] = dl.colorIntensity[2];
				buffer[offset + 11] = dl.colorIntensity[3];
				// spotParams
				buffer[offset + 12] = dl.spotParams[0];
				buffer[offset + 13] = dl.spotParams[1];
				buffer[offset + 14] = dl.spotParams[2];
				buffer[offset + 15] = dl.spotParams[3];
			} else {
				// Zero-fill unused light slots
				for (let j = 0; j < 16; j++) {
					buffer[offset + j] = 0.0;
				}
			}
			offset += 16;
		}

		return buffer;
	},

	/** Packs every direct light for the variable-length GPU storage binding. */
	packDirectLights(
		lights: Light3DOptions[],
		shadows: ShadowUniformInfo[] = [],
	): Float32Array {
		const direct = lights.filter(
			(light) => (light.lightType ?? light.type) !== "ambient",
		);
		const data = new Float32Array(
			Math.max(1, direct.length) * DIRECT_LIGHT_FLOATS,
		);
		const shadowByLightIndex = new Map(
			shadows.map((shadow, idx) => [shadow.lightIndex, { shadow, idx }]),
		);
		for (const [i, light] of direct.entries()) {
			const packed = Light3D.processLight(light);
			const offset = i * DIRECT_LIGHT_FLOATS;
			data.set(packed.posType, offset);
			data.set(packed.dirRadius, offset + 4);
			data.set(packed.colorIntensity, offset + 8);
			data.set(packed.spotParams, offset + 12);
			const entry = shadowByLightIndex.get(i);
			if (entry) {
				const { shadow, idx } = entry;
				for (let j = 0; j < 16; j++)
					data[offset + 16 + j] = shadow.matrix[j] ?? 0;
				const mode = shadow.mode ?? 1;
				if (mode === 2) {
					data[offset + 16] = shadow.far ?? packed.dirRadius[3];
				}
				const baseLayer = shadow.baseLayer ?? idx;
				data.set(
					[shadow.softness, shadow.mapSize, baseLayer, mode],
					offset + 32,
				);
				data.set(
					[shadow.bias, shadow.normalOffset, shadow.darkness, shadow.near ?? 8],
					offset + 36,
				);
			}
			data.set(packed.rectRight, offset + 40);
			data.set(packed.rectUp, offset + 44);
		}
		return data;
	},

	/** Index (among non-ambient lights) of the light that should cast shadows, or -1. */
	shadowCasterIndex(lights: Light3DOptions[]): number {
		let index = 0;
		for (const l of lights) {
			const kind = l.lightType ?? l.type;
			if (kind === "ambient") continue;
			if (
				l.castShadow &&
				(kind === "directional" ||
					kind === "spot" ||
					kind === "point" ||
					kind === "rect")
			) {
				return index;
			}
			index++;
		}
		return -1;
	},

	/** Fills params.zw and the appended physical-shading block (offset 136 on). */
	packPhysicalBlock(
		buffer: Float32Array,
		lights: Light3DOptions[],
		environment?: Environment3DOptions | null,
		shadow?: ShadowUniformInfo | null,
		isReflectionPass = false,
		hdri?: HdriUniforms,
		screenIndirect?: ScreenIndirectPass,
	): void {
		const base = 8 + MAX_LIGHTS * 16; // first float after the lights array
		let ambR = 0;
		let ambG = 0;
		let ambB = 0;
		for (const l of lights) {
			if ((l.lightType ?? l.type) !== "ambient") continue;
			const [r, g, b] = parseColorToRgb(l.color);
			const k = l.intensity ?? 1.0;
			const lin = (v: number) =>
				v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
			ambR += lin(r) * k;
			ambG += lin(g) * k;
			ambB += lin(b) * k;
		}
		buffer[base + 0] = ambR;
		buffer[base + 1] = ambG;
		buffer[base + 2] = ambB;
		buffer[base + 3] = 1; // exposure multiplier

		let envIntensity = 1.0;
		// x = 0 off, 1 radiance pass, 2 apply; y / z = SSR / GI strength (-1 off); w = SSR max roughness.
		buffer.set([0, -1, -1, 0], base + 88);
		if (environment) {
			const env = resolveEnvironment(environment);
			envIntensity = env.intensity;
			if (screenIndirect && !isReflectionPass && (env.ssr || env.gi)) {
				buffer.set(
					[
						screenIndirect === "radiance" ? 1 : 2,
						env.ssr?.intensity ?? -1,
						env.gi?.intensity ?? -1,
						env.ssr?.maxRoughness ?? 0,
					],
					base + 88,
				);
			}
			// 1 procedural; 2 + max mip with a prefiltered HDRI cubemap bound.
			const envMode = hdri ? 2 + hdri.maxMip : 1;
			if (hdri) buffer.set(hdri.sh.subarray(0, 36), base + 52);
			buffer[6] = 1; // physical shading
			buffer[7] = env.toneMapping;
			buffer[base + 3] = env.exposureMultiplier;
			buffer.set([...env.top, env.rotationRad], base + 4);
			buffer.set([...env.horizon, env.softboxes], base + 8);
			buffer.set([...env.bottom, envMode], base + 12);
			if (env.fog) {
				buffer.set([...env.fog.color, 1], base + 16);
				buffer.set([env.fog.start, env.fog.end, env.fog.opacity, 0], base + 20);
			}
		}

		if (shadow && shadow.lightIndex >= 0) {
			buffer.set(
				[1, shadow.lightIndex, shadow.softness, shadow.mapSize],
				base + 24,
			);
			buffer.set(
				[shadow.bias, shadow.normalOffset, shadow.darkness, 0],
				base + 28,
			);
			for (let i = 0; i < 16; i++)
				buffer[base + 32 + i] = shadow.matrix[i] ?? 0;
		}

		if (environment?.floor) {
			buffer[base + 48] = environment.floor.y;
			buffer[base + 49] = environment.floor.fadeDistance ?? 900;
			buffer[base + 50] = isReflectionPass ? 1.0 : 0.0;
			buffer[base + 51] = envIntensity;
		} else {
			buffer[base + 48] = 0.0;
			buffer[base + 49] = 0.0;
			buffer[base + 50] = 0.0;
			buffer[base + 51] = envIntensity;
		}
	},
};