Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add vegetation impostor levels and dithered cross-fades

Nguyen Xuan An04ec17c4126f
diff --git a/bench/size/budgets.json b/bench/size/budgets.json
index 9f0e6575..433e547e 100644
--- a/bench/size/budgets.json
+++ b/bench/size/budgets.json
@@ -6,13 +6,13 @@
"agent-scene": 100000
},
"budgets": {
- "entry:core": 88890,
+ "entry:core": 89241,
"entry:model": 14400,
"entry:nature": 13200,
"entry:motion": 15260,
"entry:canvas2d": 9400,
- "entry:gltf": 57790,
- "entry:gltf+lazy": 61120,
+ "entry:gltf": 58075,
+ "entry:gltf+lazy": 61402,
"entry:modeling": 8700,
"entry:sculpt": 2500,
"entry:surface": 10100,
@@ -25,7 +25,7 @@
"entry:retarget": 17210,
"entry:skeleton-pose": 20640,
"entry:vehicle": 15764,
- "entry:vegetation": 18600,
+ "entry:vegetation": 22416,
"entry:terrain": 4100,
"entry:navmesh": 3400,
"entry:grass": 4400,
@@ -34,22 +34,22 @@
"entry:ground-bounce": 9460,
"entry:path-tracer": 15960,
"entry:texture-set": 900,
- "entry:agent-scene": 80770,
- "entry:agent-scene+lazy": 263350,
- "entry:agent-asset": 112170,
- "entry:agent-asset+lazy": 274720,
+ "entry:agent-scene": 81053,
+ "entry:agent-scene+lazy": 263630,
+ "entry:agent-asset": 112461,
+ "entry:agent-asset+lazy": 275015,
"entry:hdri": 3300,
"entry:camera-effects": 8600,
- "entry:water-reflection": 26580,
+ "entry:water-reflection": 26869,
"entry:render-passes": 1700,
"entry:gaussian-splats": 11023,
- "entry:material-layer-shaders": 21400,
- "entry:light-linking": 19720,
- "entry:cascaded-shadows": 28530,
- "scene:lit-box": 65870,
- "scene:gltf-box": 90150,
- "scene:gltf-box+lazy": 93480,
- "scene:agent-scene": 109670,
- "scene:agent-scene+lazy": 292250
+ "entry:material-layer-shaders": 21691,
+ "entry:light-linking": 20001,
+ "entry:cascaded-shadows": 28851,
+ "scene:lit-box": 66229,
+ "scene:gltf-box": 90513,
+ "scene:gltf-box+lazy": 93839,
+ "scene:agent-scene": 110042,
+ "scene:agent-scene+lazy": 292625
}
}
diff --git a/changes/324.md b/changes/324.md
new file mode 100644
index 00000000..cfc88d60
--- /dev/null
+++ b/changes/324.md
@@ -0,0 +1 @@
+- Add baked impostor levels and dithered cross-fades to the vegetation addon (issue #324). `selectLevels(instances, eye, { impostors: { from: 3 }, fade: 0.06 })` draws far trees as one camera-facing card from a 64-view hemi-octahedral colour and normal atlas baked on the CPU (0.6 to 0.7 s for five species in Node), lit by the scene and casting a shadow from the light's side, and cross-fades neighbouring levels with the new `alphaMode: 'dither'`, chosen from the distance alone. A 5,223-tree forest drops from 2.68M to 0.52M triangles with cards from level 3 and 0.36M from level 2 (measured in Node). Both are opt-in, so existing scenes draw as before.
diff --git a/docs/culling-lod.md b/docs/culling-lod.md
index 5f74db38..8edc921f 100644
--- a/docs/culling-lod.md
+++ b/docs/culling-lod.md
@@ -32,6 +32,10 @@ An instance uses the coarsest level whose `error` (the farthest its vertices lie
`lods` is refused for the parts that culling skips (the list above), because their levels could not be chosen from a bounding sphere.
+## Cross-fades and impostor levels
+
+`lods` switch a mesh by its pixel error and do not fade. The vegetation addon chooses its own levels by distance (`selectLevels`) and can fade between them: `selectLevels(instances, eye, { fade: 0.06 })` draws both levels near a threshold with complementary screen-door coverage (`alphaMode: 'dither'`, `opacity` and `ditherIncoming` on the material), and `impostors` adds a last level that draws one baked card per tree (material tag `impostor`). Culling treats the card as a rigid part: its bounding sphere holds the quad, and the sway is a few centimetres. Both choices depend on the distance only, so they keep the determinism below; see [Vegetation](/vegetation.md#impostors-and-cross-fade).
+
## Determinism
The selection is a pure function of the geometry, the instance matrices, the camera and the canvas height. It keeps no state between frames, so a seek to any time draws the same instances at the same levels as playing up to it. `tests/render-culling.test.js` checks this on the selection, and `npm run benchmark:runtime` draws the first frame again after every measured frame and fails when the picture differs.
diff --git a/docs/vegetation.md b/docs/vegetation.md
index 772fbe38..cdb92198 100644
--- a/docs/vegetation.md
+++ b/docs/vegetation.md
@@ -116,6 +116,37 @@ When `changed` is true, build a new renderer from the new parts. Grass switches
`vegetationParts(variant, matrix, level, name)` places one tree or clump yourself.
+## Impostors and cross-fade
+
+Both are off by default, so a scene keeps its picture and its hysteresis until it asks.
+
+```js
+import { prepareImpostors, selectLevels } from '67js/addons/vegetation';
+
+prepareImpostors(forest.variants); // bake now, so no frame pays for it
+const view = selectLevels(forest.instances, camera.eye, { impostors: { from: 3 }, fade: 0.06, cullDistance: 900 });
+```
+
+`impostors` (`true` or `{ from, frameSize, level }`) draws every tree from level `from` on (default 3, beyond 150 m) as one card instead of its mesh. `from: 2` starts at 95 m. Bushes and palms take it too; grass and flowers do not. The result gains `impostors` (cards drawn) and `fading` (instances in a cross-fade).
+
+An impostor is baked per tree variant on first use, or by `prepareImpostors(variants)`. `bakeImpostorAtlas` draws the tree from 8 by 8 directions of a hemi-octahedral grid (the upper hemisphere, so a view from below the horizon shows the horizon view) into a colour atlas (sRGB, alpha is the leaf mask) and a normal atlas (linear, the tangent space of that view, green up), each 96 px a frame, on the CPU in plain JavaScript: it runs in Node and the browser alike and the pixels repeat exactly. It bakes level 1 of the tree. Instance tint multiplies the colour like it does on the meshes.
+
+The card is a quad with the `impostor` material tag. The vertex shader (`src/impostor-shader.js`) turns it to the eye, picks the atlas cell nearest the view direction in the tree's own frame (so yaw is respected) and sways its top by `frame.wind`; the standard fragment shader then lights it with the sun, the sky and the shadow map like any other surface, using the baked normals. In the shadow pass the "eye" is the light, so the card casts the tree's shadow as the sun sees it, cutout by the baked leaf mask. The card counts 2 triangles.
+
+`fade` (a fraction of the switch distance, default 0.06 when `impostors` is on) cross-fades two neighbouring levels over a band of that fraction either side of each threshold: both draw, with `alphaMode: 'dither'`, whose coverage in eighths of the way is complementary (a pixel the outgoing level drops is drawn by the incoming one, from the same interleaved-gradient pattern of the screen position). The level and the step come from the distance alone, so a camera position always draws the same picture and a seek repeats. Selection with `fade` or `impostors` keeps no hysteresis, since the band does its job; `changed` is true when any instance moved to another level or step. Shadows draw every level of a fade at full coverage.
+
+Measured (Node, 2026-11-03), 5,223 trees (broadleaf, birch, conifer, bush, 3 variants each) on a 1,550 m square with the eye at its middle at 2 m, so every distance from 0 to 1,100 m occurs:
+
+| Selection | Triangles |
+| --- | --- |
+| Levels only | 2,684,078 |
+| `impostors: { from: 3 }` | 524,870 |
+| `impostors: { from: 2 }` | 358,790 |
+
+Baking one variant each of the five species takes 0.6 to 0.7 s in Node on the CPU (about 0.14 s a variant; 0.1 s a variant with mesh leaves), and 1.4 to 2.6 s for nine variants in headless Chrome on SwiftShader. `npm run smoke:vegetation-impostors` draws a forest with every level, with cards and with fades, and writes the pictures to `artifacts/`.
+
+The depth of each view is used to resolve hidden surfaces while baking but is not stored, and the card shows the nearest single view with no blending between neighbouring views and no parallax, so a tree seen while the camera circles it steps between 64 views. Both are open work on issue #324.
+
## Measured
On the demo clearing (125 trees and bushes, 1,941 grass clumps and 129 flower patches, camera at the clearing edge), headless Chrome with GPU:
@@ -125,5 +156,5 @@ Meshes and textures are built in plain JavaScript, so tests run in Node.
## Limits
- Cards need the renderer's alpha mask to look right. Without `leafTextures` the leaf textures are 128 px procedural sprigs that look flat from under a few metres; the scanned cards hold up to about 1 m. Palm fronds have no scanned card yet. The conifer card is a cedar spray, so it reads as a flat branch tip rather than separate needles.
-- Level changes pop; there is no cross-fade. Level 2 crowns are blobs or crossed cards, not baked imposters.
+- Level changes pop unless `selectLevels` gets `fade`; level 2 crowns are blobs or crossed cards, and baked impostors exist only when asked for (see Impostors and cross-fade).
- Species are fixed presets; there is no seasonal color, wind-bent skeleton or collision with other trees.
diff --git a/package.json b/package.json
index 2ed1dd62..52fff714 100644
--- a/package.json
+++ b/package.json
@@ -101,6 +101,7 @@
"test:isolated": "node scripts/test-each-file.mjs",
"smoke": "node scripts/smoke.mjs",
"smoke:scenes": "node scripts/smoke-scenes.mjs",
+ "smoke:vegetation-impostors": "node scripts/smoke-vegetation-impostors.mjs",
"smoke:transport": "node scripts/smoke-film-transport.mjs",
"render": "node scripts/render-media.mjs",
"score": "node scripts/score.mjs",
diff --git a/scripts/smoke-vegetation-impostors.mjs b/scripts/smoke-vegetation-impostors.mjs
new file mode 100644
index 00000000..43465c0b
--- /dev/null
+++ b/scripts/smoke-vegetation-impostors.mjs
@@ -0,0 +1,97 @@
+// Draws one forest three ways in headless Chrome (SwiftShader unless `--gpu`): every level as it is, with impostor cards
+// from level 2, and with cross-fade bands. Writes the pictures to artifacts/ and checks the cards drew something close
+// to the full trees and that a fade draws both levels.
+import { chromium } from 'playwright';
+import { spawn } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import assert from 'node:assert/strict';
+
+async function evaluateWithRetry(page, task) {
+ for (let attempt = 0; ; attempt++) {
+ try {
+ return await page.evaluate(task);
+ } catch (error) {
+ if (attempt >= 3 || !/context was destroyed/.test(error.message)) throw error;
+ await page.waitForLoadState('load');
+ }
+ }
+}
+
+const port = 5183;
+const useGpu = process.argv.includes('--gpu');
+const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+let browser;
+try {
+ await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => reject(new Error('The smoke server did not start.')), 30000);
+ server.stdout.on('data', (data) => {
+ if (/ready in/.test(data.toString())) { clearTimeout(timeout); resolve(); }
+ });
+ server.on('exit', (code) => { clearTimeout(timeout); reject(new Error(`The smoke server exited ${code}.`)); });
+ });
+ const args = useGpu ? ['--enable-webgl', '--ignore-gpu-blocklist'] : ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'];
+ browser = await chromium.launch({ headless: true, args });
+ const page = await browser.newPage({ viewport: { width: 960, height: 540 } });
+ const errors = [];
+ page.on('pageerror', error => errors.push(error.message));
+ page.on('console', message => { if (message.type() === 'error' && !/404/.test(message.text())) errors.push(message.text()); });
+ await page.goto(`http://127.0.0.1:${port}/`);
+ // Vite reloads the page once when it first optimises a dependency, which destroys a running evaluate.
+ const result = await evaluateWithRetry(page, async () => {
+ const { scatterVegetation, selectLevels, prepareImpostors } = await import('/src/vegetation.js');
+ const { Renderer67 } = await import('/src/renderer.js');
+ const forest = scatterVegetation({ area: { minX: -260, maxX: 260, minZ: -260, maxZ: 260 }, density: 0.0016, mix: { broadleaf: 3, birch: 1.5, conifer: 2 }, seed: 5 });
+ const bake = prepareImpostors(forest.variants);
+ const frame = { eye: [0, 3.5, 250], target: [0, 8, 0], up: [0, 1, 0], fov: 38, near: 0.5, far: 1500, time: 1, wind: 0.3 };
+ const canvas = document.createElement('canvas');
+ canvas.width = 960;
+ canvas.height = 540;
+ document.body.append(canvas);
+ const copy = document.createElement('canvas');
+ copy.width = 960;
+ copy.height = 540;
+ const copyContext = copy.getContext('2d', { willReadFrequently: true });
+ const draw = (view) => {
+ const renderer = new Renderer67(canvas, view.parts, { ground: true, world: true, samples: 1, pixelRatio: 1 });
+ renderer.render(frame);
+ copyContext.drawImage(canvas, 0, 0);
+ const pixels = copyContext.getImageData(0, 0, 960, 540).data;
+ const picture = copy.toDataURL('image/png');
+ renderer.dispose?.();
+ return { pixels, picture };
+ };
+ const plainView = selectLevels(forest.instances, frame.eye, {});
+ const cardView = selectLevels(forest.instances, frame.eye, { impostors: { from: 2 } });
+ const fadeView = selectLevels(forest.instances, frame.eye, { fade: 0.12 });
+ const plain = draw(plainView);
+ const cards = draw(cardView);
+ const fade = draw(fadeView);
+ // A close shot with the card distance scaled down, against the same trees at full detail, shows what a card looks like.
+ const nearFrame = { ...frame, eye: [10, 2.5, 70], target: [0, 5, 0], fov: 50 };
+ Object.assign(frame, nearFrame);
+ const nearTrees = draw(selectLevels(forest.instances, frame.eye, { distanceScale: 100 }));
+ const nearCards = draw(selectLevels(forest.instances, frame.eye, { distanceScale: 0.2, impostors: { from: 2 } }));
+ let difference = 0;
+ for (let index = 0; index < plain.pixels.length; index += 4) {
+ difference += Math.abs(plain.pixels[index] - cards.pixels[index]) + Math.abs(plain.pixels[index + 1] - cards.pixels[index + 1]) + Math.abs(plain.pixels[index + 2] - cards.pixels[index + 2]);
+ }
+ const summary = (view) => ({ triangles: view.triangles, parts: view.parts.length, impostors: view.impostors ?? 0, fading: view.fading ?? 0 });
+ return {
+ trees: forest.instances.length, bake,
+ plain: summary(plainView), cards: summary(cardView), fade: summary(fadeView),
+ meanDifference: difference / (plain.pixels.length / 4 * 3 * 255),
+ pictures: { plain: plain.picture, cards: cards.picture, fade: fade.picture, 'near-trees': nearTrees.picture, 'near-cards': nearCards.picture },
+ };
+ });
+ await mkdir('artifacts', { recursive: true });
+ for (const [name, picture] of Object.entries(result.pictures)) await writeFile(`artifacts/vegetation-impostors-${name}.png`, Buffer.from(picture.split(',')[1], 'base64'));
+ delete result.pictures;
+ console.log(JSON.stringify(result));
+ assert.deepEqual(errors, []);
+ assert.ok(result.cards.impostors > 0 && result.cards.triangles < result.plain.triangles);
+ assert.ok(result.fade.fading > 0);
+ assert.ok(result.meanDifference < 0.08, `cards differ from the trees by ${result.meanDifference}`);
+} finally {
+ await browser?.close();
+ server.kill();
+}
diff --git a/src/impostor-shader.js b/src/impostor-shader.js
new file mode 100644
index 00000000..908e3a2e
--- /dev/null
+++ b/src/impostor-shader.js
@@ -0,0 +1,64 @@
+// GLSL for the `impostor` material tag: one camera-facing card per tree that shows the nearest baked view.
+// The card is a quad with corners (+-radius, centerHeight +- radius, 0) and uv (0..1, 0 at the top), built by
+// vegetation-impostors.js; the shader recovers radius and center height from any one corner, so the card needs no
+// extra attribute. The same function runs in the colour and shadow vertex shaders: in the shadow pass the "eye" is
+// the light, so the card shows the tree as the sun sees it.
+
+import { registerImpostorShaderCode } from './impostor-slots.js';
+
+/** Frames per side of the hemi-octahedral atlas (the atlas holds this many squared views). */
+export const IMPOSTOR_FRAMES = 8;
+/** The value of `material.tag === 'impostor'` in the instance data. */
+export const IMPOSTOR_TAG = 13;
+
+export const impostorShader = `
+// Hemi-octahedral cell of a direction in the tree's own frame; the upper hemisphere fills the square.
+vec2 impostorCell(vec3 localDirection) {
+ vec3 folded = vec3(localDirection.x, max(localDirection.y, 0.0), localDirection.z);
+ folded /= max(abs(folded.x) + folded.y + abs(folded.z), 0.00001);
+ vec2 square = vec2(folded.x + folded.z, folded.x - folded.z) * 0.5 + 0.5;
+ return clamp(floor(square * ${IMPOSTOR_FRAMES}.0), 0.0, ${IMPOSTOR_FRAMES - 1}.0);
+}
+
+// Returns the world position of this corner and the atlas uv of the nearest view. clipMatrix is the matrix of the pass
+// (camera or light); the eye is where it projects to w = 0, or for an orthographic pass a direction.
+vec3 impostorCard(vec3 localPosition, vec2 corner, mat4 modelMatrix, mat4 clipMatrix, float seconds, float strength, out vec2 atlasUv, out vec3 cardNormal) {
+ vec2 side = vec2(corner.x * 2.0 - 1.0, 1.0 - corner.y * 2.0);
+ float radius = abs(localPosition.x);
+ float centerHeight = localPosition.y - side.y * radius;
+ vec3 center = (modelMatrix * vec4(0.0, centerHeight, 0.0, 1.0)).xyz;
+ vec4 apex = inverse(clipMatrix) * vec4(0.0, 0.0, 1.0, 0.0);
+ vec3 toEye = normalize(abs(apex.w) > 0.000001 ? apex.xyz / apex.w - center : -apex.xyz);
+ vec3 right = cross(vec3(0.0, 1.0, 0.0), toEye);
+ float rightLength = length(right);
+ right = rightLength > 0.001 ? right / rightLength : vec3(1.0, 0.0, 0.0);
+ vec3 cardUp = cross(toEye, right);
+ cardNormal = toEye;
+ float scale = length(modelMatrix[0].xyz);
+ vec3 localDirection = normalize(transpose(mat3(modelMatrix)) * toEye);
+ atlasUv = (impostorCell(localDirection) + corner) / ${IMPOSTOR_FRAMES}.0;
+ float heightFraction = side.y * 0.5 + 0.5;
+ float sway = sin(seconds * 1.2 + center.z * 0.31 + center.x * 0.17) * strength * 0.05 * radius * heightFraction * heightFraction;
+ return center + (right * (side.x * radius + sway) + cardUp * side.y * radius) * scale;
+}
+`;
+
+// The hooks sit in main() of the colour and shadow vertex shaders (shaders.js); importing this module installs them.
+registerImpostorShaderCode({
+ declarations: impostorShader,
+ colorHook: ` vec3 impostorNormal = vec3(0.0, 1.0, 0.0);
+ bool isImpostor = USES_IMPOSTOR && instanceSurface.w == ${IMPOSTOR_TAG}.0;
+ if (isImpostor) {
+ vec2 atlasUv;
+ world.xyz = impostorCard(position, uv, instanceMatrix, viewProjection, time, wind, atlasUv, impostorNormal);
+ uv = atlasUv;
+ }
+`,
+ normalHook: ` if (isImpostor) worldNormal = impostorNormal;
+`,
+ depthHook: ` if (instanceSurface.w == ${IMPOSTOR_TAG}.0) {
+ vec3 lightFacing;
+ world.xyz = impostorCard(position, uv, instanceMatrix, lightProjection, time, wind, shadowUv, lightFacing);
+ }
+`,
+});
diff --git a/src/impostor-slots.js b/src/impostor-slots.js
new file mode 100644
index 00000000..0ad7afa6
--- /dev/null
+++ b/src/impostor-slots.js
@@ -0,0 +1,9 @@
+// The GLSL slots that the impostor card fills into the vertex shaders. They live apart from shaders.js so that the
+// vegetation addon can register its code without pulling every shader into its bundle.
+
+export const impostorGlsl = { declarations: '', colorHook: '', normalHook: '', depthHook: '' };
+
+/** Register the GLSL of the impostor card: declarations, colorHook and normalHook (colour pass), depthHook (shadow pass). */
+export function registerImpostorShaderCode(slots) {
+ Object.assign(impostorGlsl, slots);
+}
diff --git a/src/renderer.js b/src/renderer.js
index 8ec77ca2..943477e8 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -1,5 +1,5 @@
import { mat4, mat3 } from 'gl-matrix';
-import { layerTextureSupport, LIGHT_SHADING_FEATURE, SHADING_MODES, LIGHT_SHADING_MAXIMUM_SAMPLES, vertexShader, createVertexShader, createFragmentShader, liquidFragmentShader, depthVertexShader, depthFragmentShader, benchmarkVertexShader, benchmarkFragmentShader } from './shaders.js';
+import { layerTextureSupport, LIGHT_SHADING_FEATURE, SHADING_MODES, LIGHT_SHADING_MAXIMUM_SAMPLES, vertexShader, createVertexShader, createFragmentShader, liquidFragmentShader, createDepthVertexShader, depthFragmentShader, benchmarkVertexShader, benchmarkFragmentShader } from './shaders.js';
import { postFragment, createPostFragment, POST_STEPS, skyFragment, bloomFragment } from './post.js';
import { fullscreenVertex, startProgram, finishProgram, compileProgram } from './gl-program.js';
import { ambientOcclusionFragment } from './ambient-occlusion.js';
@@ -21,14 +21,14 @@ import { resolveShadowLight, shadowBiasPerSlope } from './shadow-light.js';
import { validateMorphGeometry, validateMorphPose, validateMorphTransform, packMorphTargets } from './morph.js';
const SHADOW_MAP_SIZE = 2048;
-const MATERIAL_TAGS = { armor: 1, floor: 2, water: 3, foliage: 4, terrain: 5, grass: 7, fire: 8, smoke: 9, unlit: 10, liquid: 11, foam: 12 };
+const MATERIAL_TAGS = { armor: 1, floor: 2, water: 3, foliage: 4, terrain: 5, grass: 7, fire: 8, smoke: 9, unlit: 10, liquid: 11, foam: 12, impostor: 13 };
// Liquid and foam see the resolved opaque scene, so they draw in their own pass after it.
const TRANSLUCENT_TAGS = new Set(['liquid', 'foam']);
const DEFAULT_LIQUID = Object.freeze({ thickness: 0.5, ior: 1.33, refraction: 1, scattering: 1, foamOpacity: 0.55, foamSoftness: 1 });
const INSTANCE_STRIDE = 41;
// Shaders get this in place of an infinite attenuation distance, which is not a safe uniform value.
const MAX_FINITE_DISTANCE = 3e38;
-const ALPHA_MODES = { opaque: 0, mask: 1, blend: 2 };
+const ALPHA_MODES = { opaque: 0, mask: 1, blend: 2, dither: 3 };
const ZERO_VECTOR = Object.freeze([0, 0, 0]);
const MATERIAL_MAPS = ['map', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
const MAP_UNIFORMS = ['baseMap', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
@@ -55,7 +55,7 @@ function postUniformLocations(context, program) {
const MAP_SHADER_FEATURES = ['baseMap', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
// Tags whose look the main fragment shader draws with code that other tags never reach.
-const TAG_SHADER_FEATURES = new Set(['floor', 'water', 'foliage', 'terrain', 'grass', 'fire', 'smoke', 'unlit']);
+const TAG_SHADER_FEATURES = new Set(['floor', 'water', 'foliage', 'terrain', 'grass', 'fire', 'smoke', 'unlit', 'impostor']);
function shaderFeaturesOfLighting(lighting) {
const features = [];
@@ -187,7 +187,7 @@ function lightMapState(material) {
function validateAlphaMaterial(material) {
const alphaMode = material.alphaMode ?? 'opaque';
- if (!Object.hasOwn(ALPHA_MODES, alphaMode)) throw new Error("alphaMode must be 'opaque', 'mask' or 'blend'.");
+ if (!Object.hasOwn(ALPHA_MODES, alphaMode)) throw new Error("alphaMode must be 'opaque', 'mask', 'blend' or 'dither'.");
for (const field of ['alphaCutoff', 'opacity']) {
const value = material[field] ?? 1;
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${field} must be a number within zero and one.`);
@@ -199,8 +199,9 @@ function validateAlphaMaterial(material) {
function materialAlphaState(material) {
validateAlphaMaterial(material);
const alphaMode = material.alphaMode ?? 'opaque';
- const alphaCutoff = alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : 0;
- const opacity = alphaMode === 'opaque' ? 1 : material.opacity ?? 1;
+ const alphaCutoff = alphaMode === 'mask' || alphaMode === 'dither' ? material.alphaCutoff ?? 0.5 : 0;
+ // A dither fade keeps its pixels in the incoming side's half of the pattern: opacity plus one tells the shader.
+ const opacity = alphaMode === 'opaque' ? 1 : (material.opacity ?? 1) + (alphaMode === 'dither' && material.ditherIncoming === true ? 1 : 0);
return [alphaMode, alphaCutoff, opacity, material.doubleSided === true];
}
@@ -580,7 +581,7 @@ export class Renderer67 {
if (shadowCascades) this.shaderFeatures.add(shadowCascades.shaderFeature);
const pending = {
main: this.startMainProgram(),
- depth: startProgram(this.context, depthVertexShader, depthFragmentShader),
+ depth: startProgram(this.context, createDepthVertexShader(), depthFragmentShader),
};
if (!benchmark) {
pending.post = startProgram(this.context, fullscreenVertex, postFragment);
@@ -1900,12 +1901,14 @@ export class Renderer67 {
} else {
context.enable(context.CULL_FACE);
}
- const masked = batch.alphaMode === 'mask';
+ const dithered = batch.alphaMode === 'dither';
+ const masked = batch.alphaMode === 'mask' || dithered;
if (!textured) {
const uniforms = this.depthAlphaUniforms;
context.uniform1f(uniforms.alphaMasked, masked ? 1 : 0);
context.uniform1f(uniforms.alphaCutoff, batch.alphaCutoff);
- context.uniform1f(uniforms.materialOpacity, batch.opacity);
+ // A fading level still casts its whole shadow.
+ context.uniform1f(uniforms.materialOpacity, dithered ? 1 : batch.opacity);
context.uniform1f(uniforms.hasBaseMap, batch.mapState[0] ? 1 : 0);
if (masked) {
context.activeTexture(context.TEXTURE0 + 1);
@@ -1913,7 +1916,7 @@ export class Renderer67 {
}
return;
}
- const useCoverage = masked && this.samples > 1 && !this.benchmark && !this.renderingPass;
+ const useCoverage = batch.alphaMode === 'mask' && this.samples > 1 && !this.benchmark && !this.renderingPass;
if (useCoverage) {
context.enable(context.SAMPLE_ALPHA_TO_COVERAGE);
} else {
diff --git a/src/shaders.js b/src/shaders.js
index 5ef1c55d..0dde58b0 100644
--- a/src/shaders.js
+++ b/src/shaders.js
@@ -2,6 +2,7 @@ import { MAX_MORPH_TARGETS } from './morph.js';
import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './light-limits.js';
import { environmentLookupGlsl, environmentShadingGlsl } from './environment.js';
import { splatGlsl } from './splat-shader.js';
+import { impostorGlsl } from './impostor-slots.js';
const morphingShader = `
uniform float morphEnabled;
@@ -129,11 +130,12 @@ flat out mat3 boxNormalMatrix;
${skinningShader}
${morphingShader}
${windShader}
+${impostorGlsl.declarations}
void main() {
vec2 uv = uvSets.xy;
mat4 deformation = USES_SKIN ? skinTransform() : mat4(1.0);
vec4 world = instanceMatrix * deformation * vec4(USES_MORPH ? morphedPosition(position) : position, 1.0);
- world.xyz += assemblyOffset * assemblyAmount + assemblyDetailOffset * smoothstep(0.3, 1.0, assemblyAmount);
+${impostorGlsl.colorHook} world.xyz += assemblyOffset * assemblyAmount + assemblyDetailOffset * smoothstep(0.3, 1.0, assemblyAmount);
if (USES_WIND) world.xyz += windOffset(position, world.xyz, uv, instanceSurface.w, time, wind);
if (USES_WAVES && instanceSurface.w == 3.0) {
world.y += sin(world.x * 1.4 + time * 0.8) * 0.025 + sin(world.z * 1.8 - time) * 0.02;
@@ -145,7 +147,7 @@ void main() {
vec3 localNormal = USES_MORPH ? morphedNormal(normal) : normal;
vec3 deformedNormal = USES_SKIN ? transpose(inverse(mat3(deformation))) * localNormal : localNormal;
worldNormal = normalize(instanceNormal * deformedNormal);
- // Metres along the object's own axes, so a pattern follows a moving node and is not stretched by its scale.
+${impostorGlsl.normalHook} // Metres along the object's own axes, so a pattern follows a moving node and is not stretched by its scale.
boxPosition = (USES_MORPH ? morphedPosition(position) : position) * vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));
boxNormal = deformedNormal;
boxNormalMatrix = instanceNormal;
@@ -162,7 +164,8 @@ void main() {
}`;
}
-export const depthVertexShader = `#version 300 es
+function depthVertexShaderSource() {
+ return `#version 300 es
precision highp float;
layout(location=0) in vec3 position;
layout(location=2) in mat4 instanceMatrix;
@@ -178,14 +181,24 @@ out vec2 textureUV;
${skinningShader}
${morphingShader}
${windShader}
+${impostorGlsl.declarations}
void main() {
vec4 world = instanceMatrix * skinTransform() * vec4(morphedPosition(position), 1.0);
world.xyz += assemblyOffset * assemblyAmount + assemblyDetailOffset * smoothstep(0.3, 1.0, assemblyAmount);
// Same displacement as the colour pass, so shadows follow the swaying leaves.
world.xyz += windOffset(position, world.xyz, uv, instanceSurface.w, time, wind);
- textureUV = uv;
+ vec2 shadowUv = uv;
+${impostorGlsl.depthHook} textureUV = shadowUv;
gl_Position = lightProjection * world;
}`;
+}
+
+export const depthVertexShader = depthVertexShaderSource();
+
+/** The shadow vertex shader as it is now, with any registered impostor code (the constant above is built on import). */
+export function createDepthVertexShader() {
+ return depthVertexShaderSource();
+}
// Only masked batches sample the base map, so shadows follow the cutout.
export const depthFragmentShader = `#version 300 es
@@ -662,6 +675,14 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMas
float surfaceAlpha(float textureAlpha) {
if (!USES_ALPHA_MODE) return 1.0;
float alpha = materialOpacity * textureAlpha;
+ if (alphaMode > 2.5) {
+ // Screen-door fade: opacity above 1 marks the incoming side, which keeps the pixels the outgoing side drops.
+ bool incoming = materialOpacity > 1.0;
+ float coverage = incoming ? materialOpacity - 1.0 : materialOpacity;
+ float threshold = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
+ if (textureAlpha < alphaCutoff || (incoming ? coverage < 1.0 - threshold : coverage <= threshold)) discard;
+ return 1.0;
+ }
if (alphaMode > 1.5) return alpha;
if (alphaToCoverage > 0.5) {
float softness = max(fwidth(alpha), 0.0001);
@@ -998,7 +1019,7 @@ export const LIGHT_SHADING_MAXIMUM_SAMPLES = 2;
export const ENVIRONMENT_FEATURES =Object.freeze(['environmentMap', 'studioLighting']);
// Features that only the vertex shader reads: a part with a skeleton or morph targets.
-const VERTEX_ONLY_FEATURES = Object.freeze(['skin', 'morph']);
+const VERTEX_ONLY_FEATURES = Object.freeze(['skin', 'morph', 'impostor']);
function environmentCondition(enabled) {
const hasMap = enabled.has('environmentMap');
@@ -1046,6 +1067,7 @@ function vertexDefinitions(enabled) {
return [
`#define USES_SKIN ${condition(enabled.has('skin'), 'skinEnabled > 0.5')}`,
`#define USES_MORPH ${condition(enabled.has('morph'), 'morphEnabled > 0.5')}`,
+ `#define USES_IMPOSTOR ${condition(enabled.has('impostor') && impostorGlsl.colorHook !== '', 'true')}`,
`#define USES_WIND ${condition(enabled.has('foliage') || enabled.has('grass'), 'true')}`,
`#define USES_WAVES ${condition(enabled.has('water'), 'true')}`,
`#define USES_EXPLOSION ${condition(enabled.has('fire') || enabled.has('smoke'), 'true')}`,
diff --git a/src/vegetation-impostors.js b/src/vegetation-impostors.js
new file mode 100644
index 00000000..f209385f
--- /dev/null
+++ b/src/vegetation-impostors.js
@@ -0,0 +1,398 @@
+// Impostors and cross-fades for vegetation levels.
+//
+// An impostor is a tree drawn as one camera-facing card. `bakeImpostorAtlas` renders the tree from every direction of a
+// hemi-octahedral grid into a colour atlas (RGBA) and a normal atlas (tangent space of the view, OpenGL green up), on the
+// CPU, so it runs in Node and the browser alike and its pixels repeat exactly. The `impostor` material tag in the vertex
+// shader (impostor-shader.js) turns the card to the eye and picks the nearest view. Level changes fade with a screen-door
+// dither (`alphaMode: 'dither'`), chosen from the distance alone, so a seek to any camera repeats the same picture.
+
+import { IMPOSTOR_FRAMES } from './impostor-shader.js';
+
+export const FADE_STEPS = 8;
+export const IMPOSTOR_CARD_TRIANGLES = 2;
+const DEFAULT_FRAME_SIZE = 96;
+const DEFAULT_BAKE_LEVEL = 1;
+const FRAME_MARGIN_PIXELS = 2;
+const EMPTY_BAND = 1e-6;
+
+const impostorCache = new WeakMap();
+
+function srgbToLinear(byte) {
+ const value = byte / 255;
+ return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function linearToSrgbByte(value) {
+ const clamped = Math.min(1, Math.max(0, value));
+ const encoded = clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;
+ return Math.round(encoded * 255);
+}
+
+const SRGB_DECODE = Float32Array.from({ length: 256 }, (_, byte) => srgbToLinear(byte));
+
+/** The direction (unit vector from the tree to the eye, in the tree's frame) that atlas cell `column`, `row` was baked from. */
+export function impostorFrameDirection(column, row) {
+ const squareX = (column + 0.5) / IMPOSTOR_FRAMES * 2 - 1;
+ const squareY = (row + 0.5) / IMPOSTOR_FRAMES * 2 - 1;
+ const x = (squareX + squareY) / 2;
+ const z = (squareX - squareY) / 2;
+ const y = 1 - Math.abs(x) - Math.abs(z);
+ const length = Math.hypot(x, y, z);
+ return [x / length, y / length, z / length];
+}
+
+/** The atlas cell the shader picks for a direction to the eye (the same fold as `impostorCell` in impostor-shader.js). */
+export function impostorCellOf(direction) {
+ const y = Math.max(direction[1], 0);
+ const sum = Math.max(Math.abs(direction[0]) + y + Math.abs(direction[2]), 1e-5);
+ const squareX = ((direction[0] + direction[2]) / sum) * 0.5 + 0.5;
+ const squareY = ((direction[0] - direction[2]) / sum) * 0.5 + 0.5;
+ const clampCell = value => Math.min(IMPOSTOR_FRAMES - 1, Math.max(0, Math.floor(value * IMPOSTOR_FRAMES)));
+ return { column: clampCell(squareX), row: clampCell(squareY) };
+}
+
+/** Right and up of a card that faces `toEye`, as the shader builds them. */
+export function impostorCardBasis(toEye) {
+ let right = [toEye[2], 0, -toEye[0]];
+ const rightLength = Math.hypot(right[0], right[2]);
+ right = rightLength > 0.001 ? [right[0] / rightLength, 0, right[2] / rightLength] : [1, 0, 0];
+ const up = [
+ toEye[1] * right[2] - toEye[2] * right[1],
+ toEye[2] * right[0] - toEye[0] * right[2],
+ toEye[0] * right[1] - toEye[1] * right[0],
+ ];
+ return { right, up };
+}
+
+function prepareParts(variant, level) {
+ return variant.levels[level].parts.map((part) => {
+ const { geometry, material } = part;
+ const map = material.map?.image?.data ? material.map : null;
+ return {
+ geometry, map,
+ wrap: map ? map.wrapS === 10497 : false,
+ baseColor: material.color,
+ cutoff: material.alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : 0,
+ };
+ });
+}
+
+function drawFrame(parts, view, extent, size, buffers) {
+ const { colorPixels, normalPixels, depthBuffer, offset, rowStride } = buffers;
+ const { right, up, toEye, center } = view;
+ const pixelsPerMeter = size / (2 * extent);
+ for (const part of parts) {
+ const { positions, normals, uvs, colors, indices } = part.geometry;
+ const vertexCount = positions.length / 3;
+ const screenX = new Float32Array(vertexCount);
+ const screenY = new Float32Array(vertexCount);
+ const depth = new Float32Array(vertexCount);
+ for (let vertex = 0; vertex < vertexCount; vertex++) {
+ const x = positions[vertex * 3] - center[0];
+ const y = positions[vertex * 3 + 1] - center[1];
+ const z = positions[vertex * 3 + 2] - center[2];
+ screenX[vertex] = (x * right[0] + y * right[1] + z * right[2]) * pixelsPerMeter + size / 2;
+ screenY[vertex] = size / 2 - (x * up[0] + y * up[1] + z * up[2]) * pixelsPerMeter;
+ depth[vertex] = x * toEye[0] + y * toEye[1] + z * toEye[2];
+ }
+ for (let triangle = 0; triangle < indices.length; triangle += 3) {
+ const a = indices[triangle];
+ const b = indices[triangle + 1];
+ const c = indices[triangle + 2];
+ const area = (screenX[b] - screenX[a]) * (screenY[c] - screenY[a]) - (screenX[c] - screenX[a]) * (screenY[b] - screenY[a]);
+ if (Math.abs(area) < 1e-9) continue;
+ const minimumX = Math.max(0, Math.floor(Math.min(screenX[a], screenX[b], screenX[c])));
+ const maximumX = Math.min(size - 1, Math.ceil(Math.max(screenX[a], screenX[b], screenX[c])));
+ const minimumY = Math.max(0, Math.floor(Math.min(screenY[a], screenY[b], screenY[c])));
+ const maximumY = Math.min(size - 1, Math.ceil(Math.max(screenY[a], screenY[b], screenY[c])));
+ for (let pixelY = minimumY; pixelY <= maximumY; pixelY++) {
+ for (let pixelX = minimumX; pixelX <= maximumX; pixelX++) {
+ const sampleX = pixelX + 0.5;
+ const sampleY = pixelY + 0.5;
+ const weightA = ((screenX[b] - sampleX) * (screenY[c] - sampleY) - (screenX[c] - sampleX) * (screenY[b] - sampleY)) / area;
+ const weightB = ((screenX[c] - sampleX) * (screenY[a] - sampleY) - (screenX[a] - sampleX) * (screenY[c] - sampleY)) / area;
+ const weightC = 1 - weightA - weightB;
+ if (weightA < 0 || weightB < 0 || weightC < 0) continue;
+ const pixelDepth = weightA * depth[a] + weightB * depth[b] + weightC * depth[c];
+ const bufferIndex = pixelY * size + pixelX;
+ if (pixelDepth <= depthBuffer[bufferIndex]) continue;
+ let red = part.baseColor[0];
+ let green = part.baseColor[1];
+ let blue = part.baseColor[2];
+ if (colors) {
+ red *= weightA * colors[a * 3] + weightB * colors[b * 3] + weightC * colors[c * 3];
+ green *= weightA * colors[a * 3 + 1] + weightB * colors[b * 3 + 1] + weightC * colors[c * 3 + 1];
+ blue *= weightA * colors[a * 3 + 2] + weightB * colors[b * 3 + 2] + weightC * colors[c * 3 + 2];
+ }
+ if (part.map) {
+ const u = weightA * uvs[a * 2] + weightB * uvs[b * 2] + weightC * uvs[c * 2];
+ const v = weightA * uvs[a * 2 + 1] + weightB * uvs[b * 2 + 1] + weightC * uvs[c * 2 + 1];
+ const texel = sampleTexel(part.map, u, v, part.wrap);
+ if (texel.alpha / 255 < part.cutoff) continue;
+ red *= texel.red;
+ green *= texel.green;
+ blue *= texel.blue;
+ }
+ let normalX = weightA * normals[a * 3] + weightB * normals[b * 3] + weightC * normals[c * 3];
+ let normalY = weightA * normals[a * 3 + 1] + weightB * normals[b * 3 + 1] + weightC * normals[c * 3 + 1];
+ let normalZ = weightA * normals[a * 3 + 2] + weightB * normals[b * 3 + 2] + weightC * normals[c * 3 + 2];
+ const normalLength = Math.hypot(normalX, normalY, normalZ) || 1;
+ normalX /= normalLength;
+ normalY /= normalLength;
+ normalZ /= normalLength;
+ const facing = normalX * toEye[0] + normalY * toEye[1] + normalZ * toEye[2];
+ const flip = facing < 0 ? -1 : 1;
+ const tangentX = (normalX * right[0] + normalY * right[1] + normalZ * right[2]) * flip;
+ const tangentY = (normalX * up[0] + normalY * up[1] + normalZ * up[2]) * flip;
+ const tangentZ = Math.abs(facing);
+ depthBuffer[bufferIndex] = pixelDepth;
+ const colorIndex = offset + pixelY * rowStride + pixelX * 4;
+ colorPixels[colorIndex] = linearToSrgbByte(red);
+ colorPixels[colorIndex + 1] = linearToSrgbByte(green);
+ colorPixels[colorIndex + 2] = linearToSrgbByte(blue);
+ colorPixels[colorIndex + 3] = 255;
+ normalPixels[colorIndex] = Math.round((tangentX * 0.5 + 0.5) * 255);
+ normalPixels[colorIndex + 1] = Math.round((tangentY * 0.5 + 0.5) * 255);
+ normalPixels[colorIndex + 2] = Math.round((tangentZ * 0.5 + 0.5) * 255);
+ normalPixels[colorIndex + 3] = 255;
+ }
+ }
+ }
+ }
+}
+
+const sampledTexel = { red: 0, green: 0, blue: 0, alpha: 0 };
+
+function sampleTexel(map, u, v, wrap) {
+ const { width, height, data } = map.image;
+ const fractionU = wrap ? u - Math.floor(u) : Math.min(1, Math.max(0, u));
+ const fractionV = wrap ? v - Math.floor(v) : Math.min(1, Math.max(0, v));
+ const x = Math.min(width - 1, Math.floor(fractionU * width));
+ const y = Math.min(height - 1, Math.floor(fractionV * height));
+ const index = (y * width + x) * 4;
+ sampledTexel.red = SRGB_DECODE[data[index]];
+ sampledTexel.green = SRGB_DECODE[data[index + 1]];
+ sampledTexel.blue = SRGB_DECODE[data[index + 2]];
+ sampledTexel.alpha = data[index + 3];
+ return sampledTexel;
+}
+
+// Empty pixels take the colour of a covered neighbour (alpha stays 0), so mip levels and filtering never pull in black.
+function bleedColors(colorPixels, size, frameColumn, frameRow, atlasWidth) {
+ const rowStride = atlasWidth * 4;
+ const origin = frameRow * size * rowStride + frameColumn * size * 4;
+ for (let pass = 0; pass < 3; pass++) {
+ const filled = [];
+ for (let pixelY = 0; pixelY < size; pixelY++) {
+ for (let pixelX = 0; pixelX < size; pixelX++) {
+ const index = origin + pixelY * rowStride + pixelX * 4;
+ if (colorPixels[index + 3] !== 0) continue;
+ for (const [stepX, stepY] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+ const neighborX = pixelX + stepX;
+ const neighborY = pixelY + stepY;
+ if (neighborX < 0 || neighborY < 0 || neighborX >= size || neighborY >= size) continue;
+ const neighbor = origin + neighborY * rowStride + neighborX * 4;
+ if (colorPixels[neighbor + 3] === 0) continue;
+ filled.push([index, neighbor]);
+ break;
+ }
+ }
+ }
+ for (const [index, neighbor] of filled) {
+ colorPixels[index] = colorPixels[neighbor];
+ colorPixels[index + 1] = colorPixels[neighbor + 1];
+ colorPixels[index + 2] = colorPixels[neighbor + 2];
+ colorPixels[index + 3] = 1;
+ }
+ }
+ for (let pixelY = 0; pixelY < size; pixelY++) {
+ for (let pixelX = 0; pixelX < size; pixelX++) {
+ const index = origin + pixelY * rowStride + pixelX * 4;
+ if (colorPixels[index + 3] === 1) colorPixels[index + 3] = 0;
+ }
+ }
+}
+
+/**
+ * Bakes `variant` (a tree from `createTree`) into atlases of IMPOSTOR_FRAMES squared views, `frameSize` pixels each.
+ * Returns the pixels of the colour and normal atlas and the card: `radius` and `centerHeight` in the tree's meters.
+ */
+export function bakeImpostorAtlas(variant, { frameSize = DEFAULT_FRAME_SIZE, level = DEFAULT_BAKE_LEVEL } = {}) {
+ const minimum = variant.bounds.minimum;
+ const maximum = variant.bounds.maximum;
+ const center = [(minimum[0] + maximum[0]) / 2, (minimum[1] + maximum[1]) / 2, (minimum[2] + maximum[2]) / 2];
+ const radius = Math.hypot(maximum[0] - minimum[0], maximum[1] - minimum[1], maximum[2] - minimum[2]) / 2;
+ const cardRadius = radius * frameSize / (frameSize - 2 * FRAME_MARGIN_PIXELS);
+ const atlasWidth = frameSize * IMPOSTOR_FRAMES;
+ const colorPixels = new Uint8ClampedArray(atlasWidth * atlasWidth * 4);
+ const normalPixels = new Uint8ClampedArray(atlasWidth * atlasWidth * 4);
+ for (let index = 0; index < normalPixels.length; index += 4) {
+ normalPixels[index] = 128;
+ normalPixels[index + 1] = 128;
+ normalPixels[index + 2] = 255;
+ normalPixels[index + 3] = 255;
+ }
+ const parts = prepareParts(variant, level);
+ const depthBuffer = new Float32Array(frameSize * frameSize);
+ for (let row = 0; row < IMPOSTOR_FRAMES; row++) {
+ for (let column = 0; column < IMPOSTOR_FRAMES; column++) {
+ const toEye = impostorFrameDirection(column, row);
+ const { right, up } = impostorCardBasis(toEye);
+ depthBuffer.fill(-Infinity);
+ const offset = row * frameSize * atlasWidth * 4 + column * frameSize * 4;
+ drawFrame(parts, { right, up, toEye, center }, cardRadius, frameSize, { colorPixels, normalPixels, depthBuffer, offset, rowStride: atlasWidth * 4 });
+ bleedColors(colorPixels, frameSize, column, row, atlasWidth);
+ }
+ }
+ return { width: atlasWidth, height: atlasWidth, colorPixels, normalPixels, radius: cardRadius, centerHeight: center[1], center, frameSize };
+}
+
+function textureDescriptor(pixels, size, colorSpace) {
+ const data = pixels;
+ const image = typeof ImageData === 'undefined' ? { width: size, height: size, data } : new ImageData(data, size, size);
+ return { image, colorSpace, wrapS: 33071, wrapT: 33071, minFilter: 9987, magFilter: 9729 };
+}
+
+function cardGeometry(radius, centerHeight) {
+ return {
+ positions: new Float32Array([-radius, centerHeight + radius, 0, radius, centerHeight + radius, 0, radius, centerHeight - radius, 0, -radius, centerHeight - radius, 0]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ };
+}
+
+/** The impostor of a tree variant: `{ geometry, material, bakeMilliseconds }`, baked once and cached on the variant. */
+export function getImpostor(variant, options = {}) {
+ const cached = impostorCache.get(variant);
+ if (cached) return cached;
+ const started = performance.now();
+ const atlas = bakeImpostorAtlas(variant, options);
+ const impostor = {
+ geometry: cardGeometry(atlas.radius, atlas.centerHeight),
+ material: {
+ tag: 'impostor', color: [1, 1, 1], roughness: 0.9, metallic: 0, emission: 0,
+ map: textureDescriptor(atlas.colorPixels, atlas.width, 'srgb'),
+ normalMap: textureDescriptor(atlas.normalPixels, atlas.width, 'linear'),
+ alphaMode: 'mask', alphaCutoff: 0.5, doubleSided: true,
+ },
+ atlasSize: atlas.width,
+ bakeMilliseconds: 0,
+ };
+ impostor.bakeMilliseconds = performance.now() - started;
+ impostorCache.set(variant, impostor);
+ return impostor;
+}
+
+/**
+ * Bakes the impostor of every tree variant now, so no frame pays for it. `variants` is `forest.variants` (species to
+ * variant arrays) or a list of variants. Returns `{ count, milliseconds }`.
+ */
+export function prepareImpostors(variants, options = {}) {
+ const list = Array.isArray(variants) ? variants : Object.values(variants).flat();
+ const started = performance.now();
+ let count = 0;
+ for (const variant of list) {
+ if (variant.kind !== 'tree') continue;
+ getImpostor(variant, options);
+ count++;
+ }
+ return { count, milliseconds: performance.now() - started };
+}
+
+/**
+ * Where a distance falls among level `thresholds`, with a cross-fade of `band` (a fraction) around each one.
+ * Returns `{ level, next, step }`: `step` of FADE_STEPS eighths of the way from `level` to `next`; 0 means only `level`.
+ * It depends on the distance alone, so a given camera always gives the same answer.
+ */
+export function blendLevels(distance, thresholds, band) {
+ for (let index = 0; index < thresholds.length; index++) {
+ const low = thresholds[index] * (1 - band);
+ const high = thresholds[index] * (1 + band);
+ if (distance < low || (high - low < EMPTY_BAND && distance < thresholds[index])) return { level: index, next: index, step: 0 };
+ if (distance <= high && high - low >= EMPTY_BAND) {
+ const step = Math.round((distance - low) / (high - low) * FADE_STEPS);
+ if (step <= 0) return { level: index, next: index, step: 0 };
+ if (step >= FADE_STEPS) return { level: index + 1, next: index + 1, step: 0 };
+ return { level: index, next: index + 1, step };
+ }
+ }
+ return { level: thresholds.length, next: thresholds.length, step: 0 };
+}
+
+function tintedMaterial(material, tintable, tint) {
+ return tintable ? { ...material, color: material.color.map((channel, axis) => channel * tint[axis]) } : material;
+}
+
+function fadedMaterial(material, opacity, incoming) {
+ return { ...material, alphaMode: 'dither', alphaCutoff: material.alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : 0.5, opacity, ditherIncoming: incoming };
+}
+
+function blendParts(instance, level, useImpostor, fade, options) {
+ const key = `${useImpostor ? 'i' : level}|${fade ? `${fade.opacity}|${fade.incoming}` : ''}`;
+ instance.blendParts ??= new Map();
+ if (instance.blendParts.has(key)) return instance.blendParts.get(key);
+ const label = `${instance.species} ${instance.index}`;
+ const fadeMaterial = material => (fade ? fadedMaterial(material, fade.opacity, fade.incoming) : material);
+ let parts;
+ if (useImpostor) {
+ const impostor = getImpostor(instance.variant, options);
+ parts = [{ name: `${label} impostor`, geometry: impostor.geometry, matrix: instance.matrix, material: fadeMaterial(tintedMaterial(impostor.material, true, instance.tint)) }];
+ } else {
+ parts = instance.variant.levels[level].parts.map(part => ({
+ name: `${label} ${part.role}`, geometry: part.geometry, shadowLods: part.shadowLods, matrix: instance.matrix,
+ material: fadeMaterial(tintedMaterial(part.material, part.tintable, instance.tint)),
+ }));
+ }
+ instance.blendParts.set(key, parts);
+ return parts;
+}
+
+/**
+ * `selectLevels` with cross-fades and impostors: the level comes from the distance alone (no hysteresis), and within
+ * `fade` (a fraction of a threshold, either side) two levels draw with complementary dither coverage.
+ * `impostors` is `true` or `{ from, frameSize, level }`: levels from `from` (default 3, the last) draw the baked card.
+ */
+export function selectBlendedLevels(instances, eye, { distanceScale = 1, fade = 0.06, cullDistance = Infinity, impostors = false } = {}) {
+ const impostorOptions = impostors && typeof impostors === 'object' ? impostors : {};
+ const firstImpostorLevel = impostors ? impostorOptions.from ?? 3 : Infinity;
+ const parts = [];
+ const levelCounts = [];
+ let changed = false;
+ let culled = 0;
+ let triangles = 0;
+ let cards = 0;
+ let fading = 0;
+ for (const instance of instances) {
+ const distance = Math.hypot(eye[0] - instance.position[0], eye[1] - instance.position[1], eye[2] - instance.position[2]);
+ const culledNow = distance > cullDistance;
+ const thresholds = instance.variant.distances.map(threshold => threshold * distanceScale);
+ const blend = culledNow ? { level: -1, next: -1, step: 0 } : blendLevels(distance, thresholds, fade);
+ const usesCard = level => instance.variant.kind === 'tree' && level >= firstImpostorLevel;
+ const bothCards = blend.step > 0 && usesCard(blend.level) && usesCard(blend.next);
+ const step = bothCards ? 0 : blend.step;
+ const signature = `${blend.level}:${step > 0 ? blend.next : blend.level}:${step}`;
+ if (signature !== instance.blendSignature) changed = true;
+ instance.blendSignature = signature;
+ instance.level = blend.level;
+ if (blend.level < 0) {
+ culled++;
+ continue;
+ }
+ levelCounts[blend.level] = (levelCounts[blend.level] ?? 0) + 1;
+ const drawLevel = (level, opacity, incoming) => {
+ const useImpostor = usesCard(level);
+ parts.push(...blendParts(instance, level, useImpostor, opacity === 1 ? null : { opacity, incoming }, impostorOptions));
+ triangles += useImpostor ? IMPOSTOR_CARD_TRIANGLES : instance.variant.levels[level].triangles;
+ if (useImpostor) cards++;
+ };
+ if (step === 0) {
+ drawLevel(blend.level, 1, false);
+ } else {
+ fading++;
+ drawLevel(blend.level, 1 - step / FADE_STEPS, false);
+ drawLevel(blend.next, step / FADE_STEPS, true);
+ }
+ }
+ return { parts, changed, levelCounts: Array.from(levelCounts, count => count ?? 0), culled, triangles, impostors: cards, fading };
+}
diff --git a/src/vegetation.js b/src/vegetation.js
index 49668bdf..2bfd1e88 100644
--- a/src/vegetation.js
+++ b/src/vegetation.js
@@ -16,6 +16,10 @@ import {
import { computeCrownSkyVisibility } from './tree-sky.js';
import { LEVEL_SETTINGS, SPECIES, TREE_LEVEL_DISTANCES } from './vegetation-species.js';
import { barkTextureDescriptor, leafTextureDescriptor } from './vegetation-textures.js';
+import { selectBlendedLevels } from './vegetation-impostors.js';
+
+export { prepareImpostors, getImpostor, bakeImpostorAtlas, blendLevels } from './vegetation-impostors.js';
+const DEFAULT_FADE_BAND = 0.06;
export { SPECIES };
@@ -741,9 +745,11 @@ function nextLevel(currentLevel, distance, thresholds, hysteresis, cullDistance)
/**
* Picks a level of detail per instance from its distance to `eye`. A level changes only after the
* distance passes its threshold by `hysteresis` (a fraction), so instances at a boundary do not flicker.
+ * `fade` (a fraction, such as 0.06) cross-fades neighbouring levels with a dither; `impostors` (`true` or `{ from }`) draws the baked card from level `from` (default 3) on. Either one picks the level from the distance alone, with no hysteresis.
* Returns `{ parts, changed, levelCounts, culled, triangles }` (`culled` counts instances past `cullDistance`); rebuild or update the renderer when `changed` is true.
*/
-export function selectLevels(instances, eye, { distanceScale = 1, hysteresis = 0.12, cullDistance = Infinity } = {}) {
+export function selectLevels(instances, eye, { distanceScale = 1, hysteresis = 0.12, cullDistance = Infinity, fade = 0, impostors = false } = {}) {
+ if (fade > 0 || impostors) return selectBlendedLevels(instances, eye, { distanceScale, fade: fade || DEFAULT_FADE_BAND, cullDistance, impostors });
const parts = [];
const levelCounts = [];
let changed = false;
diff --git a/tests/vegetation-impostors.test.js b/tests/vegetation-impostors.test.js
new file mode 100644
index 00000000..30741a32
--- /dev/null
+++ b/tests/vegetation-impostors.test.js
@@ -0,0 +1,153 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { createTree, scatterVegetation, selectLevels } from '../src/vegetation.js';
+import {
+ bakeImpostorAtlas, blendLevels, FADE_STEPS, getImpostor, impostorCardBasis, impostorCellOf, impostorFrameDirection, selectBlendedLevels,
+} from '../src/vegetation-impostors.js';
+import { IMPOSTOR_FRAMES, impostorShader } from '../src/impostor-shader.js';
+import { createDepthVertexShader, createFragmentShader, createVertexShader } from '../src/shaders.js';
+
+const FAST_BAKE = { frameSize: 32 };
+const THRESHOLDS = [38, 95, 150];
+
+function digestOf(pixels) {
+ return createHash('sha256').update(pixels).digest('hex');
+}
+
+function createForest(treeCount, seed = 5) {
+ const side = Math.sqrt(treeCount / 0.0035);
+ const forest = scatterVegetation({ area: { minX: -side / 2, maxX: side / 2, minZ: -side / 2, maxZ: side / 2 }, density: 0.0035, mix: { broadleaf: 3, birch: 1.5, conifer: 2, bush: 2 }, seed });
+ return forest;
+}
+
+test('every atlas cell is picked from the direction it was baked from', () => {
+ for (let row = 0; row < IMPOSTOR_FRAMES; row++) {
+ for (let column = 0; column < IMPOSTOR_FRAMES; column++) {
+ const direction = impostorFrameDirection(column, row);
+ assert.ok(Math.abs(Math.hypot(...direction) - 1) < 1e-9);
+ assert.ok(direction[1] > 0);
+ assert.deepEqual(impostorCellOf(direction), { column, row });
+ }
+ }
+});
+
+test('the card basis is orthonormal and falls back straight above the tree', () => {
+ for (const toEye of [[0.6, 0.5, -0.62], [0, 1, 0], [1, 0.01, 0]]) {
+ const length = Math.hypot(...toEye);
+ const direction = toEye.map(value => value / length);
+ const { right, up } = impostorCardBasis(direction);
+ const dot = (first, second) => first[0] * second[0] + first[1] * second[1] + first[2] * second[2];
+ assert.ok(Math.abs(dot(right, up)) < 1e-9);
+ assert.ok(Math.abs(dot(right, direction)) < 1e-9);
+ assert.ok(Math.abs(dot(up, direction)) < 1e-9);
+ assert.ok(Math.abs(Math.hypot(...up) - 1) < 1e-9);
+ }
+});
+
+test('an atlas bake covers the tree, repeats exactly and keeps unit normals', () => {
+ const tree = createTree('broadleaf', 4);
+ const first = bakeImpostorAtlas(tree, { ...FAST_BAKE, level: 2 });
+ const second = bakeImpostorAtlas(tree, { ...FAST_BAKE, level: 2 });
+ assert.equal(digestOf(first.colorPixels), digestOf(second.colorPixels));
+ assert.equal(digestOf(first.normalPixels), digestOf(second.normalPixels));
+ let covered = 0;
+ for (let index = 3; index < first.colorPixels.length; index += 4) if (first.colorPixels[index] === 255) covered++;
+ const share = covered / (first.colorPixels.length / 4);
+ assert.ok(share > 0.05 && share < 0.6, `covered share ${share}`);
+ for (let index = 0; index < first.normalPixels.length; index += 4) {
+ if (first.colorPixels[index + 3] !== 255) continue;
+ const x = first.normalPixels[index] / 255 * 2 - 1;
+ const y = first.normalPixels[index + 1] / 255 * 2 - 1;
+ const z = first.normalPixels[index + 2] / 255 * 2 - 1;
+ assert.ok(z > -0.02, 'a baked normal never faces away from the view');
+ assert.ok(Math.abs(Math.hypot(x, y, z) - 1) < 0.05);
+ }
+});
+
+test('the impostor card holds the tree and carries the impostor tag', () => {
+ const tree = createTree('conifer', 2);
+ const impostor = getImpostor(tree, { ...FAST_BAKE, level: 2 });
+ assert.equal(getImpostor(tree), impostor, 'the bake is cached on the variant');
+ assert.equal(impostor.material.tag, 'impostor');
+ assert.equal(impostor.geometry.indices.length, 6);
+ assert.ok(impostor.geometry.positions[0] < 0 && impostor.geometry.positions[3] > 0);
+ assert.ok(impostor.bakeMilliseconds > 0);
+});
+
+test('a distance gives the same blend whatever came before, with eighths between two levels', () => {
+ const band = 0.06;
+ assert.deepEqual(blendLevels(10, THRESHOLDS, band), { level: 0, next: 0, step: 0 });
+ assert.deepEqual(blendLevels(500, THRESHOLDS, band), { level: 3, next: 3, step: 0 });
+ assert.deepEqual(blendLevels(38, THRESHOLDS, band), { level: 0, next: 1, step: FADE_STEPS / 2 });
+ let previousStep = 0;
+ for (let distance = 35; distance < 41.5; distance += 0.05) {
+ const blend = blendLevels(distance, THRESHOLDS, band);
+ assert.deepEqual(blend, blendLevels(distance, THRESHOLDS, band));
+ const fraction = blend.level === 1 ? FADE_STEPS : blend.step;
+ assert.ok(fraction >= previousStep, 'the fade only moves one way as the distance grows');
+ previousStep = fraction;
+ }
+ assert.equal(previousStep, FADE_STEPS);
+});
+
+test('a fade draws both levels with complementary coverage and repeats for a camera', () => {
+ const forest = createForest(300);
+ const instance = forest.instances.find(candidate => candidate.variant.kind === 'tree');
+ const eye = [instance.position[0] + 38, instance.position[1], instance.position[2]];
+ const direct = selectBlendedLevels([instance], eye, { fade: 0.06 });
+ assert.equal(direct.fading, 1);
+ const outgoing = direct.parts.filter(part => part.material.alphaMode === 'dither' && !part.material.ditherIncoming);
+ const incoming = direct.parts.filter(part => part.material.ditherIncoming);
+ assert.ok(outgoing.length > 0 && incoming.length > 0);
+ assert.ok(Math.abs(outgoing[0].material.opacity + incoming[0].material.opacity - 1) < 1e-9);
+ selectBlendedLevels([instance], [instance.position[0] + 300, 0, instance.position[2]], { fade: 0.06 });
+ const after = selectBlendedLevels([instance], eye, { fade: 0.06 });
+ assert.deepEqual(after.parts.map(part => [part.name, part.material.opacity, part.material.ditherIncoming]), direct.parts.map(part => [part.name, part.material.opacity, part.material.ditherIncoming]));
+ assert.equal(selectBlendedLevels([instance], eye, { fade: 0.06 }).changed, false);
+ assert.equal(selectBlendedLevels([instance], eye, { fade: 0.06 }).parts[0], direct.parts[0], 'unchanged parts keep their identity');
+});
+
+test('selectLevels keeps its hysteresis path unless fade or impostors are asked for', () => {
+ const forest = createForest(200);
+ const eye = [0, 2, 0];
+ const plain = selectLevels(forest.instances, eye, {});
+ assert.equal(plain.impostors, undefined);
+ assert.ok(plain.parts.every(part => part.material.tag !== 'impostor' && part.material.alphaMode !== 'dither'));
+});
+
+test('impostors replace the last level only beyond its fade band', () => {
+ const forest = createForest(600);
+ const eye = [0, 2, 0];
+ const view = selectLevels(forest.instances, eye, { impostors: { ...FAST_BAKE } });
+ const cards = view.parts.filter(part => part.material.tag === 'impostor');
+ assert.equal(cards.length, view.impostors);
+ assert.ok(cards.length > 0);
+ for (const instance of forest.instances) {
+ const distance = Math.hypot(instance.position[0], instance.position[1] - 2, instance.position[2]);
+ const hasCard = view.parts.some(part => part.name.startsWith(`${instance.species} ${instance.index} `) && part.material.tag === 'impostor');
+ if (instance.variant.kind !== 'tree') continue;
+ if (distance < 150 * 0.94) assert.equal(hasCard, false, `${distance} m draws a mesh level`);
+ if (distance > 150 * 1.06) assert.equal(hasCard, true, `${distance} m draws a card`);
+ }
+});
+
+test('a 5,000 tree forest draws far fewer triangles with impostors', () => {
+ const forest = createForest(5000);
+ const eye = [0, 2, 0];
+ const plain = selectLevels(forest.instances, eye, {});
+ const withCards = selectLevels(forest.instances, eye, { impostors: { ...FAST_BAKE } });
+ const earlyCards = selectLevels(forest.instances, eye, { impostors: { ...FAST_BAKE, from: 2 } });
+ console.log(`trees ${forest.instances.length}, triangles plain ${plain.triangles}, cards from level 3 ${withCards.triangles}, from level 2 ${earlyCards.triangles}`);
+ assert.ok(forest.instances.length > 4000);
+ assert.ok(withCards.triangles < plain.triangles * 0.25);
+ assert.ok(earlyCards.triangles < 1.5e6);
+});
+
+test('the shaders carry the card code only where a pass needs it', () => {
+ assert.match(createVertexShader(['impostor']), /#define USES_IMPOSTOR \(true\)/);
+ assert.match(createVertexShader([]), /#define USES_IMPOSTOR false/);
+ assert.match(createDepthVertexShader(), /impostorCard\(position, uv, instanceMatrix, lightProjection/);
+ assert.match(impostorShader, new RegExp(`floor\\(square \\* ${IMPOSTOR_FRAMES}\\.0\\)`));
+ assert.match(createFragmentShader(['alphaMode', 'impostor']), /incoming \? coverage < 1\.0 - threshold : coverage <= threshold/);
+});