Skip to content

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

12.8 KB
Raw Blame
/**
 * Scene-wide "world" settings for physically based 3D: a procedural studio
 * environment (image-based light), exposure, tone mapping and fog. A scene
 * with an environment is shaded physically; one without keeps the original
 * Blinn-Phong look.
 */
import { type GeometryOutlineOptions, parseCssColor } from "@framefields/core";

/**
 * "neutral" (default, Khronos PBR Neutral): colors as authored, highlights
 * rolled off: right for products, brands and UI. "agx": filmic, desaturates
 * hot highlights gracefully. "aces": punchy film contrast, shifts hues.
 */
export type ToneMapping = "neutral" | "agx" | "aces" | "none";

export type EnvironmentPreset =
	| "studio"
	| "soft"
	| "warm"
	| "sunset"
	| "night"
	| "neon"
	| "neutral";

export interface Environment3DFog {
	/** Display color surfaces fade into; match the background for a seamless horizon. */
	color: string;
	/** Distance from the camera (px) where fog starts. */
	start: number;
	/** Distance where fog reaches `opacity`. */
	end: number;
	/** Max fog coverage 0..1. Default 1. */
	opacity?: number;
}

export interface Environment3DFloor {
	/** World Y coordinate of the floor plane (px, y down). */
	y: number;
	/** Base floor surface color (default "#08070a"). */
	color?: string;
	/** Mirror reflectivity at normal incidence / Fresnel scale, 0..1 (default 0.35). */
	reflectivity?: number;
	/** Surface roughness 0..1: controls anisotropic vertical/horizontal reflection blur (default 0.35). */
	roughness?: number;
	/** Reflection fade-out distance from the floor plane in world Y px (default 900). */
	fadeDistance?: number;
	/** Optional overall opacity of the floor plane, 0..1 (default 1; 0 draws only the additive reflection over background). */
	opacity?: number;
}

export interface Environment3DVolumetricFogNoise {
	/** World-space noise frequency (1 / period in px). Default 0.003. */
	scale?: number;
	/** Density modulation depth 0..1. Default 0.45. */
	strength?: number;
	/** Wind drift velocity [vx, vy, vz] in world px/sec. Default [20, -8, 12]. */
	speed?: [number, number, number];
	/** FBM octaves 1..3. Default 2. */
	octaves?: number;
}

export interface Environment3DVolumetricFog {
	/** Base extinction/scattering density (typical range 0.002..0.15, default 0.02). */
	density?: number;
	/** In-scattering albedo tint (default: environment horizon color). */
	color?: string;
	/** Henyey-Greenstein forward/back scatter asymmetry g in (-0.95..0.95). Default 0.55. */
	anisotropy?: number;
	/** Exponential height falloff rate (0 = uniform, >0 = ground mist). Default 0.0015. */
	heightFalloff?: number;
	/** Reference world Y height for ground fog (px, y down). Default 540. */
	baseHeight?: number;
	/** Raymarch step count per half-res pixel (8..64, default 28). */
	steps?: number;
	/** Maximum raymarch distance from camera in world px. Default 2800. */
	maxDistance?: number;
	/** Multiplier on direct-light in-scattering / god rays. Default 1.5. */
	lightIntensity?: number;
	/** Multiplier on ambient / sky in-scattering. Default 0.35. */
	ambientIntensity?: number;
	/** Optional 3D procedural FBM turbulence in the fog medium. */
	noise?: boolean | Environment3DVolumetricFogNoise;
}

/** Screen-space reflections: glossy surfaces reflect what the camera sees. */
export interface Environment3DSsrOptions {
	/** How fully a found reflection replaces the environment's, 0..1. Default 0.85. */
	intensity?: number;
	/** Roughest surface that traces reflections (0..1); rougher ones keep the environment. Default 0.6. */
	maxRoughness?: number;
	/** How far behind a surface, in world px, a ray still counts as hitting it. Default 120. */
	thickness?: number;
	/** Hi-Z march iterations per ray (16..64). Default 32. */
	steps?: number;
}

