Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Build the coarse water-mirror terrain levels when the scene gets water (part of #316)

Nguyen Xuan Anfa8ddb2a43aa
diff --git a/changes/316-lazy-levels.md b/changes/316-lazy-levels.md
new file mode 100644
index 00000000..8992f41e
--- /dev/null
+++ b/changes/316-lazy-levels.md
@@ -0,0 +1,2 @@
+- A terrain that does not set `mirrorLevels` now builds its coarse water-mirror meshes (up to two halvings the resolution allows) when `applyWaterReflection` finds a water surface in the scene, so an agent needs no flag (part of #316). The levels are built from the heights the terrain already keeps. A terrain in a scene without water builds none of them, and an explicit `mirrorLevels`, 0 included, is kept as given. On the 900 m benchmark terrain the one-time build takes about 130 ms inside `applyWaterReflection`, adds 22 MB of mesh data, and leaves terrain without water at its old memory and build time. With no `mirrorLevels` in the benchmark call the mirror frame costs +25% over reflection off (8.08 against 6.45 ms, 240 samples per variant, RTX 3060), and the picture is pixel for pixel the one made with `mirrorLevels: 2`. The first frame after attaching takes 5.7 ms of GPU time, a normal frame.
+- `scripts/benchmark-water-reflection.mjs` leaves `mirrorLevels` unset unless `--mirror-levels N` is given, and reports the `applyWaterReflection` time, the mirror mesh size and the first frame after attach (part of #316).
diff --git a/changes/316-lazy-levels.size.md b/changes/316-lazy-levels.size.md
new file mode 100644
index 00000000..e534a3ea
--- /dev/null
+++ b/changes/316-lazy-levels.size.md
@@ -0,0 +1,3 @@
+- entry:terrain: +100 bytes gzip (9787 to 9887) for the lazy build hook that builds the mirror meshes when the scene gets water. The lead approved the lazy build; only code that already lives in the terrain module grew.
+- scene:agent-scene+lazy: +90 bytes gzip (359904 to 359994), because the lazy bundle of this scene contains the terrain module. scene:agent-scene itself is -3, entry:core, scene:lit-box and scene:gltf-box are 0.
+- entry:water-reflection: +18 bytes gzip (13036 to 13054) for the call that hands the parts to the terrain hook.
diff --git a/changes/316-terrain-default.md b/changes/316-terrain-default.md
deleted file mode 100644
index 5b6a299e..00000000
--- a/changes/316-terrain-default.md
+++ /dev/null
@@ -1 +0,0 @@
-- docs/terrain.md recommends `createTerrain({ mirrorLevels: 2 })` for terrain near water and gives its cost: about 22 MB more mesh data and 80% more build time on a 900 m terrain, for a mirror frame at +25% instead of +40% over reflection off (part of #316). The default stays 0, because the terrain has no way to know about water.
diff --git a/docs/terrain.md b/docs/terrain.md
index 632e86bf..2569883e 100644
--- a/docs/terrain.md
+++ b/docs/terrain.md
@@ -92,7 +92,7 @@ In a recipe, the same ground is the `terrain` geometry (`size`, `resolution`, `s
## Terrain near water
-`createTerrain({ mirrorLevels: 2 })` builds two extra coarse meshes for each chunk that only the water reflection draws (`attachWaterReflection` hides them from every other draw). Set it for terrain that a reflecting surface will mirror; it stays 0 otherwise because the terrain knows nothing of the water, which a scene adds afterwards. Measured on a 900 m terrain at resolution 128 with 8 by 8 chunks: it adds about 22 MB of mesh data (the finest level is 61 MB) and raises the build time from about 410 ms to 740 ms (median of 5). In return the mirror frame of the water benchmark (960 by 540, RTX 3060, median of 240 samples) costs +25% over reflection off instead of +40%.
+A terrain near water needs nothing set. When `applyWaterReflection` finds a water surface in the scene, every terrain part it is given builds up to two extra coarse meshes per chunk (as many halvings as the resolution allows) that only the water reflection draws; `attachWaterReflection` hides them from every other draw. This is one build of about 130 ms in `applyWaterReflection`, before the renderer exists, so no frame waits for it. Terrain in a scene without water builds nothing extra: its memory and build time are what they were. Pass `mirrorLevels` to choose the count yourself; `mirrorLevels: 0` keeps the plain terrain even next to water, and a number you set is built when the terrain is created, as before. Measured on a 900 m terrain at resolution 128 with 8 by 8 chunks: the levels add about 22 MB of mesh data (the finest level is 61 MB). In return the mirror frame of the water benchmark (960 by 540, RTX 3060, median of 240 samples) costs +25% over reflection off instead of +40%.
## Heightfield from rasters
diff --git a/scripts/benchmark-water-reflection.mjs b/scripts/benchmark-water-reflection.mjs
index ec6116db..c283924c 100644
--- a/scripts/benchmark-water-reflection.mjs
+++ b/scripts/benchmark-water-reflection.mjs
@@ -1,6 +1,6 @@
// Times a lit frame of a large sea with dense terrain and many small parts, with the water reflection off and on, and counts
// what the mirror pass draws. GPU time comes from a native timer query, so run it through the GPU lock:
-// bash ~/.agents/tools/gpu-lock.sh node scripts/benchmark-water-reflection.mjs [--width 1920] [--height 1080] [--parts 20000] [--mirror-levels 2] [--rounds 3] [--stills folder]
+// bash ~/.agents/tools/gpu-lock.sh node scripts/benchmark-water-reflection.mjs [--width 1920] [--height 1080] [--parts 20000] [--mirror-levels N] [--rounds 3] [--stills folder]
// --counts-only skips the timer and runs on SwiftShader, so it needs no GPU lock and prints draw counts only.
// --stills writes a PNG of the lit frame for the off, on and half-scale variants, for a side-by-side check.
// The draw counts (calls, instances, triangles in the mirror pass) do not need the GPU and stay valid when the lock is busy.
@@ -19,7 +19,7 @@ const height = argument('height', 1080);
const smallPartCount = argument('parts', 20000);
const SAMPLES = argument('samples', 20);
const ROUNDS = argument('rounds', 3);
-const mirrorLevels = argument('mirror-levels', 2);
+const mirrorLevels = argument('mirror-levels', undefined);
const countsOnly = process.argv.includes('--counts-only');
const stillsFolder =process.argv.includes('--stills') ? process.argv[process.argv.indexOf('--stills') + 1] : null;
@@ -51,7 +51,10 @@ try {
smallParts.push({ name: `pebble-${index}`, geometry: pebble, matrix: new Float32Array([size, 0, 0, 0, 0, size, 0, 0, 0, 0, size, 0, x, y, z, 1]), material: { tag: 'surface', color: [0.4, 0.38, 0.34], metallic: 0, roughness: 0.8, emission: 0 } });
}
const sea = { name: 'sea', geometry: box(0, 1), matrix: new Float32Array([4000, 0, 0, 0, 0, 1, 0, 0, 0, 0, 4000, 0, 0, -0.5, 0, 1]), material: { tag: 'surface', color: [0.02, 0.06, 0.1], metallic: 0, roughness: 0.04, emission: 0 } };
+ const applyStarted = performance.now();
const marked = applyWaterReflection([...terrain.parts, ...smallParts, sea]);
+ const applyMilliseconds = performance.now() - applyStarted;
+ const mirrorMeshBytes = terrain.parts.reduce((sum, part) => sum + (part.lods ?? []).filter(lod => lod.mirrorOnly).reduce((inner, lod) => inner + lod.geometry.positions.byteLength + lod.geometry.normals.byteLength + lod.geometry.uvs.byteLength + lod.geometry.skyVisibility.byteLength + lod.geometry.indices.byteLength, 0), 0);
const renderer = new Renderer67(canvas, marked.parts, { hdr: true, depth: true, world: true, ground: false, pixelRatio: 1, samples: 4 });
const context = renderer.context;
const timer = context.getExtension('EXT_disjoint_timer_query_webgl2');
@@ -147,6 +150,22 @@ try {
for (const entry of Object.values(report)) {
if (entry?.rawTimings) delete entry.rawTimings;
}
+ report.applyWaterReflectionMilliseconds = applyMilliseconds;
+ report.mirrorMeshMegabytes = mirrorMeshBytes / 1048576;
+ if (!countsOnly) {
+ // The first frame after attaching, on a camera the mirror has not seen: GPU time and wall time, against the "on" median above.
+ const detachFirst = attachWaterReflection(renderer, marked.surface);
+ const query = context.createQuery();
+ const wallStarted = performance.now();
+ context.beginQuery(timer.TIME_ELAPSED_EXT, query);
+ renderer.render({ ...frame, eye: [50, 70, 380], time: 5 });
+ context.endQuery(timer.TIME_ELAPSED_EXT);
+ const wallMilliseconds = performance.now() - wallStarted;
+ context.flush();
+ while (!context.getQueryParameter(query, context.QUERY_RESULT_AVAILABLE)) await new Promise(resolve => setTimeout(resolve, 2));
+ report.attachFrame = { gpuMilliseconds: context.getQueryParameter(query, context.QUERY_RESULT) / 1e6, wallMilliseconds };
+ detachFirst();
+ }
return report;
}, { smallPartCount, samples: SAMPLES, rounds: ROUNDS, wantStills: stillsFolder !== null, countsOnly, mirrorLevels });
if (stillsFolder) {
diff --git a/src/terrain.js b/src/terrain.js
index c2b3204e..631c745e 100644
--- a/src/terrain.js
+++ b/src/terrain.js
@@ -162,6 +162,8 @@ function validateOptions({ size, resolution, chunks, levels, mirrorLevels }) {
}
}
+/** Extra coarse mesh levels a terrain builds for the water mirror when it has water and its `mirrorLevels` is not set. */
+const MIRROR_LEVELS_WITH_WATER = 2;
const SIDES = Object.freeze(['west', 'east', 'north', 'south']);
const MAXIMUM_HOLES = 64;
@@ -193,8 +195,10 @@ function pointInsideHoles(holes, pointX, pointZ) {
* Ground spans x and z from -size / 2 to size / 2. Call update(eye) each frame (or when the camera moves) and, when it
* returns a non-empty list, pass the scene parts to renderer.replaceParts.
*/
-export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels = 4, height, seed = 1, material = DEFAULT_MATERIAL, lodDistance, eye, holes, mirrorLevels = 0 } = {}) {
- validateOptions({ size, resolution, chunks, levels, mirrorLevels });
+export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels = 4, height, seed = 1, material = DEFAULT_MATERIAL, lodDistance, eye, holes, mirrorLevels } = {}) {
+ const mirrorLevelsExplicit = mirrorLevels !== undefined;
+ let activeMirrorLevels = mirrorLevelsExplicit ? mirrorLevels : 0;
+ validateOptions({ size, resolution, chunks, levels, mirrorLevels: activeMirrorLevels });
const holeCircles = normalizeTerrainHoles(holes);
const isHole = (worldX, worldZ) => holeCircles !== null && pointInsideHoles(holeCircles, worldX, worldZ);
const heightFunction = resolveHeightFunction(height, size, seed);
@@ -335,6 +339,8 @@ export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels
for (let chunkColumn = 0; chunkColumn < chunks; chunkColumn++) {
const state = { chunkColumn, chunkRow, level: -1, edgeLevels: null, centerX: origin + (chunkColumn + 0.5) * chunkSize, centerZ: origin + (chunkRow + 0.5) * chunkSize };
state.part = { name: `Terrain chunk ${chunkColumn},${chunkRow}`, geometry: null, matrix: identityMatrix(), material };
+ // Not enumerable, so copies and serialised parts do not carry it. The water reflection addon calls it for the parts it is given.
+ Object.defineProperty(state.part, 'prepareMirrorLevels', { value: prepareMirrorLevels });
chunkStates.push(state);
parts.push(state.part);
}
@@ -431,7 +437,7 @@ export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels
// mirrorLevels must be used with attachWaterReflection.
function buildMirrorLods(state) {
const lods = [{ geometry: state.part.geometry, error: 0 }];
- for (let extra = 1; extra <= mirrorLevels; extra++) {
+ for (let extra = 1; extra <= activeMirrorLevels; extra++) {
const level = state.targetLevel + extra;
const error = Math.max(lods[extra - 1].error, coarseError(state, level));
lods.push({ geometry: buildMirrorGeometry(state.chunkColumn, state.chunkRow, level), error, mirrorOnly: true });
@@ -439,6 +445,18 @@ export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels
return lods;
}
+ // A terrain that did not set mirrorLevels builds no coarse mirror meshes until the water reflection addon is given its parts, so
+ // terrain without water pays nothing. It then takes up to MIRROR_LEVELS_WITH_WATER extra halvings that the resolution allows.
+ // An explicit mirrorLevels, 0 included, is kept as it is.
+ function prepareMirrorLevels() {
+ if (mirrorLevelsExplicit || activeMirrorLevels > 0) return;
+ while (activeMirrorLevels < MIRROR_LEVELS_WITH_WATER && resolution % (2 ** (levels + activeMirrorLevels)) === 0) activeMirrorLevels++;
+ if (activeMirrorLevels === 0) return;
+ for (const state of chunkStates) {
+ if (state.part.geometry) state.part.lods = buildMirrorLods(state);
+ }
+ }
+
let triangleTotal = 0;
function update(eyePosition) {
if (!Array.isArray(eyePosition) && !(eyePosition instanceof Float32Array)) throw new TypeError('update needs an eye position [x, y, z].');
@@ -451,7 +469,7 @@ export function createTerrain({ size = 512, resolution = 32, chunks = 8, levels
if (unchanged) continue;
if (state.part.geometry) triangleTotal -= state.part.geometry.indices.length / 3;
state.part.geometry = buildChunkGeometry(state.chunkColumn, state.chunkRow, state.targetLevel, edgeLevels);
- if (mirrorLevels > 0) state.part.lods = buildMirrorLods(state);
+ if (activeMirrorLevels > 0) state.part.lods = buildMirrorLods(state);
triangleTotal += state.part.geometry.indices.length / 3;
state.level = state.targetLevel;
state.edgeLevels = edgeLevels;
diff --git a/src/water-reflection.js b/src/water-reflection.js
index dc711ceb..c41f6b78 100644
--- a/src/water-reflection.js
+++ b/src/water-reflection.js
@@ -116,6 +116,10 @@ export function applyWaterReflection(parts) {
if (!surface) {
return { parts, surface: null, report: { placed: false, reason: 'no large flat smooth surface' } };
}
+ // Terrain parts build their coarse mirror levels now that the scene has water, before the renderer reads the parts.
+ for (const part of parts) {
+ part.prepareMirrorLevels?.();
+ }
const flagged = new Set(surface.partIndices);
const marked = parts.map((part, index) => (flagged.has(index) ? Object.freeze({ ...part, material: withWaterReflectionFlag(part.material) }) : part));
const report = { placed: true, height: surface.height, parts: surface.partIndices.length, footprint: surface.footprint, sceneShare: surface.sceneShare };
diff --git a/tests/water-reflection.test.js b/tests/water-reflection.test.js
index ee720004..591947c1 100644
--- a/tests/water-reflection.test.js
+++ b/tests/water-reflection.test.js
@@ -2,6 +2,7 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import { box, sphere } from '../src/geometry.js';
import { applyWaterReflection, attachWaterReflection, canReuseMirrorImage, findWaterSurface, waterMirrorLevel, waterMirrorWeight, WATER_BLUR_LIMIT_ROUGHNESS, WATER_MAXIMUM_BLUR_LEVEL, WATER_MIRROR_LOD_SCALE, WATER_MIRROR_MINIMUM_PIXEL_RADIUS } from '../src/water-reflection.js';
+import { createTerrain } from '../src/terrain.js';
import { createFragmentShader } from '../src/shaders.js';
import { Renderer67 } from '../src/renderer.js';
@@ -278,6 +279,54 @@ test('only the mirror draw carries the mirror culling: parts under the plane, co
detach();
});
+function terrainWithSea(terrainOptions) {
+ const terrain = createTerrain({ size: 128, chunks: 2, resolution: 32, levels: 1, height: { amplitude: 4, featureSize: 40 }, seed: 3, ...terrainOptions });
+ const sea = placed('sea', [0, -0.5, 0], [4000, 1, 4000], WATER);
+ return { terrain, parts: [...terrain.parts, sea] };
+}
+
+function mirrorOnlyLevelCount(terrain) {
+ return terrain.parts.reduce((total, part) => total + (part.lods ?? []).filter(lod => lod.mirrorOnly).length, 0);
+}
+
+test('a terrain with no mirrorLevels builds no coarse mirror meshes until the scene gets water', () => {
+ const { terrain, parts } = terrainWithSea({});
+ assert.equal(mirrorOnlyLevelCount(terrain), 0);
+ assert.ok(terrain.parts.every(part => part.lods === undefined));
+ applyWaterReflection(parts);
+ assert.equal(mirrorOnlyLevelCount(terrain), terrain.parts.length * 2);
+ assert.ok(terrain.parts.every(part => part.lods.length === 3 && part.lods[0].geometry === part.geometry));
+});
+
+test('a scene with no water surface leaves the terrain without coarse mirror meshes', () => {
+ const terrain = createTerrain({ size: 128, chunks: 2, resolution: 32, levels: 1, height: { amplitude: 4, featureSize: 40 } });
+ const result = applyWaterReflection(terrain.parts);
+ assert.equal(result.surface, null);
+ assert.equal(mirrorOnlyLevelCount(terrain), 0);
+});
+
+test('an explicit mirrorLevels wins over the lazy default, 0 included', () => {
+ const none = terrainWithSea({ mirrorLevels: 0 });
+ applyWaterReflection(none.parts);
+ assert.equal(mirrorOnlyLevelCount(none.terrain), 0);
+ const one = terrainWithSea({ mirrorLevels: 1 });
+ applyWaterReflection(one.parts);
+ assert.equal(mirrorOnlyLevelCount(one.terrain), one.terrain.parts.length);
+});
+
+test('the lazy levels follow later terrain updates and are built once, and a resolution that allows fewer halvings takes fewer', () => {
+ const { terrain, parts } = terrainWithSea({});
+ applyWaterReflection(parts);
+ const built = terrain.parts.map(part => part.lods);
+ applyWaterReflection(parts);
+ assert.deepEqual(terrain.parts.map(part => part.lods), built);
+ terrain.update([0, 500, 0]);
+ assert.equal(mirrorOnlyLevelCount(terrain), terrain.parts.length * 2);
+ const coarse = terrainWithSea({ resolution: 2 });
+ applyWaterReflection(coarse.parts);
+ assert.equal(mirrorOnlyLevelCount(coarse.terrain), coarse.terrain.parts.length);
+});
+
test('worldBounds equals the per-axis formula it replaced, under a rotated and moved matrix', async () => {
const { worldBounds } = await import('../src/probe-trace.js');
const positions = new Float32Array(3 * 500);