3D engine that AI agents drive
Keep the water mirror for rough water and blur it with roughness (issue #331)
Nguyen Xuan An40b69f380c97
diff --git a/changes/331.md b/changes/331.mdnew file mode 100644index 00000000..d2ab0dfe--- /dev/null+++ b/changes/331.md@@ -0,0 +1 @@+- Rough water keeps its reflection (issue #331). A surface up to roughness 0.5 now gets the mirror pass; above 0.1 the mirror picture is sampled from a coarser mip level, rising linearly to level 5 at 0.5, and from 0.35 it fades out to the environment reflection, so a sea at 0.13 blurs slightly instead of losing every reflection.diff --git a/changes/331.size.md b/changes/331.size.mdnew file mode 100644index 00000000..85d36596--- /dev/null+++ b/changes/331.size.md@@ -0,0 +1 @@+- entry:water-reflection: the roughness blur level, the fade and the mip chain build, about 200 bytes gzip.diff --git a/scripts/measure-water-roughness.mjs b/scripts/measure-water-roughness.mjsnew file mode 100644index 00000000..84f7cedd--- /dev/null+++ b/scripts/measure-water-roughness.mjs@@ -0,0 +1,79 @@+// Draws the sea at several roughnesses, before and after the rough-water reflection (issue #331), as one picture:+// bash ~/.agents/tools/gpu-lock.sh node scripts/measure-water-roughness.mjs --before <checkout without the fix> --preview out/331-preview.png+// The checkout given to --before needs scripts/water-roughness-scene.js copied in, and both need out/assets (see water-preview-scene.js).+import { mkdir, writeFile } from 'node:fs/promises';+import { dirname } from 'node:path';+import { openPage } from './measure-water-shadows.mjs';++const ROUGHNESSES = [0.05, 0.1, 0.13, 0.2, 0.35];+const CELL = { width: 640, height: 360 };+const VIEW = { eye: [-2.5, 0.9, 6], target: [0.2, 0.55, 0] };++async function drawSide(root) {+ const { page, close } = await openPage(root);+ try {+ return await page.evaluate(async ({ roughnesses, cell, view }) => {+ const scene = await import('/scripts/water-roughness-scene.js');+ const preview = await import('/scripts/water-preview-scene.js');+ const assets = await preview.loadPreviewAssets('/out/assets');+ const cells = [];+ for (const roughness of roughnesses) {+ const canvas = document.createElement('canvas');+ canvas.width = cell.width;+ canvas.height = cell.height;+ canvas.style.cssText = `width:${cell.width}px;height:${cell.height}px;display:block`;+ document.body.append(canvas);+ const drawn = scene.drawRoughSea(canvas, assets, roughness, view);+ cells.push({ roughness, placed: drawn.placed, image: canvas.toDataURL('image/png') });+ drawn.dispose();+ canvas.remove();+ }+ return cells;+ }, { roughnesses: ROUGHNESSES, cell: CELL, view: VIEW });+ } finally {+ await close();+ }+}++async function composePreview(rows, outputPath) {+ const { page, close } = await openPage(process.cwd());+ try {+ const dataUrl = await page.evaluate(async ({ rows, cell }) => {+ const label = 26;+ const canvas = document.createElement('canvas');+ canvas.width = cell.width * rows[0].cells.length;+ canvas.height = (cell.height + label) * rows.length;+ const context = canvas.getContext('2d');+ context.fillStyle = '#16181d';+ context.fillRect(0, 0, canvas.width, canvas.height);+ context.font = '16px sans-serif';+ context.fillStyle = '#e8eaf0';+ for (let row = 0; row < rows.length; row++) {+ const top = row * (cell.height + label);+ for (let column = 0; column < rows[row].cells.length; column++) {+ const entry = rows[row].cells[column];+ const image = new Image();+ image.src = entry.image;+ await image.decode();+ context.drawImage(image, column * cell.width, top + label);+ context.fillText(`${rows[row].title}, roughness ${entry.roughness}${entry.placed ? '' : ' (no mirror pass)'}`, column * cell.width + 6, top + 18);+ }+ }+ return canvas.toDataURL('image/png');+ }, { rows, cell: CELL });+ await mkdir(dirname(outputPath), { recursive: true });+ await writeFile(outputPath, Buffer.from(dataUrl.split(',')[1], 'base64'));+ } finally {+ await close();+ }+}++const option = name => (process.argv.includes(name) ? process.argv[process.argv.indexOf(name) + 1] : null);+const previewPath = option('--preview');+const beforeRoot = option('--before');+if (!previewPath || !beforeRoot) {+ throw new Error('usage: measure-water-roughness.mjs --before <checkout> --preview <png>');+}+const rows = [{ title: 'before', cells: await drawSide(beforeRoot) }, { title: 'after', cells: await drawSide(process.cwd()) }];+await composePreview(rows, previewPath);+console.log(`wrote ${previewPath}`);diff --git a/scripts/water-roughness-scene.js b/scripts/water-roughness-scene.jsnew file mode 100644index 00000000..6a4843f4--- /dev/null+++ b/scripts/water-roughness-scene.js@@ -0,0 +1,29 @@+// The scene of the rough water picture (scripts/measure-water-roughness.mjs): a dark sea under the sky, with a boulder, a rock and a+// ladder standing in it. The models are Poly Haven CC0 assets read by water-preview-scene.js from a folder that is never committed.+import { Renderer67 } from '../src/renderer.js';+import { box } from '../src/geometry.js';+import { applyWaterReflection, attachWaterReflection } from '../src/water-reflection.js';+import { previewParts } from './water-preview-scene.js';++const SEA_SIZE = 400;+const unitBox = box(0, 1);++function seaPart(roughness) {+ const matrix = new Float32Array([SEA_SIZE, 0, 0, 0, 0, 0.1, 0, 0, 0, 0, SEA_SIZE, 0, 0, -0.05, 0, 1]);+ return { name: 'sea', geometry: unitBox, matrix, material: { tag: 'surface', color: [0.02, 0.05, 0.08], metallic: 0, roughness, emission: 0 } };+}++/** The standing models of the preview pool with a plain sea in place of its water sheet, which would hide the reflection. */+export function roughSeaParts(assets, roughness) {+ const standing = previewParts(assets, 0.3, {}, 1).slice(1, -1);+ return [...standing, seaPart(roughness)];+}++/** Draws one frame on `canvas` and returns what `applyWaterReflection` decided; the caller reads the canvas before the next frame. */+export function drawRoughSea(canvas, assets, roughness, view) {+ const marked = applyWaterReflection(roughSeaParts(assets, roughness));+ const renderer = new Renderer67(canvas, marked.parts, { hdr: true, depth: true, world: true, ground: false, pixelRatio: 1, samples: 4 });+ const detach = attachWaterReflection(renderer, marked.surface);+ renderer.render({ ...view, fov: 45, time: 0.5 });+ return { placed: marked.report.placed, dispose: () => { detach(); renderer.dispose?.(); } };+}diff --git a/src/water-reflection.js b/src/water-reflection.jsindex 11751132..a953e691 100644--- a/src/water-reflection.js+++ b/src/water-reflection.js@@ -6,8 +6,26 @@ import { worldBounds } from './probe-trace.js';// This module is optional. A scene without such a surface never loads it, and the renderer's only links to it are the material// field `waterReflection`, which batches parts by it, and `frame.reflectionTarget`, which sends one draw into the target.-/** A surface this smooth is a mirror for the scene (sharper than the 0.075 floor the shader gives every material). */+/** A surface this smooth is a sharp mirror for the scene (sharper than the 0.075 floor the shader gives every material). */export const WATER_MAXIMUM_ROUGHNESS = 0.1;+/** Above `WATER_MAXIMUM_ROUGHNESS` the mirror picture blurs with roughness, up to this one. A surface rougher than this is not water and gets no mirror. */+export const WATER_BLUR_LIMIT_ROUGHNESS = 0.5;+/** The mirror picture is sampled this many mip levels down at `WATER_BLUR_LIMIT_ROUGHNESS` (each level halves the picture, so the blur spans about 2^5 target pixels). */+export const WATER_MAXIMUM_BLUR_LEVEL = 5;+/** From this roughness the mirror picture fades out to the environment's own reflection, reaching nothing at `WATER_BLUR_LIMIT_ROUGHNESS`. */+export const WATER_FADE_START_ROUGHNESS = 0.35;++/** The mip level the mirror picture is sampled at for a roughness: 0 up to 0.1, rising linearly to `WATER_MAXIMUM_BLUR_LEVEL` at 0.5. */+export function waterMirrorLevel(roughness) {+ const share = (roughness - WATER_MAXIMUM_ROUGHNESS) / (WATER_BLUR_LIMIT_ROUGHNESS - WATER_MAXIMUM_ROUGHNESS);+ return WATER_MAXIMUM_BLUR_LEVEL * Math.min(Math.max(share, 0), 1);+}++/** How much of the mirror picture shows: 1 up to 0.35, falling linearly to 0 at 0.5 where only the environment is left. */+export function waterMirrorWeight(roughness) {+ const share = (roughness - WATER_FADE_START_ROUGHNESS) / (WATER_BLUR_LIMIT_ROUGHNESS - WATER_FADE_START_ROUGHNESS);+ return 1 - Math.min(Math.max(share, 0), 1);+}/** The surface is flat when its bounds are at most this tall compared with their wider side. */export const WATER_MAXIMUM_THICKNESS_RATIO = 0.02;/** The surface is large when its footprint covers at least this share of the scene's footprint. */@@ -38,7 +56,7 @@ function footprintOf({ minimum, maximum }) {}function isSmoothSurface(material) {- return !EXCLUDED_TAGS.has(material.tag) && !(material.transmission > 0) && (material.roughness ?? 1) <= WATER_MAXIMUM_ROUGHNESS;+ return !EXCLUDED_TAGS.has(material.tag) && !(material.transmission > 0) && (material.roughness ?? 1) < WATER_BLUR_LIMIT_ROUGHNESS;}function isFlatSurface({ minimum, maximum }) {@@ -47,7 +65,7 @@ function isFlatSurface({ minimum, maximum }) {}/**- * The reflecting surface of a scene, or null. A part qualifies when its material is smooth (roughness at most 0.1 and not+ * The reflecting surface of a scene, or null. A part qualifies when its material is smooth (roughness below 0.5, blurred above 0.1, and not* liquid, foam, unlit, fire, smoke or floor), its bounds are flat, and its footprint is at least 0.2% of the scene's. The largest* qualifying part sets the plane (its top); parts within a few centimetres of that height join it.* Returns `{ height, partIndices, footprint, sceneShare }`.@@ -112,6 +130,8 @@ uniform float waterReflectionEnabled;`,// While the mirror image is drawn, nothing under the water plane is part of it.mainSetup: ' if (waterClip.y > 0.5 && worldPosition.y < waterClip.x + ' + CLIP_MARGIN.toFixed(2) + ') discard;\n',+ // Above roughness 0.1 the picture is sampled from a coarser mip level (rougher water, blurrier reflection) and fades to the+ // environment's reflection between 0.35 and 0.5: `waterMirrorLevel` and `waterMirrorWeight` written in GLSL.// The picture holds the light as the frame leaves the shader: scaled by exposure, and encoded when the frame is not HDR.// Still water is not a mirror: small ripples shake the picture (more with distance), a few taps smear it (more up and down,// as ripples stretch a reflection), and Fresnel makes it strong at grazing angles and faint when looking down into the water.@@ -122,16 +142,18 @@ uniform float waterReflectionEnabled;vec3 shaken = worldPosition + vec3(slope.x, 0.0, slope.y) * (1.0 + eyeDistance * ${RIPPLE_REACH});vec4 mirrorClip = waterReflectionMatrix * vec4(shaken, 1.0);vec2 mirrorCentre = mirrorClip.xy / mirrorClip.w * 0.5 + 0.5;+ float mirrorLevel = ${WATER_MAXIMUM_BLUR_LEVEL.toFixed(1)} * clamp((roughness - ${WATER_MAXIMUM_ROUGHNESS.toFixed(2)}) / ${(WATER_BLUR_LIMIT_ROUGHNESS - WATER_MAXIMUM_ROUGHNESS).toFixed(2)}, 0.0, 1.0);+ float mirrorWeight = 1.0 - clamp((roughness - ${WATER_FADE_START_ROUGHNESS.toFixed(2)}) / ${(WATER_BLUR_LIMIT_ROUGHNESS - WATER_FADE_START_ROUGHNESS).toFixed(2)}, 0.0, 1.0);vec3 mirrored = vec3(0.0);for (int tap = 0; tap < ${BLUR_TAPS}; tap++) {float angle = float(tap) * 2.39996;vec2 offset = vec2(cos(angle), sin(angle)) * sqrt((float(tap) + 0.5) / ${BLUR_TAPS}.0);- mirrored += texture(waterReflection, mirrorCentre + offset * vec2(${BLUR_ACROSS}, ${BLUR_DOWN})).rgb;+ mirrored += textureLod(waterReflection, mirrorCentre + offset * vec2(${BLUR_ACROSS}, ${BLUR_DOWN}), mirrorLevel).rgb;}mirrored = (hdrEnabled > 0.5 ? mirrored / ${BLUR_TAPS}.0 : pow(mirrored / ${BLUR_TAPS}.0, vec3(2.2))) / max(exposure, 1e-4);- float fresnelWeight = ${FRESNEL_BASE} + (1.0 - ${FRESNEL_BASE}) * pow(1.0 - max(viewDirection.y, 0.0), 5.0);+ float fresnelWeight = (${FRESNEL_BASE} + (1.0 - ${FRESNEL_BASE}) * pow(1.0 - max(viewDirection.y, 0.0), 5.0)) * mirrorWeight;vec3 skyLight = ENVIRONMENT_ENABLED ? environmentLighting(normal, specularNormal, baseReflectance, viewDirection, reflect(-viewDirection, specularNormal), vec3(0.0), metallic, roughness, occlusion, ambientIntensity, skyReflection) : vec3(0.0);- radiance = ENVIRONMENT_ENABLED ? max(radiance - skyLight, vec3(0.0)) + mirrored * ${REFLECTION_GAIN} * fresnelWeight : mix(radiance, mirrored * ${REFLECTION_GAIN}, fresnelWeight);+ radiance = ENVIRONMENT_ENABLED ? max(radiance - skyLight * mirrorWeight, vec3(0.0)) + mirrored * ${REFLECTION_GAIN} * fresnelWeight : mix(radiance, mirrored * ${REFLECTION_GAIN}, fresnelWeight);}`,}));@@ -143,7 +165,7 @@ function createReflectionTarget(renderer, width, height) {const texture = context.createTexture();context.bindTexture(context.TEXTURE_2D, texture);context.texImage2D(context.TEXTURE_2D, 0, renderer.hdr ? context.RGBA16F : context.RGBA8, width, height, 0, context.RGBA, renderer.hdr ? context.HALF_FLOAT : context.UNSIGNED_BYTE, null);- context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);+ context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR_MIPMAP_LINEAR);context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);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);@@ -256,6 +278,9 @@ function drawMirrorImage(renderer, state, frame, renderFrame) {renderer.mirrorCulling = null;state.drawing = false;}+ // Rougher water samples the coarser levels, so they are built from the finished picture.+ renderer.context.bindTexture(renderer.context.TEXTURE_2D, state.target.texture);+ renderer.context.generateMipmap(renderer.context.TEXTURE_2D);state.matrix.set(renderer.viewProjection);state.drawnFrame = snapshotOf(frame);state.drawnRevision = state.partsRevision;diff --git a/tests/water-reflection.test.js b/tests/water-reflection.test.jsindex a55db195..cb378180 100644--- a/tests/water-reflection.test.js+++ b/tests/water-reflection.test.js@@ -1,7 +1,7 @@import test from 'node:test';import assert from 'node:assert/strict';import { box, sphere } from '../src/geometry.js';-import { applyWaterReflection, attachWaterReflection, findWaterSurface } from '../src/water-reflection.js';+import { applyWaterReflection, attachWaterReflection, findWaterSurface, waterMirrorLevel, waterMirrorWeight, WATER_BLUR_LIMIT_ROUGHNESS, WATER_MAXIMUM_BLUR_LEVEL } from '../src/water-reflection.js';import { createFragmentShader } from '../src/shaders.js';import { Renderer67 } from '../src/renderer.js';@@ -39,7 +39,7 @@ test('a scene with no such surface gets no surface and keeps its parts', () => {test('a surface that is small, tall, rough, liquid or transmissive does not qualify', () => {assert.equal(findWaterSurface([placed('ground', [0, -2, 0], [4000, 2, 4000]), placed('puddle', [0, -1, 0], [20, 0.2, 20], WATER)]), null);assert.equal(findWaterSurface([placed('ground', [0, -2, 0], [4000, 2, 4000]), placed('tower', [0, 50, 0], [900, 400, 900], WATER)]), null);- assert.equal(findWaterSurface(lakeScene({ ...WATER, roughness: 0.3 })), null);+ assert.equal(findWaterSurface(lakeScene({ ...WATER, roughness: 0.6 })), null);assert.equal(findWaterSurface(lakeScene({ ...WATER, tag: 'liquid' })), null);assert.equal(findWaterSurface(lakeScene({ ...WATER, transmission: 0.9 })), null);});@@ -192,3 +192,35 @@ test('updateEvery 2 keeps the picture for one lit frame after each draw, and detdetach();assert.equal(renderer.updateParts.name, 'updateParts');});++test('rougher water keeps the mirror pass and blurs it instead of dropping it', () => {+ for (const roughness of [0.05, 0.1, 0.13, 0.2, 0.35, 0.49]) {+ const result = applyWaterReflection(lakeScene({ ...WATER, roughness }));+ assert.equal(result.report.placed, true, `roughness ${roughness}`);+ assert.deepEqual(result.surface.partIndices, [1]);+ }+ assert.equal(applyWaterReflection(lakeScene({ ...WATER, roughness: WATER_BLUR_LIMIT_ROUGHNESS })).surface, null);+});++test('the mirror level is 0 up to roughness 0.1 and rises continuously to the limit', () => {+ assert.equal(waterMirrorLevel(0.04), 0);+ assert.equal(waterMirrorLevel(0.1), 0);+ assert.ok(waterMirrorLevel(0.13) > 0 && waterMirrorLevel(0.13) < 0.5, 'a step to 0.13 is a small blur, not a jump');+ assert.ok(waterMirrorLevel(0.2) > waterMirrorLevel(0.13));+ assert.ok(waterMirrorLevel(0.35) > waterMirrorLevel(0.2));+ assert.equal(waterMirrorLevel(WATER_BLUR_LIMIT_ROUGHNESS), WATER_MAXIMUM_BLUR_LEVEL);+ assert.equal(waterMirrorLevel(0.9), WATER_MAXIMUM_BLUR_LEVEL);+});++test('the mirror weight is 1 until the fade starts and 0 at the limit', () => {+ assert.equal(waterMirrorWeight(0.13), 1);+ assert.equal(waterMirrorWeight(0.35), 1);+ assert.ok(waterMirrorWeight(0.42) > 0 && waterMirrorWeight(0.42) < 1);+ assert.equal(waterMirrorWeight(WATER_BLUR_LIMIT_ROUGHNESS), 0);+});++test('the shader samples a mip level taken from roughness', () => {+ const source = createFragmentShader(['studioLighting', 'waterReflection']);+ assert.match(source, /float mirrorLevel = 5\.0 \* clamp\(\(roughness - 0\.10\) \/ 0\.40, 0\.0, 1\.0\)/);+ assert.match(source, /textureLod\(waterReflection,/);+});