/** Screen-space diffuse GI: ambient occlusion plus one bounce of visible light. */
export interface Environment3DGiOptions {
	/** Strength of the bounced light, 0..4. Default 1. */
	intensity?: number;
	/** Gather radius in world px. Default 400. */
	radius?: number;
	/** Horizon-scan directions per pixel (4..16). Default 6. */
	samples?: number;
}

export interface Environment3DOptions {
	preset?: EnvironmentPreset;
	/** Equirectangular panorama for real HDRI IBL: a `.hdr` (Radiance RGBE) or `.exr` (OpenEXR) path, or the file's bytes. */
	hdri?: string | Uint8Array;
	/** Overrides the preset's sky (above), horizon and ground colors. */
	top?: string;
	horizon?: string;
	bottom?: string;
	/** Scales the whole environment's light. Default 1. */
	intensity?: number;
	/** Strength of the studio softboxes reflected in glossy surfaces. */
	softboxes?: number;
	/** Turns the environment around the vertical axis, degrees. */
	rotation?: number;
	/** Exposure in stops: +1 doubles brightness. Default 0. */
	exposure?: number;
	/** Default "neutral". */
	toneMapping?: ToneMapping;
	fog?: Environment3DFog;
	floor?: Environment3DFloor;
	outlines?: boolean | GeometryOutlineOptions;
	/** Froxel-style volumetric participating media & shadowed light shafts (god rays). */
	volumetricFog?: boolean | Environment3DVolumetricFog;
	/** Screen-space reflections of nearby geometry and emissives on glossy surfaces. */
	ssr?: boolean | Environment3DSsrOptions;
	/** Screen-space diffuse GI: occlusion and color bleeding from visible surfaces. */
	gi?: boolean | Environment3DGiOptions;
}

interface PresetDef {
	top: string;
	horizon: string;
	bottom: string;
	softboxes: number;
}

export const ENVIRONMENT_PRESETS: Record<EnvironmentPreset, PresetDef> = {
	/** Neutral photo studio: bright overhead softbox, grey sweep, dark floor bounce. */
	studio: {
		top: "#9da3ad",
		horizon: "#5d626b",
		bottom: "#202226",
		softboxes: 3.5,
	},
	/** Bright, low-contrast daylight room. */
	soft: {
		top: "#f1efea",
		horizon: "#cfcac1",
		bottom: "#77726a",
		softboxes: 1.2,
	},
	/** Warm tungsten studio with golden key and amber bounce. */
	warm: {
		top: "#f4d7b5",
		horizon: "#c99768",
		bottom: "#3d281c",
		softboxes: 2.6,
	},
	/** Warm horizon, cool sky. */
	sunset: {
		top: "#4d63a3",
		horizon: "#ff9a5c",
		bottom: "#3b2a28",
		softboxes: 1.0,
	},
	/** Deep blue night with faint highlights; pair with emissive and point lights. */
	night: {
		top: "#121a3a",
		horizon: "#1f2950",
		bottom: "#05060b",
		softboxes: 0.5,
	},
	/** Cyberpunk neon studio with electric cyan top and magenta horizon. */
	neon: {
		top: "#26b0ff",
		horizon: "#d926a9",
		bottom: "#090414",
		softboxes: 2.8,
	},
	/** Flat grey: image-based light without studio reflections. */
	neutral: {
		top: "#9a9a9a",
		horizon: "#808080",
		bottom: "#5c5c5c",
		softboxes: 0,
	},
};

const TONE_MAPPING_CODE: Record<ToneMapping, number> = {
	none: 0,
	aces: 1,
	agx: 2,
	neutral: 3,
};

