Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.mjs
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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 det
detach();
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,/);
+});