3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { lightShapeSupport } from './shader-registry.js';
// The IES profile math, apart from the shader code so the path tracer can read it alone.
// An IES profile is the candela of a lamp against the angle from its axis, in degrees. It is stored as 16 relative
// values at equal steps of angle from 0 (the axis) to 90 degrees (the plane of the lamp), divided by the value on the
// axis, so `intensity` stays the candela head on. The raster shader and the path tracer read the same 16 values.
// A spot light multiplies its cone by the profile; an area light multiplies its Lambert emission by it.
export const PROFILE_SAMPLE_COUNT = 16;
const PROFILE_MAXIMUM_POINTS = 32;
// A lamp whose axis value is below this share of its peak is normalized by the peak, so the samples stay finite.
const MINIMUM_AXIS_SHARE = 1e-6;
// Bundled profiles, made for Crucible as cosine powers (CC0): the exponent sets how tight the beam is.
// 'batwing' peaks at 45 degrees off the axis, as a wall washer does.
const BUNDLED_EXPONENTS = { 'wide-flood': 1.5, downlight: 6, 'narrow-spot': 30 };
export const IES_PROFILE_NAMES = Object.freeze([...Object.keys(BUNDLED_EXPONENTS), 'batwing']);
function bundledCandela(name, angleDegrees) {
const radians = (angleDegrees * Math.PI) / 180;
if (name === 'batwing') return 0.35 + 0.65 * Math.sin(2 * radians) ** 2;
return Math.cos(radians) ** BUNDLED_EXPONENTS[name];
}
function bundledProfile(name) {
const angles = [];
for (let step = 0; step <= 9; step++) angles.push(step * 10);
return { angles, candela: angles.map(angle => bundledCandela(name, angle)) };
}
/** Checks a recipe's `ies` value (a bundled name or { angles, candela }) and returns it in one canonical shape. */
export function resolveIesProfile(value, label = 'ies') {
if (typeof value === 'string') {
if (!IES_PROFILE_NAMES.includes(value)) throw new RangeError(`${label} must be one of ${IES_PROFILE_NAMES.join(', ')} or { angles, candela }.`);
return value;
}
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${label} must be a profile name or { angles, candela }.`);
const { angles, candela } = value;
if (!Array.isArray(angles) || !Array.isArray(candela) || angles.length !== candela.length || angles.length < 2 || angles.length > PROFILE_MAXIMUM_POINTS) {
throw new RangeError(`${label} angles and candela must be arrays of the same length, from 2 to ${PROFILE_MAXIMUM_POINTS}.`);
}
angles.forEach((angle, index) => {
if (typeof angle !== 'number' || !Number.isFinite(angle) || angle < 0 || angle > 180 || (index > 0 && angle <= angles[index - 1])) {
throw new RangeError(`${label} angles must be degrees from 0 to 180, strictly rising.`);
}
});
candela.forEach(entry => {
if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0 || entry > 1e7) throw new RangeError(`${label} candela must be numbers from 0 to 10000000.`);
});
if (!candela.some(entry => entry > 0)) throw new RangeError(`${label} candela needs a value above zero.`);
return { angles: [...angles], candela: [...candela] };
}
function candelaAt(profile, angleDegrees) {
const { angles, candela } = profile;
if (angleDegrees <= angles[0]) return candela[0];
for (let index = 1; index < angles.length; index++) {
if (angleDegrees <= angles[index]) {
const fraction = (angleDegrees - angles[index - 1]) / (angles[index] - angles[index - 1]);
return candela[index - 1] + (candela[index] - candela[index - 1]) * fraction;
}
}
return 0;
}
const profileCache = new Map();
/** The 16 relative values of a profile, 1 on the axis. The array is shared: do not change it. */
export function profileSamples(value) {
const key = typeof value === 'string' ? value : JSON.stringify(value);
const cached = profileCache.get(key);
if (cached) return cached;
const profile = typeof value === 'string' ? bundledProfile(value) : value;
const peak = Math.max(...profile.candela);
const onAxis = candelaAt(profile, 0) >= peak * MINIMUM_AXIS_SHARE ? candelaAt(profile, 0) : peak;
const samples = new Float32Array(PROFILE_SAMPLE_COUNT);
for (let index = 0; index < PROFILE_SAMPLE_COUNT; index++) {
samples[index] = candelaAt(profile, (index / (PROFILE_SAMPLE_COUNT - 1)) * 90) / onAxis;
}
if (profileCache.size > 64) profileCache.clear();
profileCache.set(key, samples);
return samples;
}
/** The gain of a profile at the cosine of the angle from the lamp's axis; 0 at or past 90 degrees. */
export function profileGain(samples, cosine) {
if (cosine <= 0) return 0;
const position = (Math.acos(Math.min(cosine, 1)) / (Math.PI / 2)) * (PROFILE_SAMPLE_COUNT - 1);
const lower = Math.floor(position);
const upper = Math.min(lower + 1, PROFILE_SAMPLE_COUNT - 1);
return samples[lower] + (samples[upper] - samples[lower]) * (position - lower);
}
// The path tracer's scene builder reaches the profile through this hook, so it carries none of this code unless a light asks for a profile.
lightShapeSupport.profile = value => Array.from(profileSamples(resolveIesProfile(value, 'ies')));