3D engine that AI agents drive
Add color balance, glare and lens distortion as named post steps (issue #602)
Nguyen Xuan An34c8bf8f894c
diff --git a/bench/post/post-steps.html b/bench/post/post-steps.htmlnew file mode 100644index 00000000..efc4265a--- /dev/null+++ b/bench/post/post-steps.html@@ -0,0 +1,10 @@+<!doctype html>+<html>+<head>+<style>html,body{margin:0;height:100%;background:#000}canvas{width:100vw;height:100vh;display:block}</style>+</head>+<body>+<canvas></canvas>+<script type="module" src="./post-steps.js"></script>+</body>+</html>diff --git a/bench/post/post-steps.js b/bench/post/post-steps.jsnew file mode 100644index 00000000..67887226--- /dev/null+++ b/bench/post/post-steps.js@@ -0,0 +1,70 @@+// Runs in the page: a lit pillar, a bright emissive strip and a row of posts over a floor, drawn with each named post step off and on.+import { Renderer67 } from '/src/renderer.js';+import { box } from '/src/geometry.js';+import { installCameraEffects } from '/src/camera-effects.js';++// The named steps are an optional module: this harness loads it only when the source tree has it, so the same page also+// draws the default picture of an older tree.+const postStepsPath = '/src/post-steps.js';+const postSteps = await import(/* @vite-ignore */ postStepsPath).catch(() => null);++function placed(center, size) {+ return new Float32Array([size[0], 0, 0, 0, 0, size[1], 0, 0, 0, 0, size[2], 0, center[0], center[1], center[2], 1]);+}++function sceneParts() {+ const material = { color: [0.75, 0.75, 0.78], metallic: 0, roughness: 0.7 };+ const lamp = { color: [1, 0.9, 0.7], emissiveColor: [1, 0.9, 0.7], metallic: 0, roughness: 1, emission: 14 };+ const parts = [+ { geometry: box(), matrix: placed([0, -0.05, 0], [10, 0.1, 10]), material },+ { geometry: box(), matrix: placed([0, 0.6, 0], [0.4, 1.2, 0.4]), material },+ { geometry: box(), matrix: placed([-1.2, 1.6, -0.6], [0.9, 0.06, 0.06]), material: lamp },+ ];+ for (let index = 0; index < 5; index++) {+ parts.push({ geometry: box(), matrix: placed([-2.4 + index * 1.2, 0.35, -2 - index * 1.4], [0.3, 0.7, 0.3]), material });+ }+ return parts;+}++const environment = { keyIntensity: 1, fillIntensity: 0.2, ambientIntensity: 0.2, lightDirection: [-3, 6, 4] };+const CASES = {+ default: {},+ defocus: { depthOfField: { blur: 0.8, focusDistance: 4.5 } },+ 'color-balance': { colorBalance: { lift: [0.06, 0, -0.06], gamma: [1, 1, 1.2], gain: [1.2, 1, 0.8] } },+ 'glare-streaks': { glare: { streaks: 0.8, threshold: 1, size: 0.2 } },+ 'glare-fog': { glare: { fogGlow: 0.6, threshold: 1, size: 0.12 } },+ 'lens-distortion': { lensDistortion: { distortion: 0.8 } },+ 'lens-dispersion': { lensDistortion: { dispersion: 1 } },+};+const camera = { eye: [3.4, 1.8, 4.6], target: [0, 0.8, -1], fov: 45 };++async function drawCase(name, { warmupFrames = 4, measuredFrames = 20 } = {}) {+ const canvas = document.querySelector('canvas');+ const renderer = installCameraEffects(new Renderer67(canvas, sceneParts(), { ground: false, hdr: true, depth: true, samples: 4, pixelRatio: 1, memoryBudgetMiB: 1024, environment }));+ if (postSteps) postSteps.installPostSteps(renderer);+ renderer.resize();+ const frame = { ...camera, environment, time: 0, exposure: 1, effects: { ambientOcclusion: 0, ...CASES[name] } };+ const pixel = new Uint8Array(4);+ const finishDrawing = () => renderer.context.readPixels(0, 0, 1, 1, renderer.context.RGBA, renderer.context.UNSIGNED_BYTE, pixel);+ for (let index = 0; index < warmupFrames; index++) {+ renderer.render(frame);+ finishDrawing();+ }+ const frameMilliseconds = [];+ for (let index = 0; index < measuredFrames; index++) {+ const started = performance.now();+ renderer.render(frame);+ finishDrawing();+ frameMilliseconds.push(performance.now() - started);+ }+ renderer.render(frame);+ const glError = renderer.context.getError();+ const image = canvas.toDataURL('image/png').split(',')[1];+ renderer.dispose();+ frameMilliseconds.sort((first, second) => first - second);+ return { name, glError, image, medianMilliseconds: frameMilliseconds[Math.floor(measuredFrames / 2)] };+}++window.hasPostSteps = Boolean(postSteps);+window.caseNames = Object.keys(CASES);+window.drawCase = drawCase;diff --git a/bench/post/post-steps.mjs b/bench/post/post-steps.mjsnew file mode 100644index 00000000..8fbcc301--- /dev/null+++ b/bench/post/post-steps.mjs@@ -0,0 +1,53 @@+// Draws the default frame and each named post step (defocus, color balance, glare, lens distortion) and writes a still and a frame time for each.+// node bench/post/post-steps.mjs [--root=<source tree>] [--out=<folder>] [--rounds=N] [--size=WIDTHxHEIGHT]+// --root draws another checkout's src (for example `git archive origin/main` unpacked in a temporary folder),+// which is how the default pictures are compared byte for byte with main; the cases that need the named steps are skipped.+import { constants, setPriority } from 'node:os';+import { createHash } from 'node:crypto';+import { mkdir, writeFile } from 'node:fs/promises';+import { resolve } from 'node:path';+import { chromium } from 'playwright';+import { createServer } from 'vite';++const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';+const PAGE_LOAD_TIMEOUT = 60000;+const argumentValue = (name, fallback) => process.argv.find(argument => argument.startsWith(`--${name}=`))?.split('=')[1] ?? fallback;+const root = resolve(argumentValue('root', '.'));+const outputFolder = resolve(argumentValue('out', 'artifacts/post-steps'));+const rounds = Number(argumentValue('rounds', 3));+const [width, height] = argumentValue('size', '480x270').split('x').map(Number);++setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);+const server = await createServer({ root, server: { host: '127.0.0.1', port: 0, fs: { strict: false } }, logLevel: 'silent' });+await server.listen();+const serverUrl = `http://127.0.0.1:${server.httpServer.address().port}`;+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--ignore-gpu-blocklist', '--use-angle=d3d11', '--enable-gpu', '--disable-renderer-backgrounding'] });+try {+ const page = await browser.newPage({ viewport: { width, height } });+ await page.goto(`${serverUrl}/bench/post/post-steps.html`, { timeout: PAGE_LOAD_TIMEOUT });+ await page.waitForFunction(() => window.drawCase, null, { timeout: PAGE_LOAD_TIMEOUT });+ const hasPostSteps = await page.evaluate(() => window.hasPostSteps);+ const names = (await page.evaluate(() => window.caseNames)).filter(name => hasPostSteps || !/color-balance|glare|lens/.test(name));+ await mkdir(outputFolder, { recursive: true });+ const medians = new Map(names.map(name => [name, []]));+ const hashes = {};+ for (let round = 0; round < rounds; round++) {+ for (const name of round % 2 === 0 ? names : [...names].reverse()) {+ const result = await page.evaluate(caseName => window.drawCase(caseName), name);+ if (result.glError !== 0) throw new Error(`${name}: GL error ${result.glError}`);+ medians.get(name).push(result.medianMilliseconds);+ const png = Buffer.from(result.image, 'base64');+ hashes[name] = createHash('sha256').update(png).digest('hex').slice(0, 16);+ await writeFile(resolve(outputFolder, `${name}.png`), png);+ }+ }+ const summary = {};+ for (const [name, values] of medians) {+ const sorted = [...values].sort((first, second) => first - second);+ summary[name] = { medianMilliseconds: Number(sorted[Math.floor(sorted.length / 2)].toFixed(3)), rangeMilliseconds: [sorted[0], sorted.at(-1)].map(value => Number(value.toFixed(3))), hash: hashes[name] };+ }+ console.log(JSON.stringify({ size: [width, height], rounds, summary }, null, 1));+} finally {+ await browser.close();+ await server.close();+}diff --git a/changes/602-post-steps.md b/changes/602-post-steps.mdnew file mode 100644index 00000000..64d38eae--- /dev/null+++ b/changes/602-post-steps.md@@ -0,0 +1 @@+- Three named post steps join defocus (`effects.depthOfField`) in the look: `effects.colorBalance` (`lift`, `gamma`, `gain`, each three numbers), `effects.glare` (`streaks`, `fogGlow`, `threshold`, `size`) and `effects.lensDistortion` (`distortion`, `dispersion`). Each is off until a recipe names it and draws nothing at its neutral values, so a recipe without them renders the same pixels as before. Their code is a lazy module that loads only for a recipe that names one; `installPostSteps(renderer)` from `src/post-steps.js` adds the stages (#602)diff --git a/changes/602-post-steps.size.md b/changes/602-post-steps.size.mdnew file mode 100644index 00000000..f94e05b9--- /dev/null+++ b/changes/602-post-steps.size.md@@ -0,0 +1,3 @@+- scene:agent-scene+lazy: the lazy post-steps module (three GLSL stages, the resolver and the stage installer), loaded only for a recipe that names colorBalance, glare or lensDistortion; it brings the camera-effects stage code with it.+- goal:agent-scene: a module marker, a loader line and two reads of the registry that carry the three field names (43 bytes gzip); every stage and shader is lazy.+- tool-total: three bare group fields (49 bytes in each of scene_create, scene_apply and scene_create_asset); the fields and ranges are in docs/agent-look.md and the engine's errors.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 621d6808..3f6cbb87 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -258,6 +258,15 @@ Ambient occlusion reads the depth texture, so it needs the HDR depth target that| `depthOfField.focusDistance` | `5` | `0.01` to `100000` metres from the camera that stay sharp || `motionBlur.shutter` | `0` | `0` to `0.5` seconds of camera motion to smear || `motionBlur.objects` | `0` | `0` to `1`. How much of each moving part's own motion to smear over the same shutter; `0` leaves it off |+| `colorBalance.lift` | `[0, 0, 0]` | Three numbers, `-1` to `1`. Raises the shadows per channel and fades out toward white |+| `colorBalance.gamma` | `[1, 1, 1]` | Three numbers, `0.1` to `4`. Bends the midtones; above `1` is brighter |+| `colorBalance.gain` | `[1, 1, 1]` | Three numbers, `0` to `4`. Scales the highlights |+| `glare.streaks` | `0` | `0` to `1`. Four diagonal streaks from every pixel above the threshold |+| `glare.fogGlow` | `0` | `0` to `1`. A soft halo around the same bright pixels |+| `glare.threshold` | `1` | `0` to `10`. Peak scene brightness (linear, before tone mapping) from which a pixel glares |+| `glare.size` | `0.15` | `0.01` to `1`. Streak length and halo radius as a fraction of the image height |+| `lensDistortion.distortion` | `0` | `-1` to `1`. Above `0` is barrel, below is pincushion |+| `lensDistortion.dispersion` | `0` | `0` to `1`. Red and blue split apart toward the edges, up to 3 percent of the distance from the center |Depth of field and motion blur are deterministic: they read the frame, its depth and the camera, with fixed sample patterns, so a seek to a time gives the same pixels as playing to it.Depth of field applies to every render, including `scene_look`.@@ -265,6 +274,8 @@ Motion blur needs camera `motion` tracks and a render job with `settings.motion`With `motionBlur.objects` above zero, a part that moves between `motion.start + elapsed - shutter` and `motion.start + elapsed` also smears along its own screen path while the still background stays sharp (`1` is the full shutter). It reads each pixel's part from an object ID pass, so it costs a second draw of the frame, and it replaces the camera smear on that frame, since it covers the camera's motion too. A part is moved as one rigid body by its node transform: a skinned or morphed part, an imported asset and a translucent part are not smeared per object.Both effects compile their shader and allocate their targets the first time a frame uses them, and a scene that leaves them at zero pays nothing.+The named post steps are `depthOfField` (defocus from depth), `colorBalance`, `glare` and `lensDistortion`. Each is its own group, off until a recipe names it, and a group at its neutral values draws nothing. They run on the resolved HDR frame, before bloom and tone mapping, in this order: depth of field, motion blur, glare, lens distortion, color balance. Like the two above they are deterministic, and `colorBalance`, `glare` and `lensDistortion` load their code and shaders only for a recipe that names one.+## Directional shadowsShadow controls define an orthographic projector aligned with the current light direction.diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 7b759791..9709d06c 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -259,6 +259,7 @@ function draw(record, time = 0, camera = record.scene.camera, frameOptions = {})applyRecipeWindHeading(record.renderer, environment);const { objectMotion, ...renderOptions } = frameOptions;const frame = { ...camera, environment: litEnvironment(record.scene.parts, environment, Boolean(record.renderer.groundPart)), effects, exposure: effects.exposure, time, lines: environment.lines, ...windFrame(environment), ...renderOptions, effects: effectsWithFStop(renderOptions.effects ?? effects, camera) };+ if (effects.colorBalance || effects.glare || effects.lensDistortion) agentSceneModule('postSteps').installPostSteps(record.renderer);if (objectMotion) {// Object motion blur reads each pixel's part from the object ID pass, drawn first; the lit frame then smears along each part's motion.const { installObjectMotionBlur, packObjectMotion } = agentSceneModule('objectMotionBlur');diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 4b89fb7e..210eb440 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -268,6 +268,8 @@ const environment = z.strictObject({const environmentReference = z.record(z.string(), z.unknown()).describe('Same fields as recipe.environment in scene_create.').pipe(environment);+// Named post steps are checked by the engine and listed in docs/agent-look.md; every tool that takes a recipe repeats this schema.+const looseField = z.unknown().optional();const effects = z.strictObject({exposure: bounded(0.01, 16).optional(),saturation: bounded(0, 2).optional(),@@ -284,6 +286,9 @@ const effects = z.strictObject({}).optional(),depthOfField: z.strictObject({ blur: unit.optional(), focusDistance: bounded(0.01, 100000).optional() }).optional().describe('Lens blur: blur 0 to 1, focusDistance metres.'),motionBlur: z.strictObject({ shutter: bounded(0, 0.5).optional(), objects: bounded(0, 1).optional() }).optional().describe('Motion smear, shutter in seconds. objects 0 to 1 also smears each moving part along its own motion (off at 0).'),+ colorBalance: looseField,+ glare: looseField,+ lensDistortion: looseField,});const shadow = z.strictObject({target: boundedVector(-1e6, 1e6).optional(),@@ -294,7 +299,6 @@ const shadow = z.strictObject({}).describe('Directional shadow coverage. Backend checks Float32 view/projection consistency.');// Curve and text sit in the geometry list only, not in mesh bases or cutters. Value types and limits are checked by the// engine and listed in scene_capabilities curveText, because every tool that takes a recipe repeats this schema.-const looseField = z.unknown().optional();function curveAndTextGeometries(id) {return [z.strictObject({ ...id, type: z.literal('curve'), points: z.array(z.unknown()).max(1024), closed: looseField, radius: looseField, taper: looseField, profile: looseField, resolution: looseField, radialSegments: looseField }).describe('Bezier sweep; see scene_capabilities curveText.'),diff --git a/src/agent-look.js b/src/agent-look.jsindex 5000462e..4861ea53 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -5,7 +5,7 @@ import { resolveVolumeFog } from './volumetric.js';import { LIQUID_OPTICS, resolveLiquidOptics } from './liquid-optics.js';import { createLightingSetupMap, createCatalogEnvironmentMap, lightingSetupFields } from './lighting-setups.js';import { agentSceneModule } from './agent-scene-modules.js';-import { lightShapeSupport } from './shader-registry.js';+import { lightShapeSupport, postStepSupport } from './shader-registry.js';import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from './view-transform-names.js';import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, isEnvironmentReference, isCubeLookReference } from './look-catalog.js';import { DEFAULT_LIGHTING_SETUP, LIGHTING_SETUP_NAMES, DEFAULT_AMBIENT_OCCLUSION } from './agent-scene-capabilities.js';@@ -367,7 +367,7 @@ export function agentEnvironmentMap(environment) {}function effectsFrom(input = {}) {- knownKeys(input, EFFECT_FIELDS, 'effects');+ knownKeys(input, [...EFFECT_FIELDS, ...postStepSupport.fields], 'effects');const groupFields = { bloom: BLOOM_FIELDS, depthOfField: DEPTH_OF_FIELD_FIELDS, motionBlur: MOTION_BLUR_FIELDS };for (const field of EFFECT_FIELDS) {if (!(field in groupFields) && Object.hasOwn(input, field)) {@@ -386,7 +386,7 @@ function effectsFrom(input = {}) {}const ambientOcclusion = fallback(input.ambientOcclusion, DEFAULT_AMBIENT_OCCLUSION);const resolved = resolveEffects({ ...input, ambientOcclusion, ...groups, bloom: { strength: 0.12, threshold: 1, radius: 1, ...groups.bloom } });- return { ...resolved, exposure: numberInRange(fallback(input.exposure, 1), 0.01, 16, 'exposure') };+ return { ...resolved, exposure: numberInRange(fallback(input.exposure, 1), 0.01, 16, 'exposure'), ...postStepSupport.resolve?.(input) };}function shadowFrom(input = {}) {diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex 7ce0c4fe..b983b1ad 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -35,6 +35,7 @@ const MODULE_LOADERS = {floorSky: () => import('./floor-sky-visibility.js'),userPass: () => import('./user-pass.js'),objectMotionBlur: () => import('./object-motion-blur.js'),+ postSteps: () => import('./post-steps.js'),materialSnippet: () => import('./material-snippet.js'),};@@ -84,6 +85,7 @@ const MODULE_MARKERS = {materialSnippet: ['"snippet":{'],// Only a motionBlur object that sets a non-zero `objects` loads it; the common `"shutter":0` look does not.objectMotionBlur: [/"motionBlur":\{[^}]*"objects":(?!0[,}])/],+ postSteps: [/"(?:colorBalance|glare|lensDistortion)"/],};/** Whether a recipe, operation list or edit list contains a boolean edit, which needs loadMeshBooleans() first. */diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 65ecb327..0660f103 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -3,6 +3,7 @@ import { box, circle, cone, cylinder, grid, icoSphere, sphere, torus } from './gimport { createSceneGraph } from './scene-graph.js';import { applyProjection, validateCameraShift, CAMERA_LENS_FIELDS } from './camera.js';import { normalizeAgentLook, environmentPatchWithSetup, environmentLinksLights, agentEnvironmentMap } from './agent-look.js';+import { postStepSupport } from './shader-registry.js';import { agentSceneModule, agentSceneModuleLoaded } from './agent-scene-modules.js';import { MESH_SMOOTH_ANGLE_DEFAULT, CURVE_TEXT_LIMITS, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, MAX_MATERIAL_PATTERNS, RECIPE_ALPHA_MODES } from './agent-scene-capabilities.js';import { ALL_LIGHTS_MASK, MATERIAL_LAYER_FIELDS, validateMaterialLayers } from './material-layers.js';@@ -1575,7 +1576,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {knownKeys(operation, ['type', lookField], 'operation');const patch = operation[lookField];// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.- const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'hdri'] : [];+ const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'hdri'] : lookField === 'effects' ? postStepSupport.fields : [];knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);const nestedField = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };diff --git a/src/post-steps.js b/src/post-steps.jsnew file mode 100644index 00000000..d10f2273--- /dev/null+++ b/src/post-steps.js@@ -0,0 +1,227 @@+import { postStepSupport } from './shader-registry.js';+import { createStage, sharedFragmentHeader } from './camera-effects.js';++// Named post steps for a graded film: color balance (lift, gamma, gain), glare (streaks and fog glow), lens distortion with+// dispersion. They are optional full-frame stages. The core renderer carries none of their code: a recipe that names one+// loads this module (agent-scene-modules.js), and each stage compiles only on the first frame that turns it on. Defocus from+// depth is the `depthOfField` group of camera-effects.js, which is the same step under its older name.+//+// All three are deterministic: fixed sample patterns and no history, so a seek repeats the same pixels.++const STREAK_DIRECTIONS = 4;+const STREAK_STEPS = 12;+const FOG_SAMPLES = 24;+// Longest lateral color offset at the image corner at full dispersion, as a fraction of the distance from the center.+const MAXIMUM_DISPERSION = 0.03;++function numberInRange(value, fallback, minimum, maximum, name) {+ const result = value ?? fallback;+ if (!Number.isFinite(result) || result < minimum || result > maximum) throw new RangeError(`${name} must be between ${minimum} and ${maximum}.`);+ return result;+}++const NEUTRAL = Object.freeze({ lift: [0, 0, 0], gamma: [1, 1, 1], gain: [1, 1, 1] });++function groupOf(value, name) {+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object.`);+ return value;+}++function onlyKeys(group, allowed, name) {+ for (const key of Object.keys(group)) {+ if (!allowed.includes(key)) throw new TypeError(`Unknown ${name} field "${key}".`);+ }+}++function triple(value, fallback, minimum, maximum, name) {+ const source = value ?? fallback;+ if (!Array.isArray(source) || source.length !== 3) throw new TypeError(`${name} must be three numbers.`);+ return source.map((component, index) => numberInRange(component, fallback[index], minimum, maximum, `${name}[${index}]`));+}++function resolveColorBalance(input) {+ const group = groupOf(input, 'colorBalance');+ onlyKeys(group, ['lift', 'gamma', 'gain'], 'colorBalance');+ return {+ lift: triple(group.lift, NEUTRAL.lift, -1, 1, 'colorBalance.lift'),+ gamma: triple(group.gamma, NEUTRAL.gamma, 0.1, 4, 'colorBalance.gamma'),+ gain: triple(group.gain, NEUTRAL.gain, 0, 4, 'colorBalance.gain'),+ };+}++function resolveGlare(input) {+ const group = groupOf(input, 'glare');+ onlyKeys(group, ['streaks', 'fogGlow', 'threshold', 'size'], 'glare');+ return {+ streaks: numberInRange(group.streaks, 0, 0, 1, 'glare.streaks'),+ fogGlow: numberInRange(group.fogGlow, 0, 0, 1, 'glare.fogGlow'),+ threshold: numberInRange(group.threshold, 1, 0, 10, 'glare.threshold'),+ size: numberInRange(group.size, 0.15, 0.01, 1, 'glare.size'),+ };+}++function resolveLensDistortion(input) {+ const group = groupOf(input, 'lensDistortion');+ onlyKeys(group, ['distortion', 'dispersion'], 'lensDistortion');+ return {+ distortion: numberInRange(group.distortion, 0, -1, 1, 'lensDistortion.distortion'),+ dispersion: numberInRange(group.dispersion, 0, 0, 1, 'lensDistortion.dispersion'),+ };+}++/** The named steps an effects input sets, resolved with their defaults. A step the input leaves out stays out of the result. */+export function resolvePostSteps(effects) {+ const resolved = {};+ if (effects.colorBalance !== undefined) resolved.colorBalance = resolveColorBalance(effects.colorBalance);+ if (effects.glare !== undefined) resolved.glare = resolveGlare(effects.glare);+ if (effects.lensDistortion !== undefined) resolved.lensDistortion = resolveLensDistortion(effects.lensDistortion);+ return resolved;+}++// Registers what the look needs: the field names it accepts and how to resolve them (src/shader-registry.js).+postStepSupport.fields = ['colorBalance', 'glare', 'lensDistortion'];+postStepSupport.resolve = resolvePostSteps;++export const colorBalanceFragment = `${sharedFragmentHeader}+uniform vec3 lift;+uniform vec3 inverseGamma;+uniform vec3 gain;+void main() {+ vec4 source = texture(sourceTexture, textureCoordinate);+ // Lift raises the shadows and fades out toward white, gain scales the highlights, gamma bends the midtones.+ vec3 graded = source.rgb * gain + lift * (1.0 - clamp(source.rgb, 0.0, 1.0));+ outputColor = vec4(pow(max(graded, vec3(0.0)), inverseGamma), source.a);+}`;++export const glareFragment = `${sharedFragmentHeader}+uniform float streakAmount;+uniform float fogAmount;+uniform float threshold;+uniform float sizePixels;+vec3 brightPart(vec2 coordinate) {+ vec3 color = texture(sourceTexture, coordinate).rgb;+ float peak = max(color.r, max(color.g, color.b));+ return color * max(peak - threshold, 0.0) / max(peak, 0.00001);+}+void main() {+ vec4 source = texture(sourceTexture, textureCoordinate);+ vec3 glow = vec3(0.0);+ float jitter = pixelRotation() / 6.2831853;+ if (streakAmount > 0.0) {+ vec3 streaks = vec3(0.0);+ for (int direction = 0; direction < ${STREAK_DIRECTIONS}; direction++) {+ float angle = 0.7853982 + float(direction) * 1.5707963;+ vec2 step = vec2(cos(angle), sin(angle)) * sizePixels / ${STREAK_STEPS}.0 / resolution;+ for (int index = 1; index <= ${STREAK_STEPS}; index++) {+ float along = float(index) - jitter;+ float weight = 1.0 - along / (${STREAK_STEPS}.0 + 1.0);+ streaks += (brightPart(textureCoordinate + step * along) + brightPart(textureCoordinate - step * along)) * weight * weight;+ }+ }+ glow += streaks * streakAmount / ${STREAK_STEPS}.0;+ }+ if (fogAmount > 0.0) {+ float rotation = pixelRotation();+ vec3 fog = vec3(0.0);+ float weightSum = 0.0;+ for (int index = 0; index < ${FOG_SAMPLES}; index++) {+ float ring = sqrt((float(index) + 0.5) / ${FOG_SAMPLES}.0);+ float angle = float(index) * 2.3999632 + rotation;+ float weight = 1.0 - ring * ring;+ fog += brightPart(textureCoordinate + vec2(cos(angle), sin(angle)) * ring * sizePixels / resolution) * weight;+ weightSum += weight;+ }+ glow += fog / weightSum * fogAmount;+ }+ outputColor = vec4(source.rgb + glow, source.a);+}`;++export const lensDistortionFragment = `${sharedFragmentHeader}+uniform float distortion;+uniform float dispersion;+void main() {+ float aspect = resolution.x / resolution.y;+ vec2 centered = (textureCoordinate - 0.5) * 2.0;+ centered.x *= aspect;+ // Positive distortion is barrel: the edges sample from further out, so they bunch toward the center. Each channel+ // takes a slightly different scale, so a line off center splits into color fringes that grow with the distance.+ float bend = 1.0 + distortion * 0.25 * dot(centered, centered);+ vec3 scales = bend * (1.0 + dispersion * ${MAXIMUM_DISPERSION} * vec3(1.0, 0.0, -1.0));+ vec2 red = centered * scales.r;+ vec2 green = centered * scales.g;+ vec2 blue = centered * scales.b;+ vec4 center = texture(sourceTexture, green / vec2(aspect, 1.0) * 0.5 + 0.5);+ outputColor = vec4(texture(sourceTexture, red / vec2(aspect, 1.0) * 0.5 + 0.5).r, center.g,+ texture(sourceTexture, blue / vec2(aspect, 1.0) * 0.5 + 0.5).b, center.a);+}`;++// The renderer resolves only the core effects, so a stage reads its group from the frame's own effects.+function stepsOf(frame) {+ return resolvePostSteps(frame.effects ?? {});+}++function isColorBalanceActive(colorBalance) {+ return Boolean(colorBalance) && ['lift', 'gamma', 'gain'].some(name => colorBalance[name].some((component, index) => component !== NEUTRAL[name][index]));+}++function createColorBalanceStage() {+ return createStage({+ name: 'Color balance',+ fragment: colorBalanceFragment,+ uniformNames: ['lift', 'inverseGamma', 'gain'],+ isActive: (effects, frame) => isColorBalanceActive(stepsOf(frame).colorBalance),+ setUniforms(context, uniforms, renderer, frame) {+ const { colorBalance } = stepsOf(frame);+ context.uniform3fv(uniforms.lift, colorBalance.lift);+ context.uniform3fv(uniforms.inverseGamma, colorBalance.gamma.map(gamma => 1 / gamma));+ context.uniform3fv(uniforms.gain, colorBalance.gain);+ },+ });+}++function createGlareStage() {+ return createStage({+ name: 'Glare',+ fragment: glareFragment,+ uniformNames: ['streakAmount', 'fogAmount', 'threshold', 'sizePixels'],+ isActive: (effects, frame) => {+ const { glare } = stepsOf(frame);+ return Boolean(glare) && (glare.streaks > 0 || glare.fogGlow > 0);+ },+ setUniforms(context, uniforms, renderer, frame) {+ const { glare } = stepsOf(frame);+ context.uniform1f(uniforms.streakAmount, glare.streaks);+ context.uniform1f(uniforms.fogAmount, glare.fogGlow);+ context.uniform1f(uniforms.threshold, glare.threshold);+ context.uniform1f(uniforms.sizePixels, glare.size * renderer.canvas.height);+ },+ });+}++function createLensDistortionStage() {+ return createStage({+ name: 'Lens distortion',+ fragment: lensDistortionFragment,+ uniformNames: ['distortion', 'dispersion'],+ isActive: (effects, frame) => {+ const { lensDistortion } = stepsOf(frame);+ return Boolean(lensDistortion) && (lensDistortion.distortion !== 0 || lensDistortion.dispersion > 0);+ },+ setUniforms(context, uniforms, renderer, frame) {+ const { lensDistortion } = stepsOf(frame);+ context.uniform1f(uniforms.distortion, lensDistortion.distortion);+ context.uniform1f(uniforms.dispersion, lensDistortion.dispersion);+ },+ });+}++/**+ * Adds glare, lens distortion and color balance to a renderer, after any depth of field and motion blur it has, in that+ * order. Like them it needs `depth: true`. Each stage runs only for a frame whose effects set it.+ */+export function installPostSteps(renderer) {+ if (!renderer.postStages.some(stage => stage.name === 'Glare')) {+ renderer.postStages.push(createGlareStage(), createLensDistortionStage(), createColorBalanceStage());+ }+ return renderer;+}diff --git a/src/shader-registry.js b/src/shader-registry.jsindex 248ae794..7aeefa4f 100644--- a/src/shader-registry.js+++ b/src/shader-registry.js@@ -19,6 +19,9 @@ export const viewTransformShader = {};// recipe hooks for area light shadows, IES profiles and the sun angle. update sets state.extraFeatures and state.bind.export const lightShapeSupport = {};+// post-steps.js sets fields (the effects it adds to the look) and resolve(effects), which returns those effects resolved.+export const postStepSupport = { fields: [] };+// texture-update.js sets update(renderer, descriptor, update): the body of renderer.updateTexture.export const textureUpdateSupport = {};diff --git a/tests/post-steps.test.js b/tests/post-steps.test.jsnew file mode 100644index 00000000..fdfbec14--- /dev/null+++ b/tests/post-steps.test.js@@ -0,0 +1,128 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { existsSync } from 'node:fs';+import { execFileSync } from 'node:child_process';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { mat4 } from 'gl-matrix';+import { resolveEffects } from '../src/effects.js';+import { normalizeAgentLook } from '../src/agent-look.js';+import { agentSceneModulesNeeded, loadAgentSceneModules } from '../src/agent-scene-modules.js';+import { installCameraEffects } from '../src/camera-effects.js';+import { installPostSteps, resolvePostSteps, glareFragment, lensDistortionFragment, colorBalanceFragment } from '../src/post-steps.js';+import { createAgentScene } from '../src/agent-scene.js';++function recordingContext(calls) {+ return new Proxy({}, {+ get(target, name) {+ if (typeof name === 'symbol') return undefined;+ if (/^[A-Z0-9_]+$/.test(name)) return 1;+ if (name === 'checkFramebufferStatus') return () => 1;+ return (...args) => {+ calls.push([name, ...args]);+ return true;+ };+ },+ });+}++function fakeRenderer(context) {+ return {+ postStages: [], context, canvas: { width: 16, height: 9 }, hdr: false, depthTexture: 'depth',+ inverseViewProjection: mat4.create(), viewForward: [0, 0, -1],+ };+}++const STAGE_NAMES = ['Glare', 'Lens distortion', 'Color balance'];++test('a look that names no step resolves exactly as before', async () => {+ await loadAgentSceneModules({});+ const effects = normalizeAgentLook({}).effects;+ for (const field of ['colorBalance', 'glare', 'lensDistortion']) assert.equal(Object.hasOwn(effects, field), false);+ assert.deepEqual(resolveEffects({}), resolveEffects({ saturation: 1 }));+});++test('each named step resolves with defaults and refuses bad input', () => {+ assert.deepEqual(resolvePostSteps({ colorBalance: {} }).colorBalance, { lift: [0, 0, 0], gamma: [1, 1, 1], gain: [1, 1, 1] });+ assert.deepEqual(resolvePostSteps({ glare: { streaks: 0.5 } }).glare, { streaks: 0.5, fogGlow: 0, threshold: 1, size: 0.15 });+ assert.deepEqual(resolvePostSteps({ lensDistortion: { dispersion: 1 } }).lensDistortion, { distortion: 0, dispersion: 1 });+ assert.deepEqual(resolvePostSteps({ saturation: 1 }), {});+ assert.throws(() => resolvePostSteps({ colorBalance: { lift: [0, 0] } }), /three numbers/);+ assert.throws(() => resolvePostSteps({ colorBalance: { gamma: [0, 1, 1] } }), /colorBalance.gamma\[0\] must be between/);+ assert.throws(() => resolvePostSteps({ colorBalance: { shadows: 1 } }), /Unknown colorBalance field/);+ assert.throws(() => resolvePostSteps({ glare: { streaks: 2 } }), /glare.streaks must be between/);+ assert.throws(() => resolvePostSteps({ glare: [] }), /glare must be an object/);+ assert.throws(() => resolvePostSteps({ lensDistortion: { distortion: -2 } }), /lensDistortion.distortion must be between/);+});++test('a recipe that names a step loads the module, validates it and keeps the group in the look', async () => {+ const look = { effects: { glare: { fogGlow: 0.4 }, lensDistortion: { distortion: 0.2 } } };+ assert.ok(agentSceneModulesNeeded(look).includes('postSteps'));+ assert.equal(agentSceneModulesNeeded({ effects: { bloom: { strength: 0.3 } } }).includes('postSteps'), false);+ await loadAgentSceneModules(look);+ const effects = normalizeAgentLook(look).effects;+ assert.equal(effects.glare.fogGlow, 0.4);+ assert.equal(effects.lensDistortion.distortion, 0.2);+ assert.equal(Object.hasOwn(effects, 'colorBalance'), false);+ assert.throws(() => normalizeAgentLook({ effects: { glare: { streaks: 3 } } }), /glare.streaks/);+ assert.throws(() => normalizeAgentLook({ effects: { sparkle: 1 } }), /sparkle/);+ // The resolved group resolves to itself, so a frame can carry the look's effects as they are.+ assert.deepEqual(resolvePostSteps(effects).glare, effects.glare);+});++test('an edit adds a step to a scene that has none', async () => {+ await loadAgentSceneModules({ effects: { colorBalance: {} } });+ const scene = createAgentScene({ format: '67js.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] });+ scene.apply([{ type: 'set-effects', effects: { colorBalance: { gain: [1.2, 1, 0.8] } } }], { expectedRevision: scene.revision });+ assert.deepEqual(scene.effects.colorBalance.gain, [1.2, 1, 0.8]);+});++test('each stage draws only for a frame that sets its step, and frees its target', () => {+ const calls = [];+ const context = recordingContext(calls);+ const renderer = installPostSteps(installCameraEffects(fakeRenderer(context)));+ assert.deepEqual(renderer.postStages.slice(2).map(stage => stage.name), STAGE_NAMES);+ assert.equal(installPostSteps(renderer).postStages.length, 5);+ const unset = { eye: [0, 1, 5], effects: {} };+ const neutral = { eye: [0, 1, 5], effects: { colorBalance: {}, glare: {}, lensDistortion: {} } };+ const named = [+ ['Glare', { glare: { streaks: 0.6 } }],+ ['Lens distortion', { lensDistortion: { distortion: 0.5, dispersion: 0.5 } }],+ ['Color balance', { colorBalance: { gain: [1.1, 1, 0.9] } }],+ ];+ const effects = resolveEffects({});+ for (const [name, input] of named) {+ const stage = renderer.postStages.find(candidate => candidate.name === name);+ assert.equal(stage.apply(renderer, unset, effects, 'source'), null, `${name} is off when unset`);+ assert.equal(stage.apply(renderer, neutral, effects, 'source'), null, `${name} is off at its neutral values`);+ assert.ok(stage.apply(renderer, { eye: [0, 1, 5], effects: input }, effects, 'source'), `${name} draws`);+ stage.releaseTargets(context);+ stage.dispose(context);+ }+ assert.ok(calls.filter(call => call[0] === 'drawArrays').length === 3);+ assert.ok(calls.filter(call => call[0] === 'deleteTexture').length === 3);+});++test('the shaders keep their fixed sample patterns and read no history', () => {+ for (const fragment of [glareFragment, lensDistortionFragment, colorBalanceFragment]) {+ assert.match(fragment, /^#version 300 es/);+ assert.doesNotMatch(fragment, /previousViewProjection|time/);+ }+});++// Draws the default frame and each step in Chrome, so it runs only when asked:+// RENDER_TESTS=1 node --test tests/post-steps.test.js (on a shared GPU, start it through the machine GPU lock)+const chromePath = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';+const rendersEnabled = process.env.RENDER_TESTS === '1' && existsSync(chromePath);+const STEP_CASES = ['defocus', 'color-balance', 'glare-streaks', 'glare-fog', 'lens-distortion', 'lens-dispersion'];++test('each named step changes the picture and the default still keeps its hash', { skip: !rendersEnabled, timeout: 300000 }, () => {+ const output = execFileSync('node', ['bench/post/post-steps.mjs', '--rounds=1', `--out=${join(tmpdir(), 'post-steps-test')}`], { encoding: 'utf8' });+ const { summary } = JSON.parse(output);+ for (const name of STEP_CASES) {+ assert.notEqual(summary[name].hash, summary.default.hash, `${name} differs from the default`);+ assert.ok(summary[name].medianMilliseconds > 0, `${name} has a frame time`);+ }+ // Hash of the default still as origin/main drew it before the named steps (bench/post/post-steps.mjs --root=<origin/main checkout>).+ assert.equal(summary.default.hash, '8741ffc3aaace9a8');+});