3D engine that AI agents drive
Add an opt-in sky visibility trace from the floor texels, measured, not on by default (part of #197)
Nguyen Xuan Anba7b85ae3749
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex a056fd2a..2392d5ed 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1576,3 +1576,36 @@ Measured by `node bench/reference/depth-precision.mjs [gpu|cpu]` (scene in `deptThe gap-0 pair is two identical boxes, so every pixel ties and the first one drawn keeps it; it never flickers, and a coplanar pair of different size is what `decal` and `resolveCoplanar` are for. The wrong share falls to 1 percent or less at 50 m (0.1 and 1 mm) and at 500 m with a 1 mm gap, but not to zero: at 500 m the 0.1 mm case is still wrong on 13 percent of pixels, because a Float32 world position has a step of 0.03 mm there and the vertex transform adds more, which no depth buffer format removes. The next step, not done here, is a camera-relative vertex transform (the view translation applied to the instance matrix in double precision before the projection). SwiftShader also has the extension (the same page ran there). Its numbers are noisier and are not a precision measure: before 0.20 and 0.10 (50 m, 0.1 and 1 mm), 0.10 and 0.41 (500 m); after 0, 0.16, 0 and 0, with whole frames wrong in some jitters at 50 m and 1 mm. Both sets are 8 frames per case and move with the camera positions.Pictures: `glass`, `brick-flat`, `outdoor-hdri` and `mountain-valley` drawn by SwiftShader with `render-gpu.mjs --cpu` (standard depth, then reversed through the installed addon), with and without `--reversed-depth`: the first three are byte for byte the same; `mountain-valley` differs on 0.055 percent of its pixels by more than 2 of 255 (largest step 31), the edges of far trees where the depth test breaks a tie differently. With `--ambient-occlusion 1` (which reads the depth texture) `brick-flat` is identical and `mountain-valley` differs on 0.13 percent, largest step 28. The GPU renders of the same four scenes are queued behind a path-tracer job and are not in these numbers.++## Sky visibility traced from the floor texels, measured and kept opt-in (2026-11-04, issue #197)++The attempt the volume section named: trace the sky from the floor itself. `applyFloorSkyVisibility(parts, options)` (`src/floor-sky-visibility.js`, `67js/addons/floor-sky-visibility`, nothing in core) finds the floor parts (thin, at least 2 percent of the scene's footprint, opaque, plain, at least 30 percent of the area facing up, no light map and no baked `skyVisibility`), cuts their upward triangles by the longest edge to about 24,000 texels in total, and from each texel shoots 64 cosine-weighted rays (a fixed set, so the same scene gives the same bytes) against every other opaque part with the bake's BVH tracer. The share that escapes goes into the geometry's `skyVisibility`, which the shader already multiplies into the world and sky light of that surface, so the shader and the core entry are unchanged. `strength` blends the share toward 1 (`1 - strength * (1 - share)`). The trace is capped at 20 s and leaves the parts as they were past it, above 200,000 triangles, or when the scene has no floor. A closed room (the ray test of the ground bounce) is left alone unless `includeClosedRooms` is set. Harness: `npm run reference -- --floor-sky [<strength>] [--floor-sky-rooms]`, `frame-time.mjs --floor-sky=<strength>`.++Main at `8153626`, GPU, 960 x 540, FLIP against the stored Cycles arrays, 24 scenes of the default suite and the nine grand options; change from a fresh render of main on the same machine (it reproduces the committed rows: `long-street` 0.1121, `material-spheres` 0.0954, `metal` 0.0944). Scoring is the `score.py` FLIP of each GPU frame; no `baseline.json` row is rewritten.++| Variant | Better than -0.002 | Worse than +0.002 | Worst |+| --- | --- | --- | --- |+| Strength 1, rooms traced too | `brick-flat` -0.0067, `brick-graph` -0.0073, `brushed-film` -0.0090, `car-paint` -0.0143, `material-spheres` -0.0103 | 13 | `lit-interior` +0.1207, `brick-room` +0.1157, `metal-room` +0.1044, `long-street` +0.0368, `dark-shaft` +0.0176 |+| Strength 0.5, closed rooms left alone | `brick-flat` -0.0041, `brick-graph` -0.0039, `brushed-film` -0.0063, `car-paint` -0.0090, `material-spheres` -0.0099 | 4 | `long-street` +0.0135, `megacity-dusk` +0.0032, `emissive-sign` +0.0027, `light-linking` +0.0023 |+| Strength 0.5, rooms traced too | the five above and `temple-hall` -0.0030 | 8 | `brick-room` +0.0561, `lit-interior` +0.0532, `metal-room` +0.0510, `long-street` +0.0135, `dark-shaft` +0.0073 |++Grand options (strength 0.5): `megacity-dusk-b` +0.0033, `-c` +0.0017, `-a` -0.0002; the three valley options are untouched (`mountain-valley-a` and `-b` pass the triangle limit, `-c` has no floor part); the three temple options are closed rooms and unchanged, and traced as rooms they improve: `temple-hall-a` 0.1642 to 0.1536, `-b` 0.1564 to 0.1355, `-c` 0.1177 to 0.1016.++Box 2 (`shadow-depth.py`, display luminance, 67js before > after / Cycles; strength 0.5, rooms traced):++| Scene | p1 | p5 | p25 | contrast (log2) |+| --- | --- | --- | --- | --- |+| `dark-shaft` | 0.0437 > 0.0322 / 0.0293 | 0.0437 > 0.0350 / 0.0313 | 0.0468 > 0.0400 / 0.0430 | 2.46 > 2.51 / 1.96 |+| `temple-hall-a` | 0.0487 > 0.0423 / 0.0334 | 0.0557 > 0.0507 / 0.0363 | 0.0669 > 0.0555 / 0.0466 | 1.16 > 1.17 / 1.33 |+| `temple-hall-b` | 0.0709 > 0.0555 / 0.0339 | 0.0717 > 0.0583 / 0.0370 | 0.0787 > 0.0661 / 0.0449 | 0.78 > 0.78 / 1.80 |+| `temple-hall-c` | 0.0386 > 0.0282 / 0.0163 | 0.0394 > 0.0319 / 0.0184 | 0.0552 > 0.0398 / 0.0222 | 1.33 > 1.34 / 2.02 |+| `megacity-dusk-a` (not a room) | 0.0494 > 0.0494 / 0.0461 | 0.0628 > 0.0600 / 0.0603 | 0.1124 > 0.1124 / 0.1082 | 2.74 > 2.76 / 2.32 |+| `long-street` (not a room) | 0.2006 > 0.2006 / 0.1378 | 0.3642 > 0.2986 / 0.3223 | 0.5072 > 0.5072 / 0.4793 | 1.11 > 1.20 / 1.59 |++The dark end moves toward Cycles in every hall (p1 down by 0.006 to 0.015, p25 down by 0.007 to 0.015) and in `dark-shaft`, but the contrast does not: it moves by at most 0.1 log2 step, and `temple-hall-b` stays at 0.78 against 1.80. Reading (inferred): the light is lowered everywhere on the floor, lit and shadowed tiles alike, because the sky light does not separate them; the contrast needs the sun's shadow to be deeper, which a sky term can not give.++Which scenes fail, and why (inferred, not isolated): `long-street` (+0.0135 at 0.5) and `megacity-dusk` (+0.0032) are lit by the sun and by light that comes back from the walls and the lit street; the term removes sky from a floor that Cycles still lights from the facades, so the street gets too dark. The rooms lit by lamps alone (`lit-interior`, `brick-room`, `metal-room`) lose their whole ambient floor light, which the lamps' bounce gave; they are why closed rooms are skipped.++Cost, measured (GPU, `frame-time.mjs --plain`, median of 3 runs in two rounds): the trace takes 0.5 to 1.7 s for the usual 33,000 to 56,000 texels (2.1 to 3.6 million rays, 64 per texel; `brick-room` 6.4 s for 253,000 texels because its floor part is large). Frame time rises because the floor goes from 2 triangles to about 66,000: `long-street` 0.40 to 0.61 ms, `material-spheres` 0.52 to 0.63 ms, `temple-hall-a` 1.50 to 1.80 ms (+0.1 to +0.3 ms; the shadow pass draws the triangles too). A 2D texture read in the shader would avoid that and needs a core hook; it was not tried.++Box 4 fails: four default scenes pass the 0.002 limit at the best variant (`long-street` +0.0135 is the worst), so the term is not on by default. It stays as an opt-in addon, off unless a scene calls `applyFloorSkyVisibility` or the harness flag is given, so the default frames, `baseline.json` and `grand.json` are unchanged. It helps `car-paint`, `brick-flat`, `brick-graph`, `brushed-film`, `material-spheres` (-0.004 to -0.010) and the three temple options (-0.011 to -0.021), and costs the street and city scenes. Next idea, if taken up: a per-texel map that also carries the light that comes back from the lit walls (the sun-lit side of the facades seen from the floor texel), so a street is darkened by the sky it loses and lit by what the facades give, instead of by sky visibility alone.diff --git a/bench/reference/frame-time.mjs b/bench/reference/frame-time.mjsindex 3b468771..50cf44d3 100644--- a/bench/reference/frame-time.mjs+++ b/bench/reference/frame-time.mjs@@ -1,5 +1,5 @@// Frame time of a reference scene: plain, with the light bake, with reflection probes, and with both.-// node bench/reference/frame-time.mjs [scene-id] [gpu|cpu] [--grand]+// node bench/reference/frame-time.mjs [scene-id] [gpu|cpu] [--grand] [--floor-sky=<strength> [--floor-sky-rooms]]import { constants, setPriority } from 'node:os';import { chromium } from 'playwright';import { createServer } from 'vite';@@ -19,7 +19,9 @@ const serverUrl = `http://127.0.0.1:${server.httpServer.address().port}`;const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: BACKEND_ARGUMENTS[backend] });try {const page = await browser.newPage({ viewport: { width: 960, height: 540 } });- await page.goto(`${serverUrl}/bench/reference/harness.html${process.argv.includes('--grand') ? '?set=grand' : ''}`, { timeout: PAGE_LOAD_TIMEOUT });+ const floorSkyArgument = process.argv.find(argument => argument.startsWith('--floor-sky='));+ const harnessQuery = [process.argv.includes('--grand') ? 'set=grand' : null, floorSkyArgument ? `floorSky=${floorSkyArgument.split('=')[1]}` : null, process.argv.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : null].filter(Boolean).join('&');+ await page.goto(`${serverUrl}/bench/reference/harness.html${harnessQuery ? `?${harnessQuery}` : ''}`, { timeout: PAGE_LOAD_TIMEOUT });await page.waitForFunction(() => window.measureReferenceFrameTime, null, { timeout: PAGE_LOAD_TIMEOUT });const results = [];// Alternate the order so a drifting machine load does not favor one side. --cascades measures one map and threediff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex bfb29d2b..d9451562 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -17,6 +17,7 @@ import { applyLightLinks } from '/src/light-linking.js';import { applyWaterReflection, attachWaterReflection } from '/src/water-reflection.js';import { attachScreenSpaceWater } from './ssr-water.js';import { groundBounceEnvironment } from '/src/ground-bounce.js';+import { applyFloorSkyVisibility } from '/src/floor-sky-visibility.js';import { installReversedDepth } from '/src/reversed-depth.js';// Water reflection is on the way a recipe gets it: found from the materials, no field. ?water=off draws the scenes without it, ?water=ssr with the screen-space reflection it was compared with.@@ -33,6 +34,17 @@ const REVERSED_DEPTH = new URLSearchParams(location.search).get('reversedDepth')const WATER_REFLECTION = { off: false, ssr: 'ssr' }[new URLSearchParams(location.search).get('water')] ?? 'planar';+// ?floorSky=<strength> traces the sky each floor texel sees (src/floor-sky-visibility.js) and scales the world light there by it; the scenes draw without it otherwise.+const FLOOR_SKY_STRENGTH = Number(new URLSearchParams(location.search).get('floorSky')) || 0;+const floorSkyReports = {};++function withFloorSky(id, parts) {+ if (!FLOOR_SKY_STRENGTH) return parts;+ const result = applyFloorSkyVisibility(parts, { strength: FLOOR_SKY_STRENGTH, includeClosedRooms: new URLSearchParams(location.search).get('floorSkyRooms') === '1' });+ floorSkyReports[id] = result.report;+ return result.parts;+}+// ?set=khronos draws the Khronos sample assets (npm run reference -- --khronos) and ?set=cloth the cloth scenes// (npm run reference -- --cloth) instead of the fixed scenes.const SCENE_SETS = { khronos: KHRONOS_SCENES, ktx2: KTX2_SCENES, cloth: CLOTH_SCENES, grand: GRAND_SCENES, look: LOOK_OPTIONS };@@ -196,7 +208,7 @@ async function renderReferenceScene(id, { describe, ambientOcclusion = 0, ambienscene.environment = withDerivedGroundBounce(scene, probed ? probed.parts : baked ? baked.parts : scene.parts);const canvas = document.querySelector('canvas');// backgroundOnly draws the sky alone, so a score can be limited to the pixels the asset covers.- const renderer = createSceneRenderer(backgroundOnly ? [] : probed ? probed.parts : baked ? baked.parts : scene.parts, scene, cascades);+ const renderer = createSceneRenderer(backgroundOnly ? [] : withFloorSky(id, probed ? probed.parts : baked ? baked.parts : scene.parts), scene, cascades);renderer.resize();// Blender draws a still scene. The renderer's default wind (0.3) would move the leaf cards by up to four pixels at time 0.const frame = { ...scene.camera, environment: scene.environment, time: 0, wind: 0, exposure: 1, effects: { ambientOcclusion, ambientOcclusionRadius } };@@ -210,6 +222,7 @@ async function renderReferenceScene(id, { describe, ambientOcclusion = 0, ambiendescription: describe ? describeScene(id, scene) : null,bake: baked ? { seconds: baked.seconds, report: baked.report } : null,probes: probed ? { seconds: probed.seconds, report: probed.report } : null,+ floorSky: floorSkyReports[id] ?? null,};renderer.dispose();return result;@@ -221,7 +234,7 @@ async function measureReferenceFrameTime(id, { bake, probes = false, cascades =const baked = bake ? await bakeScene(scene, {}) : null;const probed = probes ? await probeScene(scene, id, baked ? baked.parts : scene.parts, probes) : null;scene.environment = withDerivedGroundBounce(scene, probed ? probed.parts : baked ? baked.parts : scene.parts);- const renderer = createSceneRenderer(probed ? probed.parts : baked ? baked.parts : scene.parts, scene, cascades, { water });+ const renderer = createSceneRenderer(withFloorSky(id, probed ? probed.parts : baked ? baked.parts : scene.parts), scene, cascades, { water });renderer.resize();const frame = { ...scene.camera, environment: scene.environment, time: 0, exposure: 1, effects: { ambientOcclusion: 0, ambientOcclusionRadius: 0.5 } };// With orbit the camera moves a little every frame, so cascaded maps have to be redrawn each time, as in a camera move.diff --git a/bench/reference/run.mjs b/bench/reference/run.mjsindex 3b085095..be626af4 100644--- a/bench/reference/run.mjs+++ b/bench/reference/run.mjs@@ -54,6 +54,10 @@ const BACKEND_ARGUMENTS = {};const argumentsGiven = process.argv.slice(2);+// --floor-sky-rooms also traces closed rooms, which are left as they are otherwise.+// --floor-sky [<strength>] traces the sky each floor texel sees (src/floor-sky-visibility.js) and scales the world light on floors by it (strength 1 when none follows).+const floorSkyFlag = argumentsGiven.indexOf('--floor-sky');+const floorSkyStrength = floorSkyFlag < 0 ? 0 : Number(argumentsGiven[floorSkyFlag + 1]) || 1;const scoreOnly = argumentsGiven.includes('--score-only');const skipBlender = argumentsGiven.includes('--skip-blender') || lookIds !== null;// --skip-cpu leaves out the SwiftShader render (very slow for the 9 million triangle scenes) and the scoring, which needs it.@@ -101,7 +105,7 @@ const sceneIdsGiven = lookIds ?? (sceneFlag >= 0 ? argumentsGiven[sceneFlag + 1]// The fresh bake.json lands in the work directory and is checked against the committed one (compare-scores.mjs); --update-baseline replaces// the committed bake.json and images/<id>-baked.jpg with it.const bakeScoreRun = bakedSceneIds !== null && !sceneSet && !pathTracerFlag;-const bakeVariantFlags = ['--sky-only', '--bake-preset', '--probes', '--ambient', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce'];+const bakeVariantFlags = ['--sky-only', '--bake-preset', '--probes', '--ambient', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce', '--floor-sky', '--floor-sky-rooms'];const bakeScoreIsBaseline = bakeScoreRun && argumentsGiven.includes('--update-baseline') && !bakeVariantFlags.some(flag => argumentsGiven.includes(flag));const onlyScenes = sceneIdsGiven ?? (bakeScoreRun ? bakedSceneIds : null);const skipCpu = skipCpuFlag || bakeScoreRun || Boolean(viewTransform);@@ -115,7 +119,7 @@ async function renderBackend(backend, serverUrl, graphics) {page.on('console', message => message.text().includes('GL_') && console.log('PAGE', message.text().slice(0, 200)));// Each scene gets a fresh page, so a large scene leaves no GL state or memory behind for the next one.const openHarness = async () => {- const harnessQuery = [sceneSet ? `set=${sceneSet}` : null, argumentsGiven.includes('--no-water') ? 'water=off' : argumentsGiven.includes('--ssr-water') ? 'water=ssr' : null, argumentsGiven.includes('--no-ground-bounce') ? 'groundBounce=off' : null].filter(Boolean).join('&');+ const harnessQuery = [sceneSet ? `set=${sceneSet}` : null, argumentsGiven.includes('--no-water') ? 'water=off' : argumentsGiven.includes('--ssr-water') ? 'water=ssr' : null, argumentsGiven.includes('--no-ground-bounce') ? 'groundBounce=off' : null, floorSkyStrength ? `floorSky=${floorSkyStrength}` : null, argumentsGiven.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : null].filter(Boolean).join('&');await page.goto(`${serverUrl}/bench/reference/harness.html${harnessQuery ? `?${harnessQuery}` : ''}`, { timeout: PAGE_LOAD_TIMEOUT });await page.waitForFunction(() => window.renderReferenceScene, null, { timeout: PAGE_LOAD_TIMEOUT });};@@ -143,7 +147,8 @@ async function renderBackend(backend, serverUrl, graphics) {}const bakeNote = result.bake?.report.refused ? `, bake REFUSED, drawn unbaked: ${result.bake.report.refused}` : result.bake ? `, bake ${result.bake.seconds.toFixed(1)} s, ${result.bake.report.texels} texels${result.bake.report.used ? ` (used ${result.bake.report.used.samples} samples, ${result.bake.report.used.bounces} bounces, ${result.bake.report.used.texelsPerUnit} texels per unit${result.bake.report.reduced ? ', reduced' : ''})` : ''}` : '';const probeNote = result.probes ? `, probes ${result.probes.report.placed.length} on ${result.probes.report.partsWithProbe} parts` : '';- console.log(`${id} on ${backend}: ${Math.round(performance.now() - started)} ms${bakeNote}${probeNote}`);+ const floorSkyNote = result.floorSky ? `, floor sky ${result.floorSky.reason ?? `${result.floorSky.texels} texels, ${result.floorSky.rays} rays, ${result.floorSky.seconds.toFixed(2)} s`}` : '';+ console.log(`${id} on ${backend}: ${Math.round(performance.now() - started)} ms${bakeNote}${probeNote}${floorSkyNote}`);}if (errors.length) throw new Error(errors.join('\n'));} finally {diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex ad5dd2ec..bb2e6500 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -33,6 +33,7 @@"entry:clutter": 5300,"entry:light-bake": 28500,"entry:ground-bounce": 9460,+ "entry:floor-sky-visibility": 15040,"entry:path-tracer": 17110,"entry:texture-set": 900,"entry:agent-scene": 81967,diff --git a/changes/197.md b/changes/197.mdnew file mode 100644index 00000000..058e0993--- /dev/null+++ b/changes/197.md@@ -0,0 +1 @@+- Add `applyFloorSkyVisibility` (`67js/addons/floor-sky-visibility`, issue #197), an opt-in trace of the sky each floor texel sees: 64 cosine-weighted rays per texel against the other parts, written into the floor's `skyVisibility`, which the shader already multiplies into the world and sky light. It adds nothing to the core entry, is off unless called, and leaves closed rooms alone unless `includeClosedRooms` is set. On the reference suite it improves 5 scenes by 0.004 to 0.010 FLIP (`car-paint`, `material-spheres`, `brushed-film`, `brick-flat`, `brick-graph`) and the three grand temple options by 0.011 to 0.021, but `long-street` gets worse by 0.0135 and three more scenes pass 0.002, so it is not on by default. The trace takes 0.5 to 1.7 s and the cut floor adds 0.1 to 0.3 ms per frame. The README has the numbers.diff --git a/changes/197.size.md b/changes/197.size.mdnew file mode 100644index 00000000..ce4f5b76--- /dev/null+++ b/changes/197.size.md@@ -0,0 +1 @@+- entry:light-bake: three helpers (hashUnit, radicalInverse, cosineDirection) are exported for the floor sky trace, 30 bytesdiff --git a/docs/lighting.md b/docs/lighting.mdindex d943070d..dd1e9c22 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -130,6 +130,10 @@ Luminance of the 67js picture over Cycles (linear, whole frame and 20th percentiThe two `temple-hall` p20 values differ only by the rescaling of the picture (the scene has a sun, so no bounce is added). The outdoor shadow fill of the issue is not done.+## Sky seen from the floor++`applyFloorSkyVisibility(parts, { strength, includeClosedRooms })` (`67js/addons/floor-sky-visibility`) is opt-in and returns `{ parts, report }`. It cuts the floor parts into texels, shoots 64 cosine-weighted rays from each against the other opaque parts and stores the share that escapes as the floor's `skyVisibility`, so the world and sky light on a floor under a roof or between walls is scaled down and open ground is not. Pass the returned parts to the renderer. `strength` 1 uses the traced share, 0.5 keeps half of what it hides. A closed room is left alone unless `includeClosedRooms` is `true`, and a scene that is too large (over 200,000 triangles), has no floor or runs past `maxSeconds` (20) comes back unchanged with `report.reason`. It is not on by default: it moves the dark end of halls and studio floors toward Cycles, and makes sunlit streets too dark (`long-street` +0.0135 FLIP at 0.5). The trace takes 0.5 to 1.7 s, and the floor grows to about 66,000 triangles, which adds 0.1 to 0.3 ms per frame in the reference scenes. Numbers: `bench/reference/README.md`, "Sky visibility traced from the floor texels".+## Local shadows`castShadow: true` on a point or spot light draws that light's depth into one shared atlas of 2048 x 3072 texels: 24 tiles of 512 x 512, a 24 MiB depth texture allocated on first use. A spot light takes one tile with a perspective view of `2 * angle + 4` degrees (170 at most). A point light takes six tiles, one per cube face, each 92 degrees wide. Lights are given tiles in order: point lights, then spot lights. A request for more than 24 tiles, for example five shadowed point lights, throws `RangeError` and changes nothing. So the most is four shadowed point lights, or for example two point lights and eight spot lights.diff --git a/package.json b/package.jsonindex f423d321..e139872a 100644--- a/package.json+++ b/package.json@@ -77,6 +77,7 @@"./addons/clutter": "./build/clutter.js","./addons/light-bake": "./build/light-bake.js","./addons/ground-bounce": "./build/ground-bounce.js",+ "./addons/floor-sky-visibility": "./build/floor-sky-visibility.js","./addons/path-tracer": "./build/path-tracer.js","./addons/texture-set": "./build/texture-set.js","./addons/agent-scene": "./build/agent-scene.js",diff --git a/src/floor-sky-visibility.js b/src/floor-sky-visibility.jsnew file mode 100644index 00000000..749a1211--- /dev/null+++ b/src/floor-sky-visibility.js@@ -0,0 +1,272 @@+import { CLOSED_ROOM_SHARE, closedRoomShare } from './closed-room.js';+import { buildWorld, cosineDirection, radicalInverse, sceneScale } from './light-bake.js';+import { worldBounds } from './probe-trace.js';+import { createTracer } from './ray-query.js';++// Sky visibility traced from the texels of the floor itself. A floor part is cut into small triangles, every vertex shoots+// cosine-weighted rays up into the scene's other parts, and the share that escapes goes into the geometry's `skyVisibility`,+// which the shader already multiplies into the light the world gives that surface. A narrow street or a hall then darkens+// where its walls and roofs hide the sky, and open ground stays as it was. It adds no shader code and nothing to the core+// entry; the cost is one trace when the parts are prepared, not per frame.++export const FLOOR_SKY_RAYS = 64;+export const FLOOR_SKY_MAXIMUM_TEXELS = 24_000;+export const FLOOR_SKY_MAXIMUM_SECONDS = 20;+export const FLOOR_SKY_STRENGTH = 1;++const FLOOR_THINNESS = 0.1;+const FLOOR_MINIMUM_FOOTPRINT_SHARE = 0.02;+const UPWARD_NORMAL = 0.7;+const FLOOR_MINIMUM_UPWARD_SHARE = 0.3;+const WELD_SCALE = 1e5;+const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke', 'floor', 'water', 'foliage', 'grass', 'terrain']);+const FIXED_ROTATION = 0.37;++function sceneBoundsOf(boundsList) {+ const minimum = [Infinity, Infinity, Infinity];+ const maximum = [-Infinity, -Infinity, -Infinity];+ for (const bounds of boundsList) {+ for (let axis = 0; axis < 3; axis++) {+ minimum[axis] = Math.min(minimum[axis], bounds.minimum[axis]);+ maximum[axis] = Math.max(maximum[axis], bounds.maximum[axis]);+ }+ }+ return { minimum, maximum };+}++function hasPlainMesh(part) {+ const { geometry } = part;+ const rigid = !part.skin && !part.morph && !part.crowd && !geometry.morphTargets && !geometry.skinIndices && !geometry.crowdJoints;+ const carriesLight = geometry.skyVisibility || geometry.lightUvs || part.material?.lightMap;+ return rigid && !carriesLight && Boolean(geometry.normals) && geometry.indices.length > 0;+}++function isFloorMaterial(material) {+ return !material || (material.alphaMode !== 'blend' && material.alphaMode !== 'mask' && !(material.transmission > 0) && !EXCLUDED_TAGS.has(material.tag));+}++// The share of a part's triangle area whose world normal points up: a slab with a roof and a floor side counts half.+function upwardAreaShare(part) {+ const { positions, indices } = part.geometry;+ let upward = 0;+ let total = 0;+ for (let corner = 0; corner < indices.length; corner += 3) {+ const triangle = [indices[corner], indices[corner + 1], indices[corner + 2]];+ const [first, second, third] = triangle.map(vertex => transformPoint(part.matrix, positions, vertex));+ const edgeOne = [second[0] - first[0], second[1] - first[1], second[2] - first[2]];+ const edgeTwo = [third[0] - first[0], third[1] - first[1], third[2] - first[2]];+ const normal = [edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1], edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2], edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]];+ const doubleArea = Math.hypot(...normal);+ total += doubleArea;+ if (doubleArea > 0 && normal[1] / doubleArea >= UPWARD_NORMAL) upward += doubleArea;+ }+ return total > 0 ? upward / total : 0;+}++function transformPoint(matrix, positions, vertex) {+ const x = positions[vertex * 3];+ const y = positions[vertex * 3 + 1];+ const z = positions[vertex * 3 + 2];+ return [0, 1, 2].map(axis => matrix[axis] * x + matrix[4 + axis] * y + matrix[8 + axis] * z + matrix[12 + axis]);+}++/** Which parts are floors: thin, wide, opaque and plain, with a good share of their area facing up. Returns the indices. */+export function findFloorParts(parts) {+ const boundsList = parts.map(part => worldBounds(part));+ const scene = sceneBoundsOf(boundsList);+ const sceneFootprint = (scene.maximum[0] - scene.minimum[0]) * (scene.maximum[2] - scene.minimum[2]);+ const floors = [];+ parts.forEach((part, index) => {+ const bounds = boundsList[index];+ const widthX = bounds.maximum[0] - bounds.minimum[0];+ const widthZ = bounds.maximum[2] - bounds.minimum[2];+ const height = bounds.maximum[1] - bounds.minimum[1];+ const isThin = height <= FLOOR_THINNESS * Math.max(widthX, widthZ);+ const isWide = widthX * widthZ >= FLOOR_MINIMUM_FOOTPRINT_SHARE * sceneFootprint;+ if (isThin && isWide && isFloorMaterial(part.material) && hasPlainMesh(part) && upwardAreaShare(part) >= FLOOR_MINIMUM_UPWARD_SHARE) floors.push(index);+ });+ return floors;+}++function transformDirection(matrix, x, y, z, out) {+ for (let axis = 0; axis < 3; axis++) out[axis] = matrix[axis] * x + matrix[4 + axis] * y + matrix[8 + axis] * z;+ return out;+}++function worldEdgeLength(matrix, positions, first, second) {+ const edge = transformDirection(matrix, positions[second * 3] - positions[first * 3], positions[second * 3 + 1] - positions[first * 3 + 1], positions[second * 3 + 2] - positions[first * 3 + 2], [0, 0, 0]);+ return Math.hypot(edge[0], edge[1], edge[2]);+}++// The part's mesh as growing arrays, with vertices shared by position, normal, UV and colour so the cut stays connected.+function createMeshBuilder(geometry) {+ const hasUvs = Boolean(geometry.uvs);+ const hasColors = Boolean(geometry.colors);+ const positions = [];+ const normals = [];+ const uvs = [];+ const colors = [];+ const welded = new Map();+ function addVertex(position, normal, uv, color) {+ const key = [...position, ...normal, ...(uv ?? []), ...(color ?? [])].map(value => Math.round(value * WELD_SCALE)).join(',');+ if (!welded.has(key)) {+ welded.set(key, positions.length / 3);+ positions.push(...position);+ normals.push(...normal);+ if (hasUvs) uvs.push(...uv);+ if (hasColors) colors.push(...color);+ }+ return welded.get(key);+ }+ function readVertex(index) {+ return {+ position: [geometry.positions[index * 3], geometry.positions[index * 3 + 1], geometry.positions[index * 3 + 2]],+ normal: [geometry.normals[index * 3], geometry.normals[index * 3 + 1], geometry.normals[index * 3 + 2]],+ uv: hasUvs ? [geometry.uvs[index * 2], geometry.uvs[index * 2 + 1]] : null,+ color: hasColors ? [geometry.colors[index * 3], geometry.colors[index * 3 + 1], geometry.colors[index * 3 + 2]] : null,+ };+ }+ function midpoint(first, second) {+ const average = (left, right) => (left && right ? left.map((value, slot) => (value + right[slot]) / 2) : null);+ const normal = average(first.normal, second.normal);+ const length = Math.hypot(...normal) || 1;+ return { position: average(first.position, second.position), normal: normal.map(value => value / length), uv: average(first.uv, second.uv), color: average(first.color, second.color) };+ }+ return { positions, normals, uvs, colors, addVertex, readVertex, midpoint, hasUvs, hasColors };+}++function worldNormalOf(matrix, positions, corners) {+ const [first, second, third] = corners.map(corner => [positions[corner * 3], positions[corner * 3 + 1], positions[corner * 3 + 2]]);+ const edgeOne = transformDirection(matrix, second[0] - first[0], second[1] - first[1], second[2] - first[2], [0, 0, 0]);+ const edgeTwo = transformDirection(matrix, third[0] - first[0], third[1] - first[1], third[2] - first[2], [0, 0, 0]);+ const normal = [edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1], edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2], edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]];+ const length = Math.hypot(...normal) || 1;+ return normal.map(value => value / length);+}++/**+ * Cuts the upward-facing triangles of a geometry (world edges longer than `maximumEdge`) by their longest edge, and leaves the+ * others as they are. Returns the new arrays and which vertices belong to a triangle that faces up.+ */+function cutGeometry(geometry, matrix, maximumEdge) {+ const builder = createMeshBuilder(geometry);+ const indices = [];+ const upwardVertices = new Set();+ const midpoints = new Map();+ const sourceIndex = vertexData => builder.addVertex(vertexData.position, vertexData.normal, vertexData.uv, vertexData.color);+ const inputVertices = [];+ for (let index = 0; index < geometry.positions.length / 3; index++) inputVertices.push(builder.readVertex(index));+ const cutWork = [];+ for (let corner = 0; corner < geometry.indices.length; corner += 3) {+ const triangle = [0, 1, 2].map(slot => geometry.indices[corner + slot]);+ const normal = worldNormalOf(matrix, geometry.positions, triangle);+ if (normal[1] >= UPWARD_NORMAL) {+ cutWork.push(triangle.map(vertexIndex => inputVertices[vertexIndex]));+ } else {+ indices.push(...triangle.map(vertexIndex => sourceIndex(inputVertices[vertexIndex])));+ }+ }+ const lengthBetween = (first, second) => worldEdgeLength(matrix, [...first.position, ...second.position], 0, 1);+ while (cutWork.length > 0) {+ const corners = cutWork.pop();+ const edgeLengths = [lengthBetween(corners[0], corners[1]), lengthBetween(corners[1], corners[2]), lengthBetween(corners[2], corners[0])];+ const longest = edgeLengths.indexOf(Math.max(...edgeLengths));+ if (edgeLengths[longest] <= maximumEdge) {+ const added = corners.map(sourceIndex);+ indices.push(...added);+ added.forEach(vertex => upwardVertices.add(vertex));+ continue;+ }+ const first = corners[longest];+ const second = corners[(longest + 1) % 3];+ const opposite = corners[(longest + 2) % 3];+ const key = [first, second].map(vertexData => sourceIndex(vertexData)).sort((left, right) => left - right).join('|');+ if (!midpoints.has(key)) midpoints.set(key, builder.midpoint(first, second));+ const middle = midpoints.get(key);+ cutWork.push([first, middle, opposite], [middle, second, opposite]);+ }+ return { builder, indices, upwardVertices };+}++function fixedSamples(sampleCount) {+ return Array.from({ length: sampleCount }, (unused, sample) => [(sample + 0.5) / sampleCount, (radicalInverse(sample) + FIXED_ROTATION) % 1]);+}++/**+ * Returns `{ parts, report }`: the parts with their floors cut into texels and given `geometry.skyVisibility`, traced by+ * `raysPerTexel` cosine-weighted rays against every other opaque part. `strength` 1 uses the traced share as it is, 0.5 only+ * half of what it hides. A closed room (the closed-room ray test) comes back unchanged unless `includeClosedRooms` is set. The parts come back unchanged (and `report.reason` says why) when the scene has no floor, is+ * larger than the bake's triangle limit, or the trace passes `maxSeconds`. It reads no clock to decide anything else, and+ * the rays are a fixed set, so the same scene gives the same bytes.+ */+export function applyFloorSkyVisibility(parts, { raysPerTexel = FLOOR_SKY_RAYS, maximumTexels = FLOOR_SKY_MAXIMUM_TEXELS, maxSeconds = FLOOR_SKY_MAXIMUM_SECONDS, strength = FLOOR_SKY_STRENGTH, includeClosedRooms = false } = {}) {+ const started = performance.now();+ const unchanged = reason => ({ parts, report: { floors: [], texels: 0, rays: 0, seconds: (performance.now() - started) / 1000, reason } });+ const floorIndices = findFloorParts(parts);+ if (floorIndices.length === 0) return unchanged('no floor');+ // Every opaque part blocks sky, floors included: a floor above another one (a gallery, a bridge) hides it, and a floor never+ // blocks its own texels because the rays leave from its top face.+ const occluders = parts.filter(part => part.material?.alphaMode !== 'blend');+ if (occluders.length < 2) return unchanged('nothing above the floor');+ // A closed room has no sky to see: its walls and lamps give the light, and the shader's room term already handles it.+ const roomShare = closedRoomShare(parts, new Map(parts.map(part => [part.name, part.matrix])));+ if (!includeClosedRooms && roomShare !== null && roomShare >= CLOSED_ROOM_SHARE) return unchanged('closed room');+ let world;+ try {+ world = buildWorld(occluders);+ } catch {+ return unchanged('too many triangles');+ }+ const footprint = floorIndices.reduce((total, index) => {+ const bounds = worldBounds(parts[index]);+ return total + (bounds.maximum[0] - bounds.minimum[0]) * (bounds.maximum[2] - bounds.minimum[2]);+ }, 0);+ const maximumEdge = Math.sqrt(footprint / maximumTexels) * 1.4;+ const tracer = createTracer(world);+ const offset = sceneScale(world.positions) * 1e-4;+ const samples = fixedSamples(raysPerTexel);+ const direction = [0, 0, 0];+ const worldNormal = [0, 0, 0];+ const floors = [];+ let totalRays = 0;+ const nextParts = parts.slice();+ for (const index of floorIndices) {+ const part = parts[index];+ const { geometry, matrix } = part;+ const { builder, indices, upwardVertices } = cutGeometry(geometry, matrix, maximumEdge);+ const vertexCount = builder.positions.length / 3;+ const skyVisibility = new Float32Array(vertexCount).fill(1);+ for (const vertex of upwardVertices) {+ if (performance.now() - started > maxSeconds * 1000) return unchanged('passed maxSeconds');+ const local = builder.positions.slice(vertex * 3, vertex * 3 + 3);+ const point = [0, 0, 0];+ for (let axis = 0; axis < 3; axis++) point[axis] = matrix[axis] * local[0] + matrix[4 + axis] * local[1] + matrix[8 + axis] * local[2] + matrix[12 + axis];+ transformDirection(matrix, builder.normals[vertex * 3], builder.normals[vertex * 3 + 1], builder.normals[vertex * 3 + 2], worldNormal);+ const length = Math.hypot(...worldNormal) || 1;+ worldNormal[0] /= length;+ worldNormal[1] /= length;+ worldNormal[2] /= length;+ let escaped = 0;+ for (const [firstUnit, secondUnit] of samples) {+ cosineDirection(worldNormal, firstUnit, secondUnit, direction);+ const hit = tracer.trace(point[0] + worldNormal[0] * offset, point[1] + worldNormal[1] * offset, point[2] + worldNormal[2] * offset, direction[0], direction[1], direction[2], Infinity, true);+ if (hit.nearestTriangle < 0) escaped++;+ }+ skyVisibility[vertex] = 1 - strength * (1 - escaped / raysPerTexel);+ totalRays += raysPerTexel;+ }+ const cutGeometryResult = {+ ...geometry,+ positions: new Float32Array(builder.positions),+ normals: new Float32Array(builder.normals),+ indices: new Uint32Array(indices),+ skyVisibility,+ };+ if (builder.hasUvs) cutGeometryResult.uvs = new Float32Array(builder.uvs);+ if (builder.hasColors) cutGeometryResult.colors = new Float32Array(builder.colors);+ nextParts[index] = Object.freeze({ ...part, geometry: Object.freeze(cutGeometryResult) });+ floors.push({ name: part.name, texels: upwardVertices.size, triangles: indices.length / 3 });+ }+ const texels = floors.reduce((total, floor) => total + floor.texels, 0);+ return { parts: Object.freeze(nextParts), report: { floors, texels, rays: totalRays, seconds: (performance.now() - started) / 1000, reason: null } };+}diff --git a/src/light-bake.js b/src/light-bake.jsindex d6c56417..fcee471c 100644--- a/src/light-bake.js+++ b/src/light-bake.js@@ -284,7 +284,7 @@ export function sceneScale(positions) {}/** Integer hash to [0, 1): the only source of randomness, so a bake repeats exactly. */-function hashUnit(first, second, third) {+export function hashUnit(first, second, third) {let value = Math.imul(first ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(second + 0x7f4a7c15, 0xc2b2ae35) ^ Math.imul(third + 0x165667b1, 0x27d4eb2f);value = Math.imul(value ^ (value >>> 15), 0x2c1b3c6d);value = Math.imul(value ^ (value >>> 12), 0x297a2d39);@@ -292,7 +292,7 @@ function hashUnit(first, second, third) {return (value >>> 0) / 4294967296;}-function radicalInverse(index) {+export function radicalInverse(index) {let bits = index;let result = 0;let scale = 0.5;@@ -305,7 +305,7 @@ function radicalInverse(index) {}/** A cosine-weighted direction about `normal`, written into `out`. */-function cosineDirection(normal, firstUnit, secondUnit, out) {+export function cosineDirection(normal, firstUnit, secondUnit, out) {const radius = Math.sqrt(firstUnit);const angle = 2 * Math.PI * secondUnit;const localX = radius * Math.cos(angle);diff --git a/tests/floor-sky-visibility.test.js b/tests/floor-sky-visibility.test.jsnew file mode 100644index 00000000..688c10df--- /dev/null+++ b/tests/floor-sky-visibility.test.js@@ -0,0 +1,108 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { applyFloorSkyVisibility, findFloorParts } from '../src/floor-sky-visibility.js';++const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];++// A flat square of side `size` at height `height`, facing up (or down), with UVs.+function square(name, size, height, { facing = 1, material = { color: [0.5, 0.5, 0.5] } } = {}) {+ const half = size / 2;+ const geometry = {+ positions: new Float32Array([-half, height, -half, half, height, -half, half, height, half, -half, height, half]),+ normals: new Float32Array([0, facing, 0, 0, facing, 0, 0, facing, 0, 0, facing, 0]),+ uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),+ indices: new Uint32Array(facing > 0 ? [0, 2, 1, 0, 3, 2] : [0, 1, 2, 0, 2, 3]),+ };+ return { name, geometry, matrix: IDENTITY, material };+}++function skyVisibilityAt(result, floorIndex, x, z) {+ const { positions } = result.parts[floorIndex].geometry;+ const { skyVisibility } = result.parts[floorIndex].geometry;+ let nearest = 0;+ let nearestDistance = Infinity;+ for (let vertex = 0; vertex < positions.length / 3; vertex++) {+ const distance = Math.hypot(positions[vertex * 3] - x, positions[vertex * 3 + 2] - z);+ if (distance < nearestDistance) {+ nearestDistance = distance;+ nearest = vertex;+ }+ }+ return skyVisibility[nearest];+}++test('an open floor stays at full sky visibility', () => {+ const floor = square('floor', 20, 0);+ const result = applyFloorSkyVisibility([floor, square('far-away-roof', 2, 50, { facing: -1 })], { maximumTexels: 400 });+ assert.equal(result.report.reason, null);+ const values = result.parts[0].geometry.skyVisibility;+ assert.ok(values.length > 4, 'the floor is cut into texels');+ assert.ok(Math.min(...values) > 0.95, `the lowest value is ${Math.min(...values)}`);+});++test('a roof hides the sky under it and leaves the open side alone', () => {+ const floor = square('floor', 20, 0);+ const roof = square('roof', 6, 2, { facing: -1 });+ const result = applyFloorSkyVisibility([floor, roof], { maximumTexels: 1600 });+ const under = skyVisibilityAt(result, 0, 0, 0);+ const outside = skyVisibilityAt(result, 0, 9, 9);+ assert.ok(under < 0.5, `under the roof ${under}`);+ assert.ok(outside > 0.95, `outside ${outside}`);+});++test('strength 0.5 keeps half of what the roof hides', () => {+ const parts = [square('floor', 20, 0), square('roof', 6, 2, { facing: -1 })];+ const full = skyVisibilityAt(applyFloorSkyVisibility(parts, { maximumTexels: 1600 }), 0, 0, 0);+ const half = skyVisibilityAt(applyFloorSkyVisibility(parts, { maximumTexels: 1600, strength: 0.5 }), 0, 0, 0);+ assert.ok(Math.abs(half - (1 - (1 - full) / 2)) < 1e-6);+});++test('the cut floor keeps its UVs, normals and a shape that covers the same area', () => {+ const result = applyFloorSkyVisibility([square('floor', 10, 0), square('roof', 2, 3, { facing: -1 })], { maximumTexels: 200 });+ const { positions, uvs, normals, indices } = result.parts[0].geometry;+ assert.equal(uvs.length / 2, positions.length / 3);+ assert.equal(normals.length, positions.length);+ let area = 0;+ for (let corner = 0; corner < indices.length; corner += 3) {+ const [first, second, third] = [0, 1, 2].map(slot => indices[corner + slot]);+ const edgeOne = [positions[second * 3] - positions[first * 3], positions[second * 3 + 2] - positions[first * 3 + 2]];+ const edgeTwo = [positions[third * 3] - positions[first * 3], positions[third * 3 + 2] - positions[first * 3 + 2]];+ area += Math.abs(edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]) / 2;+ }+ assert.ok(Math.abs(area - 100) < 1e-3, `area ${area}`);+ for (let vertex = 0; vertex < positions.length / 3; vertex++) {+ assert.ok(Math.abs(uvs[vertex * 2] - (positions[vertex * 3] / 10 + 0.5)) < 1e-5);+ }+});++test('the same parts give the same bytes', () => {+ const parts = [square('floor', 10, 0), square('roof', 4, 2, { facing: -1 })];+ const first = applyFloorSkyVisibility(parts, { maximumTexels: 300 }).parts[0].geometry.skyVisibility;+ const second = applyFloorSkyVisibility(parts, { maximumTexels: 300 }).parts[0].geometry.skyVisibility;+ assert.deepEqual(Array.from(first), Array.from(second));+});++test('parts that carry their own light, a cut-out or a tag are not floors', () => {+ const baked = square('baked', 10, 0, { material: { color: [1, 1, 1], lightMap: {} } });+ const leaves = square('leaves', 10, 0, { material: { color: [1, 1, 1], alphaMode: 'mask' } });+ const water = square('water', 10, 0, { material: { color: [1, 1, 1], tag: 'water' } });+ const own = square('own', 10, 0);+ own.geometry.skyVisibility = new Float32Array(4).fill(1);+ const roof = square('roof', 4, 2, { facing: -1 });+ assert.deepEqual(findFloorParts([baked, leaves, water, own, roof]), []);+});++test('a scene with no floor or nothing above it comes back unchanged', () => {+ const lone = [square('floor', 10, 0)];+ assert.equal(applyFloorSkyVisibility(lone).parts, lone);+ assert.equal(applyFloorSkyVisibility(lone).report.reason, 'nothing above the floor');+ const roofOnly = [square('roof', 4, 2, { facing: -1 }), square('roof-two', 4, 3, { facing: -1 })];+ assert.equal(applyFloorSkyVisibility(roofOnly).report.reason, 'no floor');+});++test('a trace that passes its time limit returns the parts as they were', () => {+ const parts = [square('floor', 10, 0), square('roof', 4, 2, { facing: -1 })];+ const result = applyFloorSkyVisibility(parts, { maxSeconds: 0 });+ assert.equal(result.parts, parts);+ assert.equal(result.report.reason, 'passed maxSeconds');+});diff --git a/vite.lib.config.js b/vite.lib.config.jsindex 9ab697f0..20cd6123 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -43,6 +43,7 @@ export default defineConfig({clutter: 'src/clutter.js','light-bake': 'src/light-bake.js','ground-bounce': 'src/ground-bounce.js',+ 'floor-sky-visibility': 'src/floor-sky-visibility.js','path-tracer': 'src/path-tracer.js','path-tracer-worker': 'src/path-tracer-worker.js','kernel-worker': 'src/kernel-worker.js',