Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.html
new file mode 100644
index 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.js
new file mode 100644
index 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.mjs
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 shadows
Shadow controls define an orthographic projector aligned with the current light direction.
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index 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.mjs
index 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.js
index 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.js
index 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.js
index 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 './g
import { 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.js
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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');
+});