export function linearRgb(color: string): [number, number, number] {
	const c = parseCssColor(color) ?? [0, 0, 0, 1];
	const lin = (v: number) =>
		v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
	return [lin(c[0]), lin(c[1]), lin(c[2])];
}

export interface ResolvedVolumetricFog {
	density: number;
	color: [number, number, number];
	anisotropy: number;
	heightFalloff: number;
	baseHeight: number;
	steps: number;
	maxDistance: number;
	lightIntensity: number;
	ambientIntensity: number;
	noiseScale: number;
	noiseStrength: number;
	noiseSpeed: [number, number, number];
	noiseOctaves: number;
}

export interface ResolvedEnvironment {
	top: [number, number, number];
	horizon: [number, number, number];
	bottom: [number, number, number];
	softboxes: number;
	intensity: number;
	hdri?: string | Uint8Array;
	rotationRad: number;
	exposureMultiplier: number;
	toneMapping: number;
	fog?: {
		color: [number, number, number];
		start: number;
		end: number;
		opacity: number;
	};
	floor?: {
		y: number;
		color: [number, number, number];
		reflectivity: number;
		roughness: number;
		fadeDistance: number;
		opacity: number;
	};
	volumetricFog?: ResolvedVolumetricFog;
	ssr?: ResolvedSsr;
	gi?: ResolvedGi;
}

export interface ResolvedSsr {
	intensity: number;
	maxRoughness: number;
	thickness: number;
	steps: number;
}

export interface ResolvedGi {
	intensity: number;
	radius: number;
	samples: number;
}

const clamp = (v: number, lo: number, hi: number) =>
	Math.max(lo, Math.min(hi, v));

export function resolveSsr(
	ssr: boolean | Environment3DSsrOptions | undefined,
): ResolvedSsr | undefined {
	if (!ssr) return undefined;
	const cfg: Environment3DSsrOptions = ssr === true ? {} : ssr;
	return {
		intensity: clamp(cfg.intensity ?? 0.85, 0, 1),
		maxRoughness: clamp(cfg.maxRoughness ?? 0.6, 0, 1),
		thickness: Math.max(1, cfg.thickness ?? 120),
		steps: Math.round(clamp(cfg.steps ?? 32, 16, 64)),
	};
}

export function resolveGi(
	gi: boolean | Environment3DGiOptions | undefined,
): ResolvedGi | undefined {
	if (!gi) return undefined;
	const cfg: Environment3DGiOptions = gi === true ? {} : gi;
	return {
		intensity: clamp(cfg.intensity ?? 1, 0, 4),
		radius: Math.max(1, cfg.radius ?? 400),
		samples: Math.round(clamp(cfg.samples ?? 6, 4, 16)),
	};
}

export function resolveVolumetricFog(
	vf: boolean | Environment3DVolumetricFog | undefined,
	defaultColor: [number, number, number],
): ResolvedVolumetricFog | undefined {
	if (!vf) return undefined;
	const cfg: Environment3DVolumetricFog = vf === true ? {} : vf;
	const noiseCfg: Environment3DVolumetricFogNoise | undefined =
		cfg.noise === true
			? {}
			: cfg.noise && typeof cfg.noise === "object"
				? cfg.noise
				: undefined;
	return {
		density: Math.max(0, cfg.density ?? 0.02),
		color: cfg.color ? linearRgb(cfg.color) : defaultColor,
		anisotropy: Math.max(-0.95, Math.min(0.95, cfg.anisotropy ?? 0.55)),
		heightFalloff: Math.max(0, cfg.heightFalloff ?? 0.0015),
		baseHeight: cfg.baseHeight ?? 540,
		steps: Math.max(8, Math.min(64, Math.round(cfg.steps ?? 28))),
		maxDistance: Math.max(100, cfg.maxDistance ?? 2800),
		lightIntensity: Math.max(0, cfg.lightIntensity ?? 1.5),
		ambientIntensity: Math.max(0, cfg.ambientIntensity ?? 0.35),
		noiseScale: Math.max(0.0001, noiseCfg?.scale ?? 0.003),
		noiseStrength: noiseCfg
			? Math.max(0, Math.min(1, noiseCfg.strength ?? 0.45))
			: 0,
		noiseSpeed: noiseCfg?.speed ?? [20, -8, 12],
		noiseOctaves: noiseCfg
			? Math.max(1, Math.min(3, Math.round(noiseCfg.octaves ?? 2)))
			: 0,
	};
}

