Skip to content

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

5.6 KB
Raw Blame
import type {
	EnvironmentPreset,
	LightNode,
	ToneMapping,
} from "@framefields/compositions/program";
import { autoId } from "./ids.js";
import {
	type AnimatableNode,
	type EnvironmentOptions,
	Light,
} from "./index.js";

export interface LightingRigOptions {
	/** What the lights aim at (world px). Default: the canvas center at z 0. */
	target?: [number, number, number];
	/** How far the lights sit from the target. Default 1600. */
	distance?: number;
	/** Turns the whole rig (lights and environment) around the vertical axis, degrees. */
	rotation?: number;
	/** Scales every light. Default 1. */
	intensity?: number;
	/** Exposure in stops. Default 0. */
	exposure?: number;
	toneMapping?: ToneMapping;
	/** Key light casts a soft shadow. Default true. */
	shadows?: boolean;
	/** Shadow edge blur in texels. Default 3. */
	shadowSoftness?: number;
	/** Fog fading into the background, e.g. `{ color: BG, start: 2500, end: 6000 }`. */
	fog?: EnvironmentOptions["fog"];
	/** Volumetric fog & shadowed light shafts (god rays): `true` or settings. */
	volumetricFog?: EnvironmentOptions["volumetricFog"];
	/** Screen-space reflections of nearby geometry on glossy surfaces: `true` or settings. */
	ssr?: EnvironmentOptions["ssr"];
	/** Screen-space diffuse GI (contact occlusion and color bleeding): `true` or settings. */
	gi?: EnvironmentOptions["gi"];
	/** Glow around emissive surfaces and highlights: `true` or settings. */
	bloom?: EnvironmentOptions["bloom"];
	/** Prefix for the rig's node ids. */
	id?: string;
}

interface RigSpec {
	environment: EnvironmentPreset;
	envIntensity: number;
	/** Light directions relative to the target, before `rotation`; y is down. */
	key: { dir: [number, number, number]; color: string; intensity: number };
	rim?: { dir: [number, number, number]; color: string; intensity: number };
	fill?: { dir: [number, number, number]; color: string; intensity: number };
}

const RIGS = {
	/** Product photography: soft overhead key with a shadow, cool rim, studio reflections. */
	studio: {
		environment: "studio",
		envIntensity: 1,
		key: { dir: [-0.55, -1, -0.7], color: "#fff6ec", intensity: 1.1 },
		rim: { dir: [0.9, -0.5, 0.9], color: "#dbe8ff", intensity: 0.9 },
	},
	/** Bright, airy, low contrast: lifestyle and UI-on-device shots. */
	soft: {
		environment: "soft",
		envIntensity: 1,
		key: { dir: [-0.4, -1, -0.8], color: "#ffffff", intensity: 1.0 },
	},
	/** Low warm sun, long shadows, cool sky fill. */
	sunset: {
		environment: "sunset",
		envIntensity: 0.9,
		key: { dir: [-1, -0.35, -0.3], color: "#ffb27a", intensity: 2.2 },
		fill: { dir: [0.8, -0.6, -0.4], color: "#7f9cff", intensity: 0.35 },
	},
	/** Moody: dark world, hard key, strong rim. Pair with emissive accents. */
	dramatic: {
		environment: "night",
		envIntensity: 0.8,
		key: { dir: [-0.8, -1, -0.35], color: "#ffffff", intensity: 2.4 },
		rim: { dir: [0.7, -0.4, 1], color: "#8fb4ff", intensity: 1.8 },
	},
} satisfies Record<string, RigSpec>;

export type LightingRig = keyof typeof RIGS;

function rotateY(
	[x, y, z]: [number, number, number],
	degrees: number,
): [number, number, number] {
	const r = (degrees * Math.PI) / 180;
	const c = Math.cos(r);
	const s = Math.sin(r);
	return [c * x + s * z, y, -s * x + c * z];
}

function aim(
	dir: [number, number, number],
	target: [number, number, number],
	distance: number,
	rotation: number,
): Pick<LightNode, "x" | "y" | "z" | "targetX" | "targetY" | "targetZ"> {
	const [dx, dy, dz] = rotateY(dir, rotation);
	const len = Math.hypot(dx, dy, dz) || 1;
	return {
		x: target[0] + (dx / len) * distance,
		y: target[1] + (dy / len) * distance,
		z: target[2] + (dz / len) * distance,
		targetX: target[0],
		targetY: target[1],
		targetZ: target[2],
	};
}

function rig(
	name: LightingRig,
	options: LightingRigOptions,
): AnimatableNode<LightNode>[] {
	const spec: RigSpec = RIGS[name];
	const target = options.target ?? [960, 540, 0];
	const distance = options.distance ?? 1600;
	const rotation = options.rotation ?? 0;
	const k = options.intensity ?? 1;
	const id = options.id ?? autoId(`lighting-${name}`);
	const nodes: AnimatableNode<LightNode>[] = [
		Light.environment(spec.environment, {
			id: `${id}-environment`,
			intensity: spec.envIntensity * k,
			rotation,
			exposure: options.exposure,
			toneMapping: options.toneMapping,
			fog: options.fog,
			volumetricFog: options.volumetricFog,
			ssr: options.ssr,
			gi: options.gi,
			bloom: options.bloom,
		}),
		Light.directional({
			id: `${id}-key`,
			color: spec.key.color,
			intensity: spec.key.intensity * k,
			...aim(spec.key.dir, target, distance, rotation),
			castShadow: options.shadows ?? true,
			shadowSoftness: options.shadowSoftness ?? 3,
		}),
	];
	for (const [part, light] of [
		["rim", spec.rim],
		["fill", spec.fill],
	] as const) {
		if (!light) continue;
		nodes.push(
			Light.directional({
				id: `${id}-${part}`,
				color: light.color,
				intensity: light.intensity * k,
				...aim(light.dir, target, distance, rotation),
			}),
		);
	}
	return nodes;
}

/**
 * Ready-made lighting: an environment (physical shading, tone mapping) plus
 * placed key / rim / fill lights, the key casting a soft shadow. Add the
 * returned nodes to the composition: `comp.add(Lighting.studio({ target }))`.
 *
 * Tweak from there rather than starting from zero: `intensity`, `exposure`,
 * `rotation` (turns the rig), `shadowSoftness`, `fog`.
 */
export const Lighting = {
	studio: (options: LightingRigOptions = {}) => rig("studio", options),
	soft: (options: LightingRigOptions = {}) => rig("soft", options),
	sunset: (options: LightingRigOptions = {}) => rig("sunset", options),
	dramatic: (options: LightingRigOptions = {}) => rig("dramatic", options),
};