3D engine that AI agents drive
Blend the seams where meshes cut into each other (#478)
Nguyen Xuan An07aff3d1ecca
diff --git a/bench/reference/mesh-blend-harness.html b/bench/reference/mesh-blend-harness.htmlnew file mode 100644index 00000000..56d5c4e9--- /dev/null+++ b/bench/reference/mesh-blend-harness.html@@ -0,0 +1,10 @@+<!doctype html>+<html>+<head>+<style>html,body{margin:0;height:100%}canvas{width:100vw;height:100vh;display:block}</style>+</head>+<body>+<canvas></canvas>+<script type="module" src="/bench/reference/mesh-blend-harness.js"></script>+</body>+</html>diff --git a/bench/reference/mesh-blend-harness.js b/bench/reference/mesh-blend-harness.jsnew file mode 100644index 00000000..093bcd81--- /dev/null+++ b/bench/reference/mesh-blend-harness.js@@ -0,0 +1,106 @@+// Draws a nature terrain with sunk rocks and a trunk (or a lit box), for bench/reference/mesh-blend.mjs. It imports only+// the renderer and geometry, so the same page runs on a checkout of main, which has no mesh-blend.js.+// window.setupScene({ scene: 'nature' | 'lit-box', mode: 'plain' | 'installed' | 'blend' })+// window.snapshot() -> PNG data URL, window.measureFrames(count) -> milliseconds per frame, window.teardown()+import { mat4 } from 'gl-matrix';+import { Renderer67 } from '/src/renderer.js';+import { box, cylinder, sphere } from '/src/geometry.js';+import { createNoiseHeight, createTerrain } from '/src/terrain.js';++const canvas = document.querySelector('canvas');+let renderer = null;+let frame = null;++function placed(geometry, material, name, center, size, extra = {}) {+ const positions = geometry.positions;+ const low = [Infinity, Infinity, Infinity];+ const high = [-Infinity, -Infinity, -Infinity];+ for (let index = 0; index < positions.length; index += 3) {+ for (let axis = 0; axis < 3; axis++) {+ low[axis] = Math.min(low[axis], positions[index + axis]);+ high[axis] = Math.max(high[axis], positions[index + axis]);+ }+ }+ const middle = low.map((value, axis) => (value + high[axis]) / 2);+ const scale = size.map((value, axis) => value / (high[axis] - low[axis]));+ const matrix = new Float32Array(16);+ mat4.translate(matrix, mat4.create(), center);+ mat4.rotateY(matrix, matrix, extra.turn ?? 0);+ mat4.scale(matrix, matrix, scale);+ mat4.translate(matrix, matrix, middle.map(value => -value));+ return { name, geometry, material, matrix, ...(extra.blend ? { blend: extra.blend } : {}) };+}++function natureScene(blend) {+ const terrain = createTerrain({+ size: 160, chunks: 8, resolution: 32, levels: 3, eye: [0, 3, 8],+ height: createNoiseHeight({ amplitude: 1.2, mountainAmplitude: 0, featureSize: 22, octaves: 4, warp: 0 }, 3),+ material: { color: [0.30, 0.38, 0.16], metallic: 0, roughness: 0.95, emission: 0 },+ });+ const ground = terrain.heightAt;+ const radius = blend ? { blend: { radius: 0.18 } } : {};+ const rockMaterial = (tone) => ({ color: [tone, tone * 0.95, tone * 0.88], metallic: 0, roughness: 0.9, emission: 0 });+ const rockGeometry = sphere(48, 32);+ const blockGeometry = box(0.08, 3);+ const rocks = [[-2.6, -1.0, 1.1, 0.7], [-0.4, -2.2, 0.9, 0.55], [2.4, -0.2, 1.4, 0.9], [1.0, 1.4, 0.7, 0.5], [-3.8, 1.2, 1.6, 1.0]].map(([x, z, width, height], index) => placed(+ index % 2 ? blockGeometry : rockGeometry, rockMaterial(0.34 + index * 0.03), `rock-${index}`, [x, ground(x, z) + height * 0.18, z], [width, height, width * 0.85], { turn: index, ...radius }));+ const trunkMaterial = { color: [0.28, 0.19, 0.12], metallic: 0, roughness: 0.85, emission: 0 };+ const trunk = placed(cylinder(48, 0.01, 2), trunkMaterial, 'trunk', [-1.4, ground(-1.4, 2.2) + 1.2, 2.2], [0.55, 3.4, 0.55], radius);+ const parts = [...terrain.parts, ...rocks, trunk];+ return {+ parts,+ camera: { eye: [0.6, ground(0.6, 7) + 1.7, 7.2], target: [-0.6, ground(-0.6, 0) + 0.6, 0.4], fov: 42 },+ shadowBounds: { center: [0, 0, 0], radius: 14 },+ };+}++function litBoxScene() {+ const gray = { color: [0.6, 0.55, 0.5], metallic: 0, roughness: 0.6, emission: 0 };+ const parts = [placed(box(0.08, 3), gray, 'box', [0, 0.5, 0], [1, 1, 1])];+ return { parts, camera: { eye: [2.2, 1.6, 3], target: [0, 0.5, 0], fov: 40 }, shadowBounds: undefined };+}++window.setupScene = async ({ scene, mode }) => {+ const built = scene === 'nature' ? natureScene(mode === 'blend') : litBoxScene();+ renderer = new Renderer67(canvas, built.parts, {+ ground: scene === 'lit-box', hdr: true, depth: true, samples: 4, pixelRatio: 1, memoryBudgetMiB: 1024, world: scene === 'nature',+ ...(built.shadowBounds ? { shadowBounds: built.shadowBounds } : {}),+ });+ if (mode !== 'plain') {+ const { installRenderPasses } = await import('/src/render-passes.js');+ const { installMeshBlend } = await import(/* @vite-ignore */ ['/src/mesh', 'blend.js'].join('-'));+ installMeshBlend(installRenderPasses(renderer));+ }+ renderer.resize();+ frame = { ...built.camera, environment: { lightDirection: [-3, 6, 4] }, time: 0, exposure: 1, effects: { ambientOcclusion: 0 } };+ renderer.render(frame);+ return { width: canvas.width, height: canvas.height, glError: renderer.context.getError() };+};++window.snapshot = () => {+ renderer.render(frame);+ return canvas.toDataURL('image/png');+};++window.measureFrames = (count) => {+ const context = renderer.context;+ const pixel = new Uint8Array(4);+ for (let index = 0; index < 30; index++) {+ renderer.render(frame);+ context.readPixels(0, 0, 1, 1, context.RGBA, context.UNSIGNED_BYTE, pixel);+ }+ const times = [];+ for (let index = 0; index < count; index++) {+ const started = performance.now();+ renderer.render(frame);+ context.readPixels(0, 0, 1, 1, context.RGBA, context.UNSIGNED_BYTE, pixel);+ times.push(performance.now() - started);+ }+ return times;+};++window.teardown = () => {+ renderer.dispose();+ renderer = null;+};+window.harnessReady = true;diff --git a/bench/reference/mesh-blend.mjs b/bench/reference/mesh-blend.mjsnew file mode 100644index 00000000..3ee2a5c1--- /dev/null+++ b/bench/reference/mesh-blend.mjs@@ -0,0 +1,156 @@+// Mesh blend check for issue #478: before/after still, pixel identity against main, and the frame cost at 1080p.+// node bench/reference/mesh-blend.mjs --main-root <dir with src/ of main, bench/reference/mesh-blend-harness.html, node_modules>+// [--out <folder>] [--rounds <n>] [--frames <n>] [--skip-cost]+// Writes the PNGs and out/478-sheet.png (before, after, and a 2x crop of a seam) to the output folder.+import { mkdir, writeFile } from 'node:fs/promises';+import { constants, setPriority } from 'node:os';+import { resolve } from 'node:path';+import sharp from 'sharp';+import { chromium } from 'playwright';+import { createServer } from 'vite';++const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';+const argumentsGiven = process.argv.slice(2);+const option = (name, fallback) => (argumentsGiven.includes(name) ? argumentsGiven[argumentsGiven.indexOf(name) + 1] : fallback);+const mainRoot = option('--main-root');+const output = resolve(option('--out', 'out'));+const rounds = Number(option('--rounds', 5));+const frames = Number(option('--frames', 120));+const WIDTH = 1920;+const HEIGHT = 1080;+const BROWSER_ARGUMENTS = ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding', '--use-angle=d3d11', '--enable-gpu'];++setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);+await mkdir(output, { recursive: true });++async function withPage(root, work) {+ const server = await createServer({ root, server: { host: '127.0.0.1', port: 0, fs: { strict: false } }, logLevel: 'error' });+ await server.listen();+ const url = `http://127.0.0.1:${server.httpServer.address().port}/bench/reference/mesh-blend-harness.html`;+ const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: BROWSER_ARGUMENTS });+ try {+ const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });+ page.on('console', message => message.type() === 'error' && console.log('CONSOLE', message.text()));+ page.on('response', response => response.status() >= 400 && response.text().then(text => console.log('HTTP', response.status(), response.url(), text.slice(0, 700))));+ page.on('pageerror', error => console.log('PAGE ERROR', error.message));+ await page.goto(url, { timeout: 60000 });+ await page.waitForFunction(() => window.harnessReady, null, { timeout: 60000 });+ return await work(page);+ } finally {+ await browser.close();+ await server.close();+ }+}++async function capture(page, scene, mode) {+ const info = await page.evaluate(options => window.setupScene(options), { scene, mode });+ if (info.glError !== 0 || info.width !== WIDTH || info.height !== HEIGHT) throw new Error(`${scene}/${mode}: ${JSON.stringify(info)}`);+ const png = Buffer.from((await page.evaluate(() => window.snapshot())).split(',')[1], 'base64');+ await page.evaluate(() => window.teardown());+ return png;+}++async function maxDifference(firstPng, secondPng) {+ const [first, second] = await Promise.all([firstPng, secondPng].map(png => sharp(png).raw().toBuffer()));+ let largest = 0;+ let differing = 0;+ for (let index = 0; index < first.length; index++) {+ const difference = Math.abs(first[index] - second[index]);+ if (difference > 0) differing++;+ if (difference > largest) largest = difference;+ }+ return { largest, differing };+}++const stills = {};+await withPage(resolve('.'), async page => {+ for (const [scene, mode] of [['nature', 'plain'], ['nature', 'installed'], ['nature', 'blend'], ['lit-box', 'plain'], ['lit-box', 'installed']]) {+ stills[`branch-${scene}-${mode}`] = await capture(page, scene, mode);+ await writeFile(`${output}/mesh-blend-${scene}-${mode}.png`, stills[`branch-${scene}-${mode}`]);+ }+});+if (mainRoot) {+ await withPage(resolve(mainRoot), async page => {+ for (const scene of ['nature', 'lit-box']) stills[`main-${scene}`] = await capture(page, scene, 'plain');+ });+ for (const scene of ['nature', 'lit-box']) {+ const plain = await maxDifference(stills[`main-${scene}`], stills[`branch-${scene}-plain`]);+ const installed = await maxDifference(stills[`main-${scene}`], stills[`branch-${scene}-installed`]);+ console.log(`${scene}: max difference from main, addon not loaded ${plain.largest} (${plain.differing} values), addon installed but no blend part ${installed.largest} (${installed.differing} values)`);+ }+}+const changed = await maxDifference(stills['branch-nature-plain'], stills['branch-nature-blend']);+console.log(`nature: blend on changes ${changed.differing} channel values (max ${changed.largest})`);++// The seam crop: the 480 x 270 window with the most changed pixels, found from the difference of the two stills.+const [offPixels, onPixels] = await Promise.all([stills['branch-nature-plain'], stills['branch-nature-blend']].map(png => sharp(png).ensureAlpha().raw().toBuffer()));+const BLOCK = 30;+const blockColumns = WIDTH / BLOCK;+const blockRows = HEIGHT / BLOCK;+const changedInBlock = new Array(blockColumns * blockRows).fill(0);+for (let y = 0; y < HEIGHT; y++) {+ for (let x = 0; x < WIDTH; x++) {+ const offset = (y * WIDTH + x) * 4;+ if (Math.abs(offPixels[offset] - onPixels[offset]) + Math.abs(offPixels[offset + 1] - onPixels[offset + 1]) + Math.abs(offPixels[offset + 2] - onPixels[offset + 2]) > 6) {+ changedInBlock[Math.floor(y / BLOCK) * blockColumns + Math.floor(x / BLOCK)]++;+ }+ }+}+const cropWidth = 480;+const cropHeight = 270;+let bestCount = -1;+let cropLeft = 0;+let cropTop = 0;+for (let row = 0; row <= blockRows - cropHeight / BLOCK; row++) {+ for (let column = 0; column <= blockColumns - cropWidth / BLOCK; column++) {+ let count = 0;+ for (let rowOffset = 0; rowOffset < cropHeight / BLOCK; rowOffset++) {+ for (let columnOffset = 0; columnOffset < cropWidth / BLOCK; columnOffset++) count += changedInBlock[(row + rowOffset) * blockColumns + column + columnOffset];+ }+ if (count > bestCount) {+ bestCount = count;+ cropLeft = column * BLOCK;+ cropTop = row * BLOCK;+ }+ }+}+console.log();+const label = (text, width) => Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="44"><rect width="100%" height="100%" fill="#14161a"/><text x="14" y="30" font-family="Arial" font-size="24" fill="#f2f2f2">${text}</text></svg>`);+const half = 960;+const halfHeight = 540;+async function column(png, title, ratioWidth, ratioHeight, crop) {+ let image = sharp(png);+ if (crop) image = image.extract({ left: cropLeft, top: cropTop, width: cropWidth, height: cropHeight });+ return image.resize(ratioWidth, ratioHeight, { kernel: crop ? 'nearest' : 'lanczos3' }).composite([]).toBuffer().then(buffer => ({ buffer, title }));+}+const tiles = await Promise.all([+ column(stills['branch-nature-plain'], 'Before (no blend)', half, halfHeight, false),+ column(stills['branch-nature-blend'], 'After (blend radius 0.18 m)', half, halfHeight, false),+ column(stills['branch-nature-plain'], 'Before, 2x crop of a seam', half, halfHeight, true),+ column(stills['branch-nature-blend'], 'After, 2x crop of the same seam', half, halfHeight, true),+]);+const composites = [];+tiles.forEach((tile, index) => {+ const left = (index % 2) * half;+ const top = Math.floor(index / 2) * (halfHeight + 44);+ composites.push({ input: label(tile.title, half), left, top }, { input: tile.buffer, left, top: top + 44 });+});+await sharp({ create: { width: half * 2, height: (halfHeight + 44) * 2, channels: 3, background: '#14161a' } }).composite(composites).png().toFile(`${output}/478-sheet.png`);+console.log(`sheet: ${resolve(output, '478-sheet.png')}`);++if (!argumentsGiven.includes('--skip-cost')) {+ const times = { off: [], on: [] };+ await withPage(resolve('.'), async page => {+ for (let round = 0; round < rounds; round++) {+ for (const [label2, mode] of round % 2 ? [['off', 'installed'], ['on', 'blend']] : [['on', 'blend'], ['off', 'installed']]) {+ await page.evaluate(options => window.setupScene(options), { scene: 'nature', mode });+ times[label2].push(...await page.evaluate(count => window.measureFrames(count), frames));+ await page.evaluate(() => window.teardown());+ }+ }+ });+ const middle = values => [...values].sort((first, second) => first - second)[Math.floor(values.length / 2)];+ const off = middle(times.off);+ const on = middle(times.on);+ console.log(`1080p frame, ${rounds} rounds x ${frames} frames pooled: off ${off.toFixed(3)} ms, on ${on.toFixed(3)} ms, cost ${(on - off).toFixed(3)} ms`);+}diff --git a/changes/478.md b/changes/478.mdnew file mode 100644index 00000000..4e9e84db--- /dev/null+++ b/changes/478.md@@ -0,0 +1 @@+- Add mesh blend (`67js/addons/mesh-blend`, issue #478), a screen-space pass that softens the seam where one mesh cuts into another (a rock sunk into terrain, a trunk into the ground). A part opts in with `blend: { radius }` in metres, as a part option in code or a `blend` field on a recipe node (MCP `set-node` takes it too). The pass finds seams from the object ID render pass (part change), the frame depth (a depth match, so silhouettes against the sky are skipped) and a normal discontinuity rebuilt from the depth, then mixes the other part's colour over the radius. It adds nothing to the core entry and is off unless a part has `blend`: frames of scenes without it are pixel-identical to main (max difference 0 on a lit box and on a nature terrain). It costs one extra object ID draw plus a fullscreen pass; `docs/mesh-blend.md` has the numbers and limits, and `bench/reference/mesh-blend.mjs` renders the before and after still.diff --git a/changes/478.size.md b/changes/478.size.mdnew file mode 100644index 00000000..ce0b4c9c--- /dev/null+++ b/changes/478.size.md@@ -0,0 +1,2 @@+- entry:mesh-blend: a new lazy addon, 3,494 bytes gzip (the pass shader, the radius table and the option check); entry:core, scene:lit-box and scene:gltf-box grow 0 B, scene:agent-scene grows 3 B (the `blend` node field name)+- result:scene_capabilities: one 100-byte line that tells an agent the `blend` node field exists and where its doc isdiff --git a/docs/mesh-blend.md b/docs/mesh-blend.mdnew file mode 100644index 00000000..f565d171--- /dev/null+++ b/docs/mesh-blend.md@@ -0,0 +1,35 @@+# Mesh blend++Where a rock sinks into terrain or a trunk into the ground, the two meshes meet in a hard, straight seam. Mesh blend is a screen-space pass (the idea of the MeshBlend plugin for Unreal) that mixes the colour of the surface a part cuts into over a short distance. A part opts in with `blend: { radius }`, the distance in metres:++```json+{ "id": "rock-1", "geometry": "rock", "material": "stone", "blend": { "radius": 0.15 } }+```++Mark the rocks, trunks and roots, and the terrain too if you want its colour to take on the rock's. A node without `blend` draws as before: a scene with no `blend` part renders the same pixels as one without the addon, and loads none of it. `set-node` takes `blend` like any node field.++## How it works++For each pixel of a blend part, the pass looks at 24 taps on a spiral within `radius` (converted to pixels at that distance, 1 to 40 pixels). A tap counts when it shows another part (an object ID differs), its surface point lies within three radii of this pixel (a depth match: a silhouette against the sky or a far wall never counts), and the two surfaces are not parallel (a normal discontinuity, rebuilt from the depth). The share of taps that count, weighted toward the pixel, sets how much of the other part's colour mixes in. It does not blend across a part's own edges.++## Cost and limits++- One extra draw of the opaque geometry in the object ID mode (the render passes addon draws it), and one fullscreen pass that returns at once for every pixel outside a blend part. Measured on an RTX 3060 at 1080p with 4x MSAA, on a terrain with five sunk rocks and a trunk (median of 6 rounds of 150 frames, other sessions sharing the machine): 2.46 ms without blend, 3.42 ms with it, so about 0.97 ms. Most of that is the extra draw, so it grows with the geometry of the scene and the fullscreen pass stays small.+- Needs a renderer with `depth: true` and `installRenderPasses` first, like line art. The MCP preview does both.+- Opaque and cutout parts only. A blended or transmissive surface has no part ID.+- A blend part mixes toward the part on the other side of its seam; the other part changes only if it has `blend` too. Marking both gives the soft seam from both sides.+- A seam under about one pixel wide (a tiny radius far from the camera) is left alone. The path tracer does not run the pass.+- The part ID is the draw order of opaque instances. A part count above 16 million is not supported (the ID has 24 bits).+- In a recipe, a wrong `blend` value (`radius` outside 0.005 to 2, an unknown field) is reported when the preview draws the frame, with the message of the field.++## Code++```js+import { installRenderPasses } from '@codepawlhq/67js/addons/render-passes';+import { installMeshBlend } from '@codepawlhq/67js/addons/mesh-blend';++const renderer = installMeshBlend(installRenderPasses(new Renderer67(canvas, parts, { depth: true, hdr: true })));+// parts: [{ name, geometry, material, matrix, blend: { radius: 0.15 } }, ...]+```++Install it before `installLineArt` so the lines draw over the blended colour. `renderer.meshBlend.radii` is a `Map` from part name to radius for hosts whose parts do not carry the option (the recipe preview fills it from the nodes). `bench/reference/mesh-blend.mjs` renders the before and after still of a terrain with sunk rocks and a trunk, checks the pixels against main and measures the frame.diff --git a/package.json b/package.jsonindex b7d89dbf..94fca111 100644--- a/package.json+++ b/package.json@@ -32,6 +32,7 @@"docs/export-glb.md","docs/gltf.md","docs/line-art.md",+ "docs/mesh-blend.md","docs/guide.md","docs/lighting.md","docs/material-maps.md",@@ -91,6 +92,7 @@"./addons/render-passes": "./build/render-passes.js","./addons/user-pass": "./build/user-pass.js","./addons/line-art": "./build/line-art.js",+ "./addons/mesh-blend": "./build/mesh-blend.js","./addons/coplanar-overlap": "./build/coplanar-overlap.js","./addons/reversed-depth": "./build/reversed-depth.js","./addons/material-layer-shaders": "./build/material-layer-shaders.js",diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex ed29d94e..72037c4b 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -5,6 +5,7 @@ import { skyOpenness } from '../src/closed-room.js';import { fogSkyVisibility } from '../src/fog-sky-visibility.js';import { installCameraEffects } from '../src/camera-effects.js';import { installRenderPasses } from '../src/render-passes.js';+import { installMeshBlend, normalizeBlend } from '../src/mesh-blend.js';import { installDepthPrecision } from '../src/reversed-depth.js';import { applyProjection } from '../src/camera.js';import { mat4 } from 'gl-matrix';@@ -243,6 +244,7 @@ function draw(record, time = 0, camera = record.scene.camera, frameOptions = {})record.shadowKey = shadowKey;}record.renderer.world = environment.world;+ syncMeshBlend(record);record.renderer.userPasses?.set(record.scene.postPasses ?? []);applyRecipeWindHeading(record.renderer, environment);record.renderer.render({ ...camera, environment: litEnvironment(record.scene.parts, environment, Boolean(record.renderer.groundPart)), effects, exposure: effects.exposure, time, lines: environment.lines, ...windFrame(environment), ...frameOptions });@@ -252,6 +254,19 @@ function draw(record, time = 0, camera = record.scene.camera, frameOptions = {})}}+// The radius of each node's `blend`, by part name. Checked again only when the scene revision changes; a bad value throws here+// with the field's message, which the render reports.+function syncMeshBlend(record) {+ if (record.blendRevision === record.scene.revision && record.blendRenderer === record.renderer) return;+ record.blendRevision = record.scene.revision;+ record.blendRenderer = record.renderer;+ const radii = new Map();+ for (const node of record.scene.exportRecipe().nodes ?? []) {+ if (node.blend !== undefined) radii.set(node.id, normalizeBlend(node.blend).radius);+ }+ record.renderer.meshBlend.radii = radii;+}+function status(record) {const render = renderInfo(record.renderer);record.lastRender = render;@@ -340,7 +355,9 @@ function initializeRenderer(scene, { memoryBudgetMiB, backend }) {memoryBudgetMiB,}))));// Outlines, toon light and polylines draw only for a frame that carries environment.lines; user passes run last, on the finished frame.- return agentSceneModule('userPass').installUserPasses(agentSceneModule('lineArt').installLineArt(renderer));+ // Mesh blend installs before line art, so its stage runs first and the lines draw over the blended colour; it blends only the+ // parts whose nodes carry `blend` (syncMeshBlend), so a recipe without it draws as before.+ return agentSceneModule('userPass').installUserPasses(agentSceneModule('lineArt').installLineArt(installMeshBlend(renderer)));}// Camera fields from a timeline shot on top of the sampled camera, checked with the scene's own camera rules.diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex c5e5664b..2438e5c6 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -9,6 +9,7 @@ import packageMetadata from '../package.json' with { type: 'json' };import { VEGETATION_CAPABILITY_NOTE } from '../src/agent-vegetation-notes.js';import { CROWD_CAPABILITY_NOTE } from '../src/agent-crowd-notes.js';import { USER_PASS_CAPABILITIES } from '../src/user-pass.js';+import { MESH_BLEND_CAPABILITIES } from '../src/mesh-blend.js';import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';@@ -576,7 +577,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browreturn Object.freeze({async capabilities() {return {- scene: { ...AGENT_SCENE_CAPABILITIES, postPasses: USER_PASS_CAPABILITIES, materialSnippet: MATERIAL_SNIPPET_CAPABILITIES, vegetation: VEGETATION_CAPABILITY_NOTE, crowd: CROWD_CAPABILITY_NOTE, textureSequence: TEXTURE_SEQUENCE_CAPABILITIES },+ scene: { ...AGENT_SCENE_CAPABILITIES, postPasses: USER_PASS_CAPABILITIES, meshBlend: MESH_BLEND_CAPABILITIES, materialSnippet: MATERIAL_SNIPPET_CAPABILITIES, vegetation: VEGETATION_CAPABILITY_NOTE, crowd: CROWD_CAPABILITY_NOTE, textureSequence: TEXTURE_SEQUENCE_CAPABILITIES },sceneLimits: SCENE_LIMITS,preview: { backend, memoryBudgetMiB: memory, maximumWidth: 1024, maximumHeight: 1024, maximumImageBytes: MAXIMUM_IMAGE_BYTES, maximumActiveScenes: 1, maximumQueuedCalls: MAXIMUM_QUEUED_CALLS, evaluationTimeoutMs: EVALUATION_TIMEOUT_MS },review: { ...REVIEW_LIMITS, backend, memoryBudgetMiB: memory, evaluationTimeoutMs: EVALUATION_TIMEOUT_MS,diff --git a/scripts/measure-tool-cost.mjs b/scripts/measure-tool-cost.mjsindex 2572e254..0334ac7e 100644--- a/scripts/measure-tool-cost.mjs+++ b/scripts/measure-tool-cost.mjs@@ -6,6 +6,7 @@ import { createAgentMcpServer } from './mcp-server.mjs';import { VEGETATION_CAPABILITY_NOTE } from '../src/agent-vegetation-notes.js';import { CROWD_CAPABILITY_NOTE } from '../src/agent-crowd-notes.js';import { USER_PASS_CAPABILITIES } from '../src/user-pass.js';+import { MESH_BLEND_CAPABILITIES } from '../src/mesh-blend.js';import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';import { createAgentScene, AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';import { TEXTURE_SEQUENCE_CAPABILITIES } from '../src/texture-sequence-limits.js';@@ -73,7 +74,7 @@ async function typicalResults(recipe) {const meshReport = scene.inspectMeshes({ geometries: ['seat'] });const { inspection, ...statusWithoutInspection } = status;return {- scene_capabilities: { ...AGENT_SCENE_CAPABILITIES, postPasses: USER_PASS_CAPABILITIES, materialSnippet: MATERIAL_SNIPPET_CAPABILITIES, vegetation: VEGETATION_CAPABILITY_NOTE, crowd: CROWD_CAPABILITY_NOTE, textureSequence: TEXTURE_SEQUENCE_CAPABILITIES },+ scene_capabilities: { ...AGENT_SCENE_CAPABILITIES, postPasses: USER_PASS_CAPABILITIES, meshBlend: MESH_BLEND_CAPABILITIES, materialSnippet: MATERIAL_SNIPPET_CAPABILITIES, vegetation: VEGETATION_CAPABILITY_NOTE, crowd: CROWD_CAPABILITY_NOTE, textureSequence: TEXTURE_SEQUENCE_CAPABILITIES },scene_create: status,scene_inspect: { sessionId: SAMPLE_SESSION, ...scene.inspect() },mesh_inspect: { sessionId: SAMPLE_SESSION, ...meshReport },diff --git a/src/agent-scene.js b/src/agent-scene.jsindex baf92c59..736cf89b 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -23,7 +23,7 @@ const MAX_MESH_REPORTS = 16;// Terrain meshes carry one more float for each vertex (sky visibility) than the 56 bytes the budget estimates.const TERRAIN_SKY_VISIBILITY_BYTES = 4;const CAMERA_DEFAULTS = Object.freeze({ eye: [4, 3, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 45, near: 0.1, far: 1000 });-const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer'];+const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer', 'blend'];const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'snippet', 'waterPreset', 'absorption', 'turbidity', ...MATERIAL_LAYER_FIELDS];const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'boxMapScale', 'boxMapAxis'];const CAMERA_FIELDS = Object.keys(CAMERA_DEFAULTS);diff --git a/src/mesh-blend.js b/src/mesh-blend.jsnew file mode 100644index 00000000..0a898204--- /dev/null+++ b/src/mesh-blend.js@@ -0,0 +1,287 @@+// Mesh blend: a screen-space pass that softens the seam where one mesh cuts into another (a rock sunk into terrain, a trunk+// into the ground). A part opts in with `blend: { radius }`, the distance in metres over which its colour mixes with the+// colour of the surface it meets. Nothing here is in the core renderer: installMeshBlend adds a post stage and wraps+// render, and a frame with no `blend` part runs untouched, so a scene without it draws the same pixels.+//+// A pixel of a blend part looks at taps on a spiral within `radius` (in screen pixels at its distance) and counts the taps+// that show another part. A tap counts only when its surface point lies within a short reach of this pixel (a depth match:+// a silhouette against the sky or a far wall is skipped) and the surfaces do not run parallel (a normal discontinuity,+// rebuilt from the depth). The part IDs come from the object ID render pass, drawn just before the frame; the depth is the+// depth texture of the frame, so the renderer needs `depth: true`, as line art does. Cost: one extra draw of the opaque+// geometry in the ID mode, plus a fullscreen pass that exits early for every pixel outside a blend part.++export const MESH_BLEND_LIMITS = Object.freeze({ radius: Object.freeze([0.005, 2]) });+export const MESH_BLEND_TAPS = Object.freeze({ count: 24, angleStep: 2.39996323 });+const TAP_COUNT = MESH_BLEND_TAPS.count;+const MAXIMUM_PIXEL_RADIUS = 40;+const TABLE_WIDTH = 1024;++// gl-program.js is not imported on purpose: this module loads on demand (see line-art.js).+const fullscreenVertex = `#version 300 es+precision highp float;+void main() {+ vec2 position = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));+ gl_Position = vec4(position * 2.0 - 1.0, 0.0, 1.0);+}`;++/** Checks a part's `blend` option and returns it normalized: { radius } in metres. */+export function normalizeBlend(input) {+ if (input === null || typeof input !== 'object' || Array.isArray(input)) {+ throw new TypeError('blend must be an object such as { "radius": 0.15 }.');+ }+ for (const key of Object.keys(input)) {+ if (key !== 'radius') throw new RangeError(`blend has no field ${key}. Fix: use { "radius": metres }.`);+ }+ const [minimum, maximum] = MESH_BLEND_LIMITS.radius;+ if (typeof input.radius !== 'number' || !(input.radius >= minimum && input.radius <= maximum)) {+ throw new RangeError(`blend.radius must be a number of metres between ${minimum} and ${maximum}.`);+ }+ return { radius: input.radius };+}++/**+ * The radius each object ID mixes over, indexed by ID (slot 0 is the background): the parts the ID pass numbers in order.+ * A part's own `blend` wins; `radii` maps a part name to a radius for hosts whose parts do not carry the option (a recipe's nodes).+ */+export function blendRadiusTable(parts, radii = new Map()) {+ const table = new Float32Array(parts.length + 1);+ parts.forEach((part, index) => {+ table[index + 1] = part.blend?.radius ?? radii.get(part.name) ?? 0;+ });+ return table;+}++// What scene_capabilities reports: one line, since every byte there is paid on each call. The limits are in the docs.+export const MESH_BLEND_CAPABILITIES = 'nodes[].blend {radius: metres 0.005-2} softens seams; needs depth; docs/mesh-blend.md';++export const blendFragment = `#version 300 es+precision highp float;+uniform sampler2D sourceTexture;+uniform sampler2D sceneDepth;+uniform sampler2D partTexture;+uniform sampler2D radiusTexture;+uniform mat4 inverseViewProjection;+uniform vec3 eye;+uniform float pixelsPerMetre;+uniform float orthographic;+out vec4 outputColor;+ivec2 lastPixel;+int partAt(ivec2 pixel) {+ ivec3 bytes = ivec3(texelFetch(partTexture, clamp(pixel, ivec2(0), lastPixel), 0).rgb * 255.0 + 0.5);+ return bytes.x + bytes.y * 256 + bytes.z * 65536;+}+vec3 positionAt(ivec2 pixel) {+ ivec2 clamped = clamp(pixel, ivec2(0), lastPixel);+ float depth = texelFetch(sceneDepth, clamped, 0).r;+ vec4 ndc = vec4((vec2(clamped) + 0.5) / vec2(lastPixel + 1) * 2.0 - 1.0, depth * 2.0 - 1.0, 1.0);+ vec4 world = inverseViewProjection * ndc;+ return world.xyz / world.w;+}+// The shorter step of the two sides, skipping a zero step (the frame edge clamps a neighbour onto the pixel itself).+vec3 shorterStep(vec3 first, vec3 second) {+ float firstLength = dot(first, first);+ float secondLength = dot(second, second);+ return (secondLength < 1e-14 || (firstLength >= 1e-14 && firstLength < secondLength)) ? first : second;+}+vec3 normalAt(ivec2 pixel, vec3 center) {+ vec3 right = positionAt(pixel + ivec2(1, 0)) - center;+ vec3 left = center - positionAt(pixel - ivec2(1, 0));+ vec3 up = positionAt(pixel + ivec2(0, 1)) - center;+ vec3 down = center - positionAt(pixel - ivec2(0, 1));+ vec3 raw = cross(shorterStep(right, left), shorterStep(up, down));+ vec3 toEye = normalize(eye - center);+ if (dot(raw, raw) < 1e-20) return toEye;+ vec3 normal = normalize(raw);+ return dot(normal, toEye) < 0.0 ? -normal : normal;+}+void main() {+ ivec2 pixel = ivec2(gl_FragCoord.xy);+ lastPixel = textureSize(sourceTexture, 0) - 1;+ vec4 source = texelFetch(sourceTexture, pixel, 0);+ outputColor = source;+ int part = partAt(pixel);+ if (part == 0) return;+ float radius = texelFetch(radiusTexture, ivec2(part & ${TABLE_WIDTH - 1}, part / ${TABLE_WIDTH}), 0).r;+ if (radius <= 0.0) return;+ vec3 center = positionAt(pixel);+ float pixelRadius = radius * pixelsPerMetre / (orthographic > 0.5 ? 1.0 : length(center - eye));+ pixelRadius = clamp(pixelRadius, 1.0, ${MAXIMUM_PIXEL_RADIUS}.0);+ float reach = radius * 3.0;+ vec3 colorSum = vec3(0.0);+ float otherWeight = 0.0;+ float totalWeight = 0.0;+ ivec2 nearestTap = pixel;+ bool found = false;+ for (int index = 0; index < ${TAP_COUNT}; index++) {+ float fraction = sqrt((float(index) + 0.5) / ${TAP_COUNT}.0);+ float angle = float(index) * ${MESH_BLEND_TAPS.angleStep};+ ivec2 tap = pixel + ivec2(round(vec2(cos(angle), sin(angle)) * pixelRadius * fraction));+ float weight = 1.0 - fraction;+ totalWeight += weight;+ int tapPart = partAt(tap);+ if (tapPart == 0 || tapPart == part) continue;+ if (distance(positionAt(tap), center) > reach) continue;+ if (!found) nearestTap = tap;+ found = true;+ colorSum += weight * texelFetch(sourceTexture, clamp(tap, ivec2(0), lastPixel), 0).rgb;+ otherWeight += weight;+ }+ if (!found) return;+ float creased = smoothstep(0.05, 0.4, 1.0 - dot(normalAt(pixel, center), normalAt(nearestTap, positionAt(nearestTap))));+ float amount = smoothstep(0.0, 0.5, otherWeight / totalWeight) * creased;+ outputColor.rgb = mix(source.rgb, colorSum / otherWeight, amount);+}`;++function compileShader(context, kind, source) {+ const shader = context.createShader(kind);+ context.shaderSource(shader, source);+ context.compileShader(shader);+ if (!context.getShaderParameter(shader, context.COMPILE_STATUS)) {+ throw new Error(`Mesh blend shader compilation failed: ${context.getShaderInfoLog(shader)}`);+ }+ return shader;+}++function compileProgram(context, vertexSource, fragmentSource) {+ const program = context.createProgram();+ context.attachShader(program, compileShader(context, context.VERTEX_SHADER, vertexSource));+ context.attachShader(program, compileShader(context, context.FRAGMENT_SHADER, fragmentSource));+ context.linkProgram(program);+ if (!context.getProgramParameter(program, context.LINK_STATUS)) {+ throw new Error(`Mesh blend shader linking failed: ${context.getProgramInfoLog(program)}`);+ }+ return program;+}++function createColorTarget(context, width, height, floatColor, filter) {+ const texture = context.createTexture();+ context.bindTexture(context.TEXTURE_2D, texture);+ context.texImage2D(context.TEXTURE_2D, 0, floatColor ? context.RGBA16F : context.RGBA8, width, height, 0, context.RGBA,+ floatColor ? context.HALF_FLOAT : context.UNSIGNED_BYTE, null);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, filter);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, filter);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);+ const framebuffer = context.createFramebuffer();+ context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);+ context.framebufferTexture2D(context.FRAMEBUFFER, context.COLOR_ATTACHMENT0, context.TEXTURE_2D, texture, 0);+ if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) {+ throw new Error('Mesh blend framebuffer allocation failed. Choose a lower quality preset.');+ }+ return { texture, framebuffer };+}++function sameTable(first, second) {+ return first?.length === second.length && first.every((value, index) => value === second[index]);+}++/**+ * Adds the seam blend to a renderer. The renderer needs `depth: true` and installRenderPasses first. A part opts in with+ * `blend: { radius }`; a frame whose parts have none draws exactly as before.+ */+export function installMeshBlend(renderer) {+ if (renderer.meshBlend) return renderer;+ if (!renderer.passSupport) throw new Error('Mesh blend needs installRenderPasses(renderer) from 67js/addons/render-passes first.');+ const state = { active: false, table: null };+ let program = null;+ let uniforms = null;+ let partTarget = null;+ let outputTarget = null;+ let radiusTexture = null;++ function opaqueParts() {+ return renderer.batches.filter(batch => renderer.drawsInOpaqueLoop(batch)).flatMap(batch => batch.parts);+ }++ function uploadTable(table) {+ const { context } = renderer;+ if (sameTable(state.table, table)) return;+ state.table = table;+ const rows = Math.ceil(table.length / TABLE_WIDTH);+ const padded = new Float32Array(rows * TABLE_WIDTH);+ padded.set(table);+ radiusTexture ??= context.createTexture();+ context.bindTexture(context.TEXTURE_2D, radiusTexture);+ context.texImage2D(context.TEXTURE_2D, 0, context.R32F, TABLE_WIDTH, rows, 0, context.RED, context.FLOAT, padded);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.NEAREST);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.NEAREST);+ }++ function captureParts() {+ const { context, canvas } = renderer;+ partTarget ??= createColorTarget(context, canvas.width, canvas.height, false, context.NEAREST);+ context.bindFramebuffer(context.READ_FRAMEBUFFER, renderer.passSupport.framebuffer);+ context.bindFramebuffer(context.DRAW_FRAMEBUFFER, partTarget.framebuffer);+ context.blitFramebuffer(0, 0, canvas.width, canvas.height, 0, 0, canvas.width, canvas.height, context.COLOR_BUFFER_BIT, context.NEAREST);+ }++ function apply(rendererInUse, frame, effects, sourceTexture) {+ if (!state.active) return null;+ if (!renderer.depthTexture) throw new Error('Mesh blend requires depth:true on the renderer.');+ const { context, canvas } = renderer;+ if (!program) {+ program = compileProgram(context, fullscreenVertex, blendFragment);+ uniforms = Object.fromEntries(['sourceTexture', 'sceneDepth', 'partTexture', 'radiusTexture', 'inverseViewProjection', 'eye', 'pixelsPerMetre', 'orthographic']+ .map(name => [name, context.getUniformLocation(program, name)]));+ }+ outputTarget ??= createColorTarget(context, canvas.width, canvas.height, renderer.hdr, context.LINEAR);+ context.bindFramebuffer(context.FRAMEBUFFER, outputTarget.framebuffer);+ context.viewport(0, 0, canvas.width, canvas.height);+ context.disable(context.DEPTH_TEST);+ context.disable(context.CULL_FACE);+ context.bindVertexArray(null);+ context.useProgram(program);+ [[sourceTexture, 'sourceTexture'], [renderer.depthTexture, 'sceneDepth'], [partTarget.texture, 'partTexture'], [radiusTexture, 'radiusTexture']].forEach(([texture, name], unit) => {+ context.activeTexture(context.TEXTURE0 + unit);+ context.bindTexture(context.TEXTURE_2D, texture);+ context.uniform1i(uniforms[name], unit);+ });+ context.uniformMatrix4fv(uniforms.inverseViewProjection, false, renderer.inverseViewProjection);+ context.uniform3fv(uniforms.eye, frame.eye);+ context.uniform1f(uniforms.pixelsPerMetre, renderer.projection[5] * canvas.height / 2);+ context.uniform1f(uniforms.orthographic, renderer.projection[15] === 1 ? 1 : 0);+ context.drawArrays(context.TRIANGLES, 0, 3);+ return outputTarget.texture;+ }++ function releaseTargets(context) {+ for (const target of [partTarget, outputTarget]) {+ if (!target) continue;+ context.deleteTexture(target.texture);+ context.deleteFramebuffer(target.framebuffer);+ }+ partTarget = null;+ outputTarget = null;+ }++ function dispose(context) {+ releaseTargets(context);+ if (program) context.deleteProgram(program);+ if (radiusTexture) context.deleteTexture(radiusTexture);+ program = null;+ radiusTexture = null;+ state.table = null;+ }++ renderer.postStages.push({ name: 'Mesh blend', apply, releaseTargets, dispose });+ const drawFrame = renderer.render.bind(renderer);+ renderer.render = frame => {+ state.active = false;+ if (frame.pass === undefined && !frame.reflectionTarget && !renderer.benchmark) {+ const table = blendRadiusTable(opaqueParts(), renderer.meshBlend.radii);+ if (table.some(radius => radius > 0)) {+ uploadTable(table);+ drawFrame({ ...frame, pass: 'objectId' });+ captureParts();+ state.active = true;+ }+ }+ try {+ drawFrame(frame);+ } finally {+ state.active = false;+ }+ };+ renderer.meshBlend = { limits: MESH_BLEND_LIMITS, radii: new Map() };+ return renderer;+}diff --git a/tests/agent-runtime.test.js b/tests/agent-runtime.test.jsindex ba3d7ef3..2a56d8c0 100644--- a/tests/agent-runtime.test.js+++ b/tests/agent-runtime.test.js@@ -9,6 +9,7 @@ import { createContext, Script } from 'node:vm';import { VEGETATION_CAPABILITY_NOTE } from '../src/agent-vegetation-notes.js';import { CROWD_CAPABILITY_NOTE } from '../src/agent-crowd-notes.js';import { USER_PASS_CAPABILITIES } from '../src/user-pass.js';+import { MESH_BLEND_CAPABILITIES } from '../src/mesh-blend.js';import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';import { recipeAssetNeeds } from '../src/agent-scene-assets.js';@@ -108,7 +109,7 @@ async function reviewRuntimeHarness({ failShot, blockShot = false, oversize = faconst context = createContext({ createServer, randomUUID, existsSync: () => true,readFile: async () => '', packageMetadata: { version: 'test' },createRequire: () => ({ resolve: () => { throw new Error('no peer in tests'); } }),- VEGETATION_CAPABILITY_NOTE, CROWD_CAPABILITY_NOTE, USER_PASS_CAPABILITIES, MATERIAL_SNIPPET_CAPABILITIES, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS, PATH_TRACER_CAPABILITIES,+ VEGETATION_CAPABILITY_NOTE, CROWD_CAPABILITY_NOTE, USER_PASS_CAPABILITIES, MESH_BLEND_CAPABILITIES, MATERIAL_SNIPPET_CAPABILITIES, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS, PATH_TRACER_CAPABILITIES,recipeAssetNeeds, sequenceFrameIds, TEXTURE_SEQUENCE_CAPABILITIES,audioInputArguments, createAudioLibrary, measureStreamSeconds, filmTimelineDuration, filmTimelineShotStarts, sampleFilmTimeline, normalizeReview, REVIEW_LIMITS, isPreviewHost, BRANCH_LIMITS, validateBranchName,chromium: { launch: async () => browser }, URL, Buffer, process, performance, clearTimeout,diff --git a/tests/mesh-blend.test.js b/tests/mesh-blend.test.jsnew file mode 100644index 00000000..35c1c1b4--- /dev/null+++ b/tests/mesh-blend.test.js@@ -0,0 +1,201 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { readFileSync } from 'node:fs';+import { normalizeBlend, blendRadiusTable, installMeshBlend, blendFragment, MESH_BLEND_TAPS, MESH_BLEND_CAPABILITIES } from '../src/mesh-blend.js';+import { createAgentScene } from '../src/agent-scene.js';+import { blendReference } from './support/mesh-blend-reference.js';++const WIDTH = 64;+const HEIGHT = 16;+const GREEN = [0, 1, 0];+const RED = [1, 0, 0];+const ORTHOGRAPHIC = { eye: [0, 0, 100], pixelsPerMetre: 20, orthographic: true };++// A ground plane facing the viewer on the left and a rock face at 45 degrees on the right; they meet at column 32.+// The pixel pitch is 0.05 m, so a radius of 0.2 m reaches 4 pixels. `rockDepth` and `rockId` change the right half.+function syntheticBuffers({ rockId = 2, rockSlope = 1, rockOffset = 0, rockIds } = {}) {+ const ids = new Int32Array(WIDTH * HEIGHT);+ const positions = new Float32Array(WIDTH * HEIGHT * 3);+ const colors = new Float32Array(WIDTH * HEIGHT * 3);+ for (let y = 0; y < HEIGHT; y++) {+ for (let x = 0; x < WIDTH; x++) {+ const index = y * WIDTH + x;+ const onRock = x >= 32;+ ids[index] = onRock ? (rockIds ? rockIds(x) : rockId) : 1;+ const depth = onRock ? (x - 32) * 0.05 * rockSlope + rockOffset : 0;+ positions.set([x * 0.05, y * 0.05, depth], index * 3);+ colors.set(onRock ? RED : GREEN, index * 3);+ }+ }+ return { width: WIDTH, height: HEIGHT, ids, positions, colors };+}++const colorAt = (colors, x, y = 8) => Array.from(colors.subarray((y * WIDTH + x) * 3, (y * WIDTH + x) * 3 + 3));++test('a blend part mixes toward the part it cuts into, fading out over its radius', () => {+ const buffers = syntheticBuffers();+ const result = blendReference(buffers, { ...ORTHOGRAPHIC, radii: new Map([[2, 0.2]]) });+ const atSeam = colorAt(result, 33);+ const farther = colorAt(result, 34);+ assert.ok(atSeam[1] > 0.25 && atSeam[0] < 0.75, `next to the seam the rock should take on the ground colour, got ${atSeam}`);+ assert.ok(farther[1] > 0 && farther[1] < atSeam[1], 'the mix falls off with distance');+ assert.deepEqual(colorAt(result, 40), RED, 'beyond the radius the rock keeps its colour');+ assert.deepEqual(colorAt(result, 10), GREEN, 'the ground part has no blend and is untouched');+});++test('a larger radius reaches further from the seam', () => {+ const small = blendReference(syntheticBuffers(), { ...ORTHOGRAPHIC, radii: new Map([[2, 0.1]]) });+ const large = blendReference(syntheticBuffers(), { ...ORTHOGRAPHIC, radii: new Map([[2, 0.3]]) });+ assert.deepEqual(colorAt(small, 36), RED);+ assert.ok(colorAt(large, 36)[1] > 0, 'the 0.3 m radius still touches 6 pixels out');+});++test('a part without a radius is left alone even when another part touches it', () => {+ const buffers = syntheticBuffers();+ const result = blendReference(buffers, { ...ORTHOGRAPHIC, radii: new Map() });+ assert.deepEqual(Array.from(result), Array.from(buffers.colors));+});++test('a depth jump is a silhouette, not a seam: a rock in front of a far wall is not blended', () => {+ const buffers = syntheticBuffers({ rockOffset: 5 });+ const result = blendReference(buffers, { ...ORTHOGRAPHIC, radii: new Map([[2, 0.2]]) });+ assert.deepEqual(colorAt(result, 32), RED);+ assert.deepEqual(colorAt(result, 33), RED);+});++test('two parts on one plane have no normal discontinuity, so nothing blends', () => {+ const buffers = syntheticBuffers({ rockSlope: 0 });+ const result = blendReference(buffers, { ...ORTHOGRAPHIC, radii: new Map([[2, 0.2]]) });+ assert.deepEqual(Array.from(result), Array.from(buffers.colors));+});++test('pixels of one part, and the background (ID 0), never blend with themselves or the sky', () => {+ const sameId = syntheticBuffers({ rockId: 1 });+ assert.deepEqual(Array.from(blendReference(sameId, { ...ORTHOGRAPHIC, radii: new Map([[1, 0.2]]) })), Array.from(sameId.colors));+ const sky = syntheticBuffers({ rockId: 0 });+ assert.deepEqual(Array.from(blendReference(sky, { ...ORTHOGRAPHIC, radii: new Map([[1, 0.2]]) })), Array.from(sky.colors));+});++test('the reference and the shader use the same tap pattern', () => {+ assert.ok(blendFragment.includes(`< ${MESH_BLEND_TAPS.count}; index++`));+ assert.ok(blendFragment.includes(`float(index) * ${MESH_BLEND_TAPS.angleStep}`));+ assert.ok(blendFragment.includes('smoothstep(0.05, 0.4, 1.0 - dot('));+});++test('blend is checked: a radius in metres and nothing else', () => {+ assert.deepEqual(normalizeBlend({ radius: 0.15 }), { radius: 0.15 });+ assert.throws(() => normalizeBlend({ radius: 0 }), /between 0\.005 and 2/);+ assert.throws(() => normalizeBlend({ radius: 5 }), /between 0\.005 and 2/);+ assert.throws(() => normalizeBlend({ radius: '0.1' }), /number of metres/);+ assert.throws(() => normalizeBlend({ radius: 0.1, softness: 1 }), /no field softness/);+ assert.throws(() => normalizeBlend(0.1), /must be an object/);+});++test('the radius table follows the part order, with a radius map for parts that carry none', () => {+ const parts = [{ name: 'ground' }, { name: 'rock', blend: { radius: 0.2 } }, { name: 'root' }];+ assert.deepEqual(Array.from(blendRadiusTable(parts)), [0, 0, Math.fround(0.2), 0]);+ assert.deepEqual(Array.from(blendRadiusTable(parts, new Map([['root', 0.5], ['rock', 0.9]]))), [0, 0, Math.fround(0.2), Math.fround(0.5)]);+});++// A fake WebGL context: constants are stable numbers, calls return empty objects, and shader and framebuffer checks pass.+function fakeContext() {+ const calls = [];+ const constant = name => [...name].reduce((sum, character) => (sum * 31 + character.charCodeAt(0)) % 100000, 7);+ return new Proxy({}, {+ get(target, name) {+ if (typeof name !== 'string') return undefined;+ if (/^[A-Z][A-Z0-9_]*$/.test(name)) return constant(name);+ if (name === 'checkFramebufferStatus') return () => constant('FRAMEBUFFER_COMPLETE');+ if (name === 'getShaderParameter' || name === 'getProgramParameter') return () => true;+ return (...argumentsGiven) => {+ calls.push(name);+ return {};+ };+ },+ calls,+ });+}++function fakeRenderer(parts) {+ const drawn = [];+ const renderer = {+ context: fakeContext(),+ canvas: { width: 8, height: 8 },+ benchmark: false,+ hdr: true,+ depthTexture: {},+ projection: new Float32Array(16),+ inverseViewProjection: new Float32Array(16),+ postStages: [],+ passSupport: { framebuffer: {} },+ batches: [{ parts }],+ drawsInOpaqueLoop: () => true,+ render: frame => drawn.push(frame),+ };+ return { renderer, drawn };+}++test('installing needs the render passes addon', () => {+ const { renderer } = fakeRenderer([]);+ renderer.passSupport = null;+ assert.throws(() => installMeshBlend(renderer), /installRenderPasses/);+});++test('with no blend part a frame is drawn once, as given, and the stage does nothing', () => {+ const { renderer, drawn } = fakeRenderer([{ name: 'ground' }, { name: 'rock' }]);+ installMeshBlend(renderer);+ const frame = { eye: [0, 0, 5] };+ renderer.render(frame);+ assert.equal(drawn.length, 1);+ assert.equal(drawn[0], frame, 'the very same frame object reaches the renderer');+ assert.equal(renderer.postStages[0].apply(renderer, frame, {}, {}), null);+});++test('a blend part adds one object ID draw before the frame, and the stage runs only for that frame', () => {+ const { renderer, drawn } = fakeRenderer([{ name: 'ground' }, { name: 'rock', blend: { radius: 0.2 } }]);+ installMeshBlend(renderer);+ const frame = { eye: [0, 0, 5] };+ renderer.render(frame);+ assert.equal(drawn.length, 2);+ assert.equal(drawn[0].pass, 'objectId');+ assert.equal(drawn[1], frame);+ assert.equal(renderer.postStages[0].apply(renderer, frame, {}, {}), null, 'the stage is off again after the frame');+});++test('a radius from the radii map opts a part in like its own blend field', () => {+ const { renderer, drawn } = fakeRenderer([{ name: 'ground' }, { name: 'rock' }]);+ installMeshBlend(renderer);+ renderer.meshBlend.radii = new Map([['rock', 0.2]]);+ renderer.render({ eye: [0, 0, 5] });+ assert.equal(drawn.length, 2);+});++test('passes, mirrors and benchmark frames are never blended', () => {+ const { renderer, drawn } = fakeRenderer([{ name: 'rock', blend: { radius: 0.2 } }]);+ installMeshBlend(renderer);+ renderer.render({ eye: [0, 0, 5], pass: 'normal' });+ renderer.render({ eye: [0, 0, 5], reflectionTarget: {} });+ renderer.benchmark = true;+ renderer.render({ eye: [0, 0, 5] });+ assert.equal(drawn.length, 3);+});++test('a recipe node takes blend and keeps it through export and set-node', () => {+ const recipe = {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box' }],+ materials: [{ id: 'gray', color: [0.5, 0.5, 0.5] }],+ nodes: [{ id: 'rock', geometry: 'box', material: 'gray', blend: { radius: 0.15 } }, { id: 'ground', geometry: 'box', material: 'gray' }],+ };+ const scene = createAgentScene(recipe);+ assert.deepEqual(scene.exportRecipe().nodes[0].blend, { radius: 0.15 });+ assert.equal(scene.exportRecipe().nodes[1].blend, undefined);+ scene.apply([{ type: 'set-node', id: 'ground', blend: { radius: 0.3 } }], { expectedRevision: 0 });+ assert.deepEqual(scene.exportRecipe().nodes[1].blend, { radius: 0.3 });+});++test('the docs and the capability note describe the same option', () => {+ const documentation = readFileSync(new URL('../docs/mesh-blend.md', import.meta.url), 'utf8');+ assert.ok(documentation.includes('blend: { radius }') || documentation.includes('"blend": { "radius"'));+ assert.match(MESH_BLEND_CAPABILITIES, /blend \{radius.*docs\/mesh-blend\.md/);+});diff --git a/tests/support/mesh-blend-reference.js b/tests/support/mesh-blend-reference.jsnew file mode 100644index 00000000..ad6e8860--- /dev/null+++ b/tests/support/mesh-blend-reference.js@@ -0,0 +1,91 @@+// A CPU port of the fragment shader in src/mesh-blend.js, for tests on synthetic buffers. It reads the same inputs (part IDs,+// world positions rebuilt from depth, source colour) and follows the shader line by line, with the same tap pattern.+import { MESH_BLEND_TAPS } from '../../src/mesh-blend.js';++const MAXIMUM_PIXEL_RADIUS = 40;++function smoothstep(low, high, value) {+ const fraction = Math.min(1, Math.max(0, (value - low) / (high - low)));+ return fraction * fraction * (3 - 2 * fraction);+}++function subtract(first, second) {+ return [first[0] - second[0], first[1] - second[1], first[2] - second[2]];+}++function dot(first, second) {+ return first[0] * second[0] + first[1] * second[1] + first[2] * second[2];+}++function cross(first, second) {+ return [first[1] * second[2] - first[2] * second[1], first[2] * second[0] - first[0] * second[2], first[0] * second[1] - first[1] * second[0]];+}++// The shorter step of the two sides, skipping a zero step.+function shorterStep(first, second) {+ const firstLength = dot(first, first);+ const secondLength = dot(second, second);+ return secondLength < 1e-14 || (firstLength >= 1e-14 && firstLength < secondLength) ? first : second;+}++/**+ * buffers: { width, height, ids (Int32Array), positions (Float32Array xyz), colors (Float32Array rgb) }.+ * options: { radii: Map id -> metres, eye, pixelsPerMetre, orthographic }. Returns the blended colors.+ */+export function blendReference(buffers, options) {+ const { width, height, ids, positions, colors } = buffers;+ const clampX = x => Math.min(width - 1, Math.max(0, x));+ const clampY = y => Math.min(height - 1, Math.max(0, y));+ const indexOf = (x, y) => clampY(y) * width + clampX(x);+ const positionAt = (x, y) => Array.from(positions.subarray(indexOf(x, y) * 3, indexOf(x, y) * 3 + 3));+ const normalAt = (x, y, center) => {+ const right = subtract(positionAt(x + 1, y), center);+ const left = subtract(center, positionAt(x - 1, y));+ const up = subtract(positionAt(x, y + 1), center);+ const down = subtract(center, positionAt(x, y - 1));+ const raw = cross(shorterStep(right, left), shorterStep(up, down));+ const toEyeRaw = subtract(options.eye, center);+ const toEye = toEyeRaw.map(component => component / Math.hypot(...toEyeRaw));+ if (dot(raw, raw) < 1e-20) return toEye;+ const normal = raw.map(component => component / Math.hypot(...raw));+ return dot(normal, toEye) < 0 ? normal.map(component => -component) : normal;+ };+ const output = new Float32Array(colors);+ for (let y = 0; y < height; y++) {+ for (let x = 0; x < width; x++) {+ const part = ids[indexOf(x, y)];+ const radius = options.radii.get(part) ?? 0;+ if (part === 0 || radius <= 0) continue;+ const center = positionAt(x, y);+ const pixelRadius = Math.min(MAXIMUM_PIXEL_RADIUS, Math.max(1, radius * options.pixelsPerMetre / (options.orthographic ? 1 : Math.hypot(...subtract(center, options.eye)))));+ const reach = radius * 3;+ const colorSum = [0, 0, 0];+ let otherWeight = 0;+ let totalWeight = 0;+ let nearestTap = null;+ for (let index = 0; index < MESH_BLEND_TAPS.count; index++) {+ const fraction = Math.sqrt((index + 0.5) / MESH_BLEND_TAPS.count);+ const angle = index * MESH_BLEND_TAPS.angleStep;+ const tapX = x + Math.round(Math.cos(angle) * pixelRadius * fraction);+ const tapY = y + Math.round(Math.sin(angle) * pixelRadius * fraction);+ const weight = 1 - fraction;+ totalWeight += weight;+ const tapPart = ids[indexOf(tapX, tapY)];+ if (tapPart === 0 || tapPart === part) continue;+ if (Math.hypot(...subtract(positionAt(tapX, tapY), center)) > reach) continue;+ nearestTap ??= [tapX, tapY];+ for (let channel = 0; channel < 3; channel++) colorSum[channel] += weight * colors[indexOf(tapX, tapY) * 3 + channel];+ otherWeight += weight;+ }+ if (!nearestTap) continue;+ const nearestPosition = positionAt(...nearestTap);+ const creased = smoothstep(0.05, 0.4, 1 - dot(normalAt(x, y, center), normalAt(nearestTap[0], nearestTap[1], nearestPosition)));+ const amount = smoothstep(0, 0.5, otherWeight / totalWeight) * creased;+ for (let channel = 0; channel < 3; channel++) {+ const source = colors[indexOf(x, y) * 3 + channel];+ output[indexOf(x, y) * 3 + channel] = source + (colorSum[channel] / otherWeight - source) * amount;+ }+ }+ }+ return output;+}diff --git a/tests/support/preview-harness.mjs b/tests/support/preview-harness.mjsindex d97ab398..c9497310 100644--- a/tests/support/preview-harness.mjs+++ b/tests/support/preview-harness.mjs@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';import { Script, createContext } from 'node:vm';import { mat4 } from 'gl-matrix';import { createAgentScene, needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, needsPhysics, loadPhysicsEngine, physicsEngineLoaded, loadAllAgentSceneModules, allAgentSceneModulesLoaded } from '../../src/agent-scene.js';+import { normalizeBlend } from '../../src/mesh-blend.js';import { applyProjection } from '../../src/camera.js';import { resolveAgentShadow, agentEnvironmentMap } from '../../src/agent-look.js';import { agentSceneModule, agentSceneModuleLoaded } from '../../src/agent-scene-modules.js';@@ -84,6 +85,7 @@ export function previewHarness() {agentGroundPlacement: () => null, createAgentGround: () => null, placeAgentGround: () => {}, FLOOR_COLOR: [0.22, 0.22, 0.21], groundBounceEnvironment: (parts, environment) => environment,// The optional addons only plug stages into a real renderer; the fault-injected one needs none.installCameraEffects: renderer => renderer, installRenderPasses: renderer => renderer, installDepthPrecision: renderer => renderer,+ installMeshBlend: renderer => Object.assign(renderer, { meshBlend: { radii: new Map() } }), normalizeBlend,});// Evaluate only trusted repository adapter code; inject the driver boundary for failure cases.new Script(source).runInContext(context);diff --git a/vite.lib.config.js b/vite.lib.config.jsindex c7847854..134d2d83 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -84,6 +84,7 @@ export default defineConfig({'render-passes': 'src/render-passes.js','user-pass': 'src/user-pass.js','line-art': 'src/line-art.js',+ 'mesh-blend': 'src/mesh-blend.js','coplanar-overlap': 'src/coplanar-overlap.js','reversed-depth': 'src/reversed-depth.js','material-layer-shaders': 'src/material-layer-shaders.js',