/** Linear radiance and shader codes for an environment. */
export function resolveEnvironment(
	opts: Environment3DOptions,
): ResolvedEnvironment {
	const preset =
		ENVIRONMENT_PRESETS[opts.preset ?? "studio"] ?? ENVIRONMENT_PRESETS.studio;
	const k = opts.intensity ?? 1;
	const scale = (c: [number, number, number]): [number, number, number] => [
		c[0] * k,
		c[1] * k,
		c[2] * k,
	];
	const horizonLinear = linearRgb(opts.horizon ?? preset.horizon);
	return {
		top: scale(linearRgb(opts.top ?? preset.top)),
		horizon: scale(horizonLinear),
		bottom: scale(linearRgb(opts.bottom ?? preset.bottom)),
		softboxes: (opts.softboxes ?? preset.softboxes) * k,
		intensity: k,
		...(opts.hdri !== undefined && { hdri: opts.hdri }),
		rotationRad: ((opts.rotation ?? 0) * Math.PI) / 180,
		exposureMultiplier: 2 ** (opts.exposure ?? 0),
		toneMapping: TONE_MAPPING_CODE[opts.toneMapping ?? "neutral"],
		fog: opts.fog
			? {
					color: linearRgb(opts.fog.color),
					start: opts.fog.start,
					end: opts.fog.end,
					opacity: Math.max(0, Math.min(1, opts.fog.opacity ?? 1)),
				}
			: undefined,
		floor: opts.floor
			? {
					y: opts.floor.y,
					color: linearRgb(opts.floor.color ?? "#08070a"),
					reflectivity: Math.max(
						0,
						Math.min(1, opts.floor.reflectivity ?? 0.35),
					),
					roughness: Math.max(0, Math.min(1, opts.floor.roughness ?? 0.35)),
					fadeDistance: Math.max(0, opts.floor.fadeDistance ?? 900),
					opacity: Math.max(0, Math.min(1, opts.floor.opacity ?? 1.0)),
				}
			: undefined,
		volumetricFog: resolveVolumetricFog(opts.volumetricFog, horizonLinear),
		ssr: resolveSsr(opts.ssr),
		gi: resolveGi(opts.gi),
	};
}

/** Where a shadow-casting light's depth map lives, for the lit shaders. */
export interface ShadowUniformInfo {
	/** Light view-projection (world → shadow clip). For omnidirectional point shadows, element [0] stores far plane. */
	matrix: ArrayLike<number>;
	/** Index of the casting light among the packed (non-ambient) lights. */
	lightIndex: number;
	/** Shadow map size in texels. */
	mapSize: number;
	/** Blur radius in texels. */
	softness: number;
	/** Depth bias in NDC. */
	bias: number;
	/** Pushes the lookup along the normal, world px. */
	normalOffset: number;
	/** 0 = invisible shadows, 1 = fully dark. */
	darkness: number;
	/** Starting layer index in the shadow depth 2D array texture. */
	baseLayer?: number;
	/** Number of array layers consumed by this shadow entry (1 for directional/spot/rect, 6 for point). */
	layerCount?: number;
	/** Shadow projection mode: 1 = 2D frustum, 2 = 6-face omnidirectional cube. */
	mode?: 1 | 2;
	/** Near plane distance in world px (used by mode=2 omnidirectional point shadows). */
	near?: number;
	/** Far plane distance in world px (used by mode=2 omnidirectional point shadows). */
	far?: number;
}