From b19ce20ba5924206e66264da96f52c1626689a9a Mon Sep 17 00:00:00 2001 From: timohueser Date: Sat, 21 Nov 2026 21:35:02 +0100 Subject: [PATCH 1/3] trailview: the terrain range and the morph band in the budget, phone 3.7 and 0.15 Co-Authored-By: Claude Opus 5.5 --- builder/web/src/lib/trailview/README.md | 4 ++-- builder/web/src/lib/trailview/budget.ts | 13 +++++++--- .../web/src/lib/trailview/ground/look.wgsl | 12 ++++++---- builder/web/src/lib/trailview/plan/cells.wgsl | 2 +- .../web/src/lib/trailview/plan/pieces.test.ts | 11 +++++---- builder/web/src/lib/trailview/plan/pieces.ts | 4 ++-- .../web/src/lib/trailview/roads/corridor.wgsl | 2 +- .../lib/trailview/terrain/drawn-height.wgsl | 5 ++-- .../web/src/lib/trailview/terrain/lod.test.ts | 12 ++++++---- builder/web/src/lib/trailview/terrain/lod.ts | 19 ++++++--------- .../src/lib/trailview/terrain/pages.test.ts | 13 ++++++---- .../src/lib/trailview/terrain/terrain.test.ts | 7 ++++-- .../web/src/lib/trailview/terrain/terrain.ts | 24 ++++++++++++------- 13 files changed, 75 insertions(+), 53 deletions(-) diff --git a/builder/web/src/lib/trailview/README.md b/builder/web/src/lib/trailview/README.md index 8eb0e05b02..d24b658bdd 100644 --- a/builder/web/src/lib/trailview/README.md +++ b/builder/web/src/lib/trailview/README.md @@ -170,8 +170,8 @@ uv run --locked --group planner-maps python FIX features features.pmtiles multiply by `look.screen.z`. - A still view shows the mean of 16 jittered frames; only new pages, nodes or extras restart them. - Debug colours lose bits in the `rg11b10ufloat` frame (2–4/255 near 1). -- A finer node meets a coarser one only on the LOD plateau: keep `RANGE.least` of `lod.ts` - (`lod.test.ts`). +- A finer node meets a coarser one only on the LOD plateau: a lower least range needs a narrower + morph band (`lod` of `budget.ts`, `lod.test.ts`). - The page pools have a fixed size. A view that wants more pages lowers `quality` in the HUD. - Never let a synthesis read a stamped page: a stored page keeps its raw layer and draws a copy. - The ground pool has a fixed size too: the farthest pages past it draw from their cover, two levels diff --git a/builder/web/src/lib/trailview/budget.ts b/builder/web/src/lib/trailview/budget.ts index 2ab5339b85..c06f2fd501 100644 --- a/builder/web/src/lib/trailview/budget.ts +++ b/builder/web/src/lib/trailview/budget.ts @@ -13,13 +13,20 @@ export interface Budget { groundPages: number; /** Loads in flight at most: terrain tiles, ground tiles, house tiles, stamp jobs of the worker, canopy tiles. */ loads: { terrain: number; ground: number; houses: number; stamps: number; canopy: number }; + /** + * The terrain's CDLOD range in node sizes, and its morph band in levels of log2 distance (`cdlod` of lod.ts). Below the + * least, a node can reach past the morph band of its parent's level, and neighbours would not meet (lod.test.ts); a + * narrower band lets them meet at a lower least. Above the most, a level leaves its LOD map window. + */ + lod: { least: number; most: number; morph: number }; } /** * The desktop's canopy loads are the 3 × 3 tiles about the eye at once. An iPhone 13 does not load a view with more - * than 64 ground pages. + * than 64 ground pages. The phone's range is 3.7 at every render size: at its 1,182 rows `bestRange` (terrain.ts) gives + * 4.0, and on the iPhone 13 the range × 0.8 of the desktop's least saved 4.5 ms of GPU time per frame. */ export const BUDGETS: Record = { - desktop: { frameRate: 60, terrainShare: 1, groundPages: 192, loads: { terrain: 6, ground: 4, houses: 6, stamps: 8, canopy: 9 } }, - phone: { frameRate: 30, terrainShare: 0.5, groundPages: 64, loads: { terrain: 3, ground: 2, houses: 3, stamps: 4, canopy: 5 } }, + desktop: { frameRate: 60, terrainShare: 1, groundPages: 192, loads: { terrain: 6, ground: 4, houses: 6, stamps: 8, canopy: 9 }, lod: { least: 4.6, most: 8, morph: 0.3 } }, + phone: { frameRate: 30, terrainShare: 0.5, groundPages: 64, loads: { terrain: 3, ground: 2, houses: 3, stamps: 4, canopy: 5 }, lod: { least: 3.7, most: 3.7, morph: 0.15 } }, }; diff --git a/builder/web/src/lib/trailview/ground/look.wgsl b/builder/web/src/lib/trailview/ground/look.wgsl index 75748dbcb0..ba88b513c7 100644 --- a/builder/web/src/lib/trailview/ground/look.wgsl +++ b/builder/web/src/lib/trailview/ground/look.wgsl @@ -30,11 +30,13 @@ // A node coarser than level 16 that its distance keeps from splitting (terrain.ts) draws without the // road paint, the blades and the bushes' dots: the compiler drops them, and with them the registers -// that they take from every pixel. Such a node lies at least RANGE.least nodes of level 16 from the -// eye (lod.ts). At 71° N on a canvas 2880 pixels tall, an output pixel there spans 0.37 m or more at -// the screen's centre, and 0.22 m at a corner of a 16:9 frame. That is past the fade of the blades -// (0.18 m). The dots of a patch fade at 0.1 × size_m: the 3 m that rules.py allows fade before such a -// node up to 64° N. Blotches do not fade: rules.py keeps them two such pixels across. +// that they take from every pixel. Such a node lies at least the least range of the tier from the +// eye (`lod` of budget.ts): 4.6 nodes of level 16 on the desktop. At 71° N on a canvas 2880 pixels +// tall, an output pixel there spans 0.37 m or more at the screen's centre, and 0.22 m at a corner of a +// 16:9 frame. That is past the fade of the blades (0.18 m). The dots of a patch fade at 0.1 × size_m: +// the 3 m that rules.py allows fade before such a node up to 64° N. The phone's 3.7 nodes on an +// iPad's canvas of up to 2752 pixels give 0.19 m at a corner, and its dots fade before such a node up +// to 58° N. Blotches do not fade: rules.py keeps them two such pixels across. override DETAIL: bool = true; // A corridor's band: the ground beside a road, shaped by it, under no paint and with facets of its own. override BAND: bool = false; diff --git a/builder/web/src/lib/trailview/plan/cells.wgsl b/builder/web/src/lib/trailview/plan/cells.wgsl index c6467d4d7f..f97e513a79 100644 --- a/builder/web/src/lib/trailview/plan/cells.wgsl +++ b/builder/web/src/lib/trailview/plan/cells.wgsl @@ -30,7 +30,7 @@ fn plan_meshed(u: vec2i) -> bool { // under it, over level-18 nodes and, at a lower quality, over level-17 nodes: level 17 morphs only // twice as far out. fn plan_sink_m() -> f32 { - return surface.range * exp2(-18.0 - MORPH); + return surface.range * exp2(-18.0 - surface.morph); } // Units past plan_sink_m to which a mesh draws whole (corridor.wgsl): two level-17 cells, the reach of a diff --git a/builder/web/src/lib/trailview/plan/pieces.test.ts b/builder/web/src/lib/trailview/plan/pieces.test.ts index 0279687278..c4962cea62 100644 --- a/builder/web/src/lib/trailview/plan/pieces.test.ts +++ b/builder/web/src/lib/trailview/plan/pieces.test.ts @@ -1,9 +1,12 @@ import { describe, expect, it } from 'vitest'; +import { BUDGETS } from '../budget'; import { anchorAt } from '../frame/space'; -import { CALM, cdlod, key, RANGE, type Node } from '../terrain/lod'; +import { CALM, cdlod, key, type Node } from '../terrain/lod'; import type { CellMesh } from './mesh'; import { meshLevel, Pieces, splitMouths, splitTails } from './pieces'; +const { least, morph } = BUDGETS.desktop.lod; + describe('splitMouths', () => { it("moves a run's mouth triangles to its end and keeps every triangle with its first corner", () => { // The corners' labels in their words, as the mesh packs them: 13 bits in the first word, 12 in the second. @@ -89,7 +92,7 @@ describe('meshLevel', () => { describe('Pieces', () => { it('draws again after a dip to 16 in a still view: it asks for the frames that bring the meshes back', () => { const pieces = new Pieces(() => ({ data: null, portals: null })), eye = { anchor: anchorAt(8.4048, 46.8219), above: 1.7 }; - const frame = (finest: number) => pieces.update(cdlod(eye, RANGE.least, finest), eye, () => 0, () => '', [], () => true, () => true); + const frame = (finest: number) => pieces.update(cdlod(eye, least, morph, finest), eye, () => 0, () => '', [], () => true, () => true); for (const finest of [18, 17, 16]) frame(finest); expect(pieces.level).toBe(0); // The quality is back at 17 and nothing else moves: only the meshes keep the frames going. @@ -115,7 +118,7 @@ describe('Pieces', () => { return (away = false) => { const before = reads; gone = away; - pieces.update(cdlod(eye, RANGE.least, 18), eye, () => 0, () => '', [], () => true, () => true); + pieces.update(cdlod(eye, least, morph, 18), eye, () => 0, () => '', [], () => true, () => true); return (reads - before) / 36; }; }; @@ -132,7 +135,7 @@ describe('Pieces', () => { words[0] = 0x4f424d05; pieces.add({ level: 16, x: 34_307, y: 23_107 }, words.buffer, 0, new Set()); let reads = 0; - const frame = (finest: number) => pieces.update(cdlod(eye, RANGE.least, finest), eye, () => 0, () => `${reads++}`, [], () => true, () => true); + const frame = (finest: number) => pieces.update(cdlod(eye, least, morph, finest), eye, () => 0, () => `${reads++}`, [], () => true, () => true); frame(18); frame(16); const before = reads; diff --git a/builder/web/src/lib/trailview/plan/pieces.ts b/builder/web/src/lib/trailview/plan/pieces.ts index f3297ff948..d3e66dbbce 100644 --- a/builder/web/src/lib/trailview/plan/pieces.ts +++ b/builder/web/src/lib/trailview/plan/pieces.ts @@ -12,7 +12,7 @@ import { layouts } from '../gpu/layouts'; import { wgsl } from '../gpu/wgsl'; import { CASTER_DEPTH, CASTER_PRIMITIVE } from '../light/shadow'; import { DEPTH, sceneFormat } from '../resolve/targets'; -import { CALM, CELL_LEVEL, distances, key, MORPH, size, type Eye, type Node, type Rule } from '../terrain/lod'; +import { CALM, CELL_LEVEL, distances, key, size, type Eye, type Node, type Rule } from '../terrain/lod'; import { touches } from '../terrain/pages'; import { metresPerUnit } from '../terrain/bins'; import type { NodeFeatures } from '../terrain/stamps'; @@ -319,7 +319,7 @@ export class Pieces { const cells = this.meshLevel ? range : []; const near = (piece: Piece) => distances(eye, piece.node)[0]; // The plateau of level 18 ends here; a triangle's reach and a little more stay whole past it. - const plateau = rule.range / 2 ** (18 + MORPH) - FADE_MARGIN_M; + const plateau = rule.range / 2 ** (18 + rule.morph) - FADE_MARGIN_M; this.cut.clear(); this.drawn = cells.flatMap(cell => { const piece = this.pieces.get(key(cell)); diff --git a/builder/web/src/lib/trailview/roads/corridor.wgsl b/builder/web/src/lib/trailview/roads/corridor.wgsl index df3764e56c..ba4879432f 100644 --- a/builder/web/src/lib/trailview/roads/corridor.wgsl +++ b/builder/web/src/lib/trailview/roads/corridor.wgsl @@ -365,7 +365,7 @@ fn corridor_fragment(raw: CorridorOut) -> @location(0) vec4f { // corners' triangles reach and the terrain takes no snap (PLAN_TRIANGLE_UNITS of cells.wgsl); gone // where level 18 ends. In metres, so the same at the finest level 17. if (PIECE && CUT) { - let sink = surface.range * exp2(-18.0 - MORPH); + let sink = surface.range * exp2(-18.0 - surface.morph); let d = length(vec3f(lod_space(in.u), surface.above)); if (dither(in.clip.xy + DETAIL_DITHER) >= 1.0 - smoothstep(sink + 256.0 * surface.unit, surface.range * exp2(-18.0), d)) { discard; diff --git a/builder/web/src/lib/trailview/terrain/drawn-height.wgsl b/builder/web/src/lib/trailview/terrain/drawn-height.wgsl index 5fc4ad7cf4..570c71c660 100644 --- a/builder/web/src/lib/trailview/terrain/drawn-height.wgsl +++ b/builder/web/src/lib/trailview/terrain/drawn-height.wgsl @@ -22,6 +22,8 @@ struct Surface { forward: array, // Per level: xy the node at the origin of its LOD map window. zw is unused: a uniform array element takes 16 bytes. levels: array, + // The morph band at the far end of each level, in levels of log2 distance (`Rule.morph` of lod.ts). + morph: f32, } @group(1) @binding(0) var surface: Surface; @@ -40,7 +42,6 @@ const MAP: i32 = 32; // Texels across a layer: 8 pages of 256. const LAYER: f32 = 2048.0; const COARSEST: u32 = 1u; -const MORPH: f32 = 0.3; // As MARGIN in lod.ts. const MARGIN: f32 = 1e-3; const UNKNOWN16: u32 = 0xffffu; @@ -232,7 +233,7 @@ fn units_ground(u: vec2i, top: u32) -> vec2f { fn lod(s: vec2f) -> f32 { let q = log2(surface.range / length(vec3f(s, surface.above))); let k = floor(q); - return clamp(k - 1.0 + min(1.0, (q - k) / MORPH), f32(COARSEST), f32(surface.finest)); + return clamp(k - 1.0 + min(1.0, (q - k) / surface.morph), f32(COARSEST), f32(surface.finest)); } // The weights of a point in a triangle, all ≥ 0 inside it; none for a triangle without area. diff --git a/builder/web/src/lib/trailview/terrain/lod.test.ts b/builder/web/src/lib/trailview/terrain/lod.test.ts index 57c1e69b45..4645f3f729 100644 --- a/builder/web/src/lib/trailview/terrain/lod.test.ts +++ b/builder/web/src/lib/trailview/terrain/lod.test.ts @@ -1,16 +1,18 @@ import { describe, expect, it } from 'vitest'; import { worldPixel } from '../../planner/layers/mercator'; +import { BUDGETS } from '../budget'; import { anchorAt, lodSpace, UNITS } from '../frame/space'; -import { cdlod, GRID, MAP, RANGE, select, size, type Eye, type Node, type Rule } from './lod'; +import { cdlod, GRID, MAP, select, size, type Eye, type Node, type Rule } from './lod'; const BOX = [7.6, 46.46, 8.95, 47.25] as const; const [west, north] = worldPixel([BOX[0], BOX[3]], UNITS), [east, south] = worldPixel([BOX[2], BOX[1]], UNITS); const BOUNDS: [number, number, number, number] = [west, north, east, south]; const eye = (lon: number, lat: number, above: number): Eye => ({ anchor: anchorAt(lon, lat), above }); const EYES = [eye(8.403, 46.8205, 1.6), eye(8.39, 46.8, 900), eye(8.415, 46.7, 12_000), eye(8.2, 46.85, 60_000)]; -const RULES: [string, (eye: Eye) => Rule][] = [ - ...[RANGE.least, RANGE.most].map((factor): [string, (eye: Eye) => Rule] => [`cdlod ${factor}`, e => cdlod(e, factor)]), -]; +const RULES = Object.entries(BUDGETS).flatMap(([tier, { lod }]) => + [...new Set([lod.least, lod.most])].map((factor): [string, (eye: Eye) => Rule] => [`${tier} ${factor}`, e => cdlod(e, factor, lod.morph)]), +); +const DESKTOP = BUDGETS.desktop.lod; /** The LOD at the grid vertex (i, j) of a node, from whole units, as the vertex shader has it. */ const vertexLod = (rule: Rule, e: Eye, { level, x, y }: Node, i: number, j: number) => { @@ -64,7 +66,7 @@ describe.each(RULES)('the %s selection', (_, make) => { describe('the CDLOD selection', () => { it('culls a subtree that is not visible, and wants the pages of the drawn nodes and of the parents that they morph to', () => { - const walk = EYES[0], rule = cdlod(walk, RANGE.least); + const walk = EYES[0], rule = cdlod(walk, DESKTOP.least, DESKTOP.morph); const all = select(rule, BOUNDS, () => true); const east = select(rule, BOUNDS, ({ level, x }) => (x + 1) * size(level) > walk.anchor.whole[0]); expect(east.nodes.length).toBeLessThan(all.nodes.length); diff --git a/builder/web/src/lib/trailview/terrain/lod.ts b/builder/web/src/lib/trailview/terrain/lod.ts index e0ba059e62..14db80897d 100644 --- a/builder/web/src/lib/trailview/terrain/lod.ts +++ b/builder/web/src/lib/trailview/terrain/lod.ts @@ -6,19 +6,12 @@ export const GRID = 64; export const FINEST = 18; /** The coarsest level with pages: the quadrants of tile 0/0/0. */ export const COARSEST = 1; -/** The morph band of a CDLOD level, in levels of log2 distance, as MORPH in drawn-height.wgsl. */ -export const MORPH = 0.3; /** Calm frames in a row before the quality rises again (terrain.ts), and before the meshes draw again after a frame below level 17 (pieces.ts). */ export const CALM = 120; /** Nodes along an edge of the LOD map window of each level. */ export const MAP = 32; /** A node splits this far, in levels, before its finest point reaches the next level, so float32 shaders see exact plateaus. */ const MARGIN = 1e-3; -/** - * CDLOD ranges in node sizes. Below the least, a node can reach past the morph band of its parent's - * level, and neighbours would not meet; above the most, a level leaves its LOD map window. - */ -export const RANGE = { least: 4.6, most: 8 } as const; /** The near field: metres about the eye where the level-17 nodes and the kinds' near meshes draw. `nearReady()` waits for it. */ export const NEAR_M = 2000; /** The field about the eye that `eyeReady()` waits for: the view's position is final once it draws. */ @@ -55,6 +48,8 @@ export interface Rule { readonly finest: number; /** The distance in metres where the LOD is 0. */ readonly range: number; + /** The morph band at the far end of each level, in levels of log2 distance. */ + readonly morph: number; /** Whether some point of the node wants a level finer than its own + `coarser`. */ split(node: Node, coarser?: number): boolean; /** Whether some point of a drawn node morphs toward its parent's level, so the node reads its parent's page. */ @@ -77,18 +72,18 @@ export function distances(eye: Eye, { level, x, y }: Node): [number, number] { /** * CDLOD (Strugar 2009) by distance: the LOD is log2(range / d) with a plateau at each whole level and - * a morph band of MORPH at its far end. `factor` is the range of a level in its node sizes. + * a morph band of `morph` levels at its far end. `factor` is the range of a level in its node sizes (`lod` of budget.ts). */ -export function cdlod(eye: Eye, factor: number, finest = FINEST): Rule { +export function cdlod(eye: Eye, factor: number, morph: number, finest = FINEST): Rule { const range = factor * UNITS * eye.anchor.unit; const plateau = (q: number) => { const k = Math.floor(q); - return Math.min(finest, Math.max(COARSEST, k - 1 + Math.min(1, (q - k) / MORPH))); + return Math.min(finest, Math.max(COARSEST, k - 1 + Math.min(1, (q - k) / morph))); }; return { - finest, range, + finest, range, morph, split: (node, coarser = 0) => node.level + coarser < finest && Math.log2(range / distances(eye, node)[0]) > node.level + 1 + coarser - MARGIN, - morphs: node => Math.log2(range / distances(eye, node)[1]) < node.level + MORPH + MARGIN, + morphs: node => Math.log2(range / distances(eye, node)[1]) < node.level + morph + MARGIN, lod: ([sx, sy]) => plateau(Math.log2(range / Math.hypot(sx, sy, eye.above))), }; } diff --git a/builder/web/src/lib/trailview/terrain/pages.test.ts b/builder/web/src/lib/trailview/terrain/pages.test.ts index d40edd2fdf..0adca58fe4 100644 --- a/builder/web/src/lib/trailview/terrain/pages.test.ts +++ b/builder/web/src/lib/trailview/terrain/pages.test.ts @@ -1,11 +1,14 @@ import { describe, expect, it } from 'vitest'; import { worldPixel } from '../../planner/layers/mercator'; +import { BUDGETS } from '../budget'; import { anchorAt, UNITS } from '../frame/space'; import { pageData, PAGE } from '../stream/heights'; import type { TerrainSource } from '../stream/terrain'; -import { cdlod, distances, EYE_M, key, MAP, RANGE, select, size, type Node } from './lod'; +import { cdlod, distances, EYE_M, key, MAP, select, size, type Node } from './lod'; import { ARRIVALS, MODE, Pages, touches, type StampSource, type Work } from './pages'; +const { least, morph } = BUDGETS.desktop.lod; + const BOX = [8.37, 46.765, 8.46, 46.83] as const; const [west, north] = worldPixel([BOX[0], BOX[3]], UNITS), [east, south] = worldPixel([BOX[2], BOX[1]], UNITS); const BOUNDS: [number, number, number, number] = [west, north, east, south]; @@ -41,7 +44,7 @@ async function settle(pages: Pages, wanted: Node[], frames = 300, eye = new Set< } describe('the page pools', () => { - const { wanted } = select(cdlod({ anchor, above: 1.6 }, RANGE.least), BOUNDS, () => true); + const { wanted } = select(cdlod({ anchor, above: 1.6 }, least, morph), BOUNDS, () => true); wanted.sort((a, b) => a.level - b.level); const eye = new Set(wanted.filter(node => distances({ anchor, above: 0 }, node)[0] <= EYE_M).map(key)); @@ -239,7 +242,7 @@ describe('the page pools', () => { it('name in each frame the pages under every box whose read key changes: arrivals, syntheses, evictions and restamps', async () => { const ex = anchor.whole[0] + anchor.part[0], ey = anchor.whole[1] + anchor.part[1], s = size(16), order = (a: Node, b: Node) => a.level - b.level; - const half = (east: boolean) => select(cdlod({ anchor, above: 1.6 }, RANGE.least), BOUNDS, ({ level, x }) => (east ? (x + 1) * size(level) > ex : x * size(level) < ex)).wanted.sort(order); + const half = (east: boolean) => select(cdlod({ anchor, above: 1.6 }, least, morph), BOUNDS, ({ level, x }) => (east ? (x + 1) * size(level) > ex : x * size(level) < ex)).wanted.sort(order); const boxes = [-1, 0, 1].flatMap(j => [-1, 0, 1].map((i): [number, number, number, number] => { const x = (Math.floor(ex / s) + i) * s, y = (Math.floor(ey / s) + j) * s; return [x + 100, y + 100, x + s - 100, y + s - 100]; @@ -298,7 +301,7 @@ describe('the page pools', () => { }); describe('the stamps', () => { - const { wanted } = select(cdlod({ anchor, above: 1.6 }, RANGE.least), BOUNDS, () => true); + const { wanted } = select(cdlod({ anchor, above: 1.6 }, least, morph), BOUNDS, () => true); wanted.sort((a, b) => a.level - b.level); /** Every node has a feature near it; its stamps are known one frame after a page asks for them. */ const stamps = (): StampSource => { @@ -345,7 +348,7 @@ describe('a turn', () => { // A flight 1 km above the ground over Engelberg, in the whole box of the bakes. const [w, n] = worldPixel([7.6, 47.25], UNITS), [e, s] = worldPixel([8.95, 46.46], UNITS); const box: [number, number, number, number] = [w, n, e, s]; - const rule = cdlod({ anchor, above: 1000 }, RANGE.least); + const rule = cdlod({ anchor, above: 1000 }, least, morph); const ex = anchor.whole[0] + anchor.part[0]; const side = (east: boolean) => select(rule, box, ({ level, x }) => (east ? (x + 1) * size(level) > ex : x * size(level) < ex)); diff --git a/builder/web/src/lib/trailview/terrain/terrain.test.ts b/builder/web/src/lib/trailview/terrain/terrain.test.ts index a4163a8ccd..488d044dbf 100644 --- a/builder/web/src/lib/trailview/terrain/terrain.test.ts +++ b/builder/web/src/lib/trailview/terrain/terrain.test.ts @@ -1,15 +1,18 @@ import { describe, expect, it, vi } from 'vitest'; +import { BUDGETS } from '../budget'; import { anchorAt } from '../frame/space'; import { TILE_ZOOM } from '../stream/terrain'; -import { CALM, cdlod, GRID, RANGE, select, size } from './lod'; +import { CALM, cdlod, GRID, select, size } from './lod'; import { MODE, type Page } from './pages'; import { gridIndices, stampJobs, stepQuality, SYNTH_PAGES, SYNTHESIZED, Terrain } from './terrain'; +const { least, morph } = BUDGETS.desktop.lod; + describe('the synthesized pool', () => { it('holds what the least range wants of the half of the world ahead, so no page is left out', () => { const anchor = anchorAt(8.38, 46.8), east = anchor.whole[0] + anchor.part[0]; for (const above of [1.6, 30, 300]) { - const { wanted } = select(cdlod({ anchor, above }, RANGE.least), [0, 0, 2 ** 30, 2 ** 30], ({ level, x }) => (x + 1) * size(level) >= east); + const { wanted } = select(cdlod({ anchor, above }, least, morph), [0, 0, 2 ** 30, 2 ** 30], ({ level, x }) => (x + 1) * size(level) >= east); expect(wanted.filter(({ level }) => level > TILE_ZOOM + 1).length).toBeLessThanOrEqual(SYNTH_PAGES); } }); diff --git a/builder/web/src/lib/trailview/terrain/terrain.ts b/builder/web/src/lib/trailview/terrain/terrain.ts index 0363066e72..9175545582 100644 --- a/builder/web/src/lib/trailview/terrain/terrain.ts +++ b/builder/web/src/lib/trailview/terrain/terrain.ts @@ -13,7 +13,7 @@ import { PAGE } from '../stream/heights'; import type { TerrainSource } from '../stream/terrain'; import { DEPTH, sceneFormat } from '../resolve/targets'; import { featureTile, NEAR, profileTable, STAMP_WORDS, waterAt } from './bins'; -import { CALM, cdlod, COARSEST, distances, EYE_M, FINEST, GRID, key, MAP, NEAR_M, RANGE, select, size, type Node, type Rule } from './lod'; +import { CALM, cdlod, COARSEST, distances, EYE_M, FINEST, GRID, key, MAP, NEAR_M, select, size, type Node, type Rule } from './lod'; import { ARRIVALS, copies, MODE, NO_LIMIT, Pages, type Kind, type Page, type Stamp, type Work } from './pages'; import { Stamps, type BakedNodes, type FeatureTiles } from './stamps'; import { OPAQUE, Water } from './water'; @@ -64,8 +64,10 @@ const PROBE_STEP = 1; /** * The probe runs again when the eye's height above the ground moves more than this many metres from that of the * last probe. The probe's answer sets that height, and the height moves the answer through the morph of `lod` - * (drawn-height.wgsl) by D / (MORPH · above · ln 2) per metre for a gap D between two levels, far below 1, so - * repeated probes converge; float rounding then leaves a last swing of one step. The band ends it: 1 cm is 20 + * (drawn-height.wgsl) by at most D / (morph · above · ln 2) per metre for a gap D between two levels. The eye's point + * morphs only above the start of the finest level's band, range · 2^−(18 + morph): 3.3 level-18 nodes on the phone, at + * least 166 m up to 71° N, where the bound is 0.06 D. At a walk's eye height the point lies on the finest level's + * plateau and the answer does not move. So repeated probes converge; float rounding then leaves a last swing of one step. The band ends it: 1 cm is 20 * times the float32 step of a ground height below 8,192 m (at most 0.5 mm), and no change that a view shows. */ const PROBE_ABOVE_M = 0.01; @@ -74,7 +76,7 @@ const RAD = Math.PI / 180; /** The workgroups of a cliff job, as ROW in cliff.wgsl. */ const CLIFF_ROW = 32; /** Bytes of `Surface` and `Job` in the WGSL, and of a node instance. */ -const SURFACE_BYTES = 416, JOB_BYTES = 24, STAMP_JOB_BYTES = 32, NODE_BYTES = 16; +const SURFACE_BYTES = 432, JOB_BYTES = 24, STAMP_JOB_BYTES = 32, NODE_BYTES = 16; /** A stamp job whose base is the synthesized page in `out`, as SYNTHESIZED in stamp.wgsl. */ export const SYNTHESIZED = 0xffffffff; /** Audit samples per run at most, words per sample, and words of results, as in audit.wgsl. */ @@ -224,6 +226,7 @@ export class Terrain { ground?: { height: number; slope: [number, number]; lonLat: [number, number]; frame: number }; private resources?: Resources; private readonly bounds: [number, number, number, number]; + private readonly lod: Budget['lod']; private nodes: Node[] = []; /** The first drawn nodes that hold a tunnel's portal: they draw with its hole. */ private holed = 0; @@ -277,6 +280,7 @@ export class Terrain { constructor(private readonly frame: Frame, source: TerrainSource, features: FeatureTiles | undefined, bounds: Bounds, private readonly changed: () => void, stop: AbortSignal, budget: Budget, plan = false, private readonly finest = FINEST, baked?: BakedNodes, cache?: { release: string; version: string; plan: string }) { const [west, north] = worldPixel([bounds[0], bounds[3]], UNITS), [east, south] = worldPixel([bounds[2], bounds[1]], UNITS); this.bounds = [west, north, east, south]; + this.lod = budget.lod; // Whole layers inside the two budgets; the synthesized pool takes its share, the stored pool the rest. const pages = Math.floor((BUDGET.stored + BUDGET.synth - MASK_BYTES) / PAGE_BYTES / LAYER_PAGES) * LAYER_PAGES; this.profileTable = profileTable(); @@ -569,7 +573,7 @@ export class Terrain { anchor, COARSEST_MESH); const short = this.pages.left.some((pages, level) => pages > 0 && level < COARSEST_MESH), { capacity } = this.pages; ({ quality: this.quality, calm: this.calm, held: this.held } = stepQuality({ quality: this.quality, calm: this.calm, held: this.held }, short, this.pages.missing === 0, moving, - () => this.quality < qualitySteps(view.pixels) && lowers(coarse(this.quality), coarse(this.quality + 1), capacity), + () => this.quality < qualitySteps(this.lod, view.pixels) && lowers(coarse(this.quality), coarse(this.quality + 1), capacity), () => fits(coarse(this.quality - 1), capacity))); // The level that the probe reads splits by the height of the last probe, as `encode` decides the next probe by it. const above = this.heldAbove(view.above), probeReads = this.probeKey(above === view.above ? rule : this.rule({ anchor, above }, view.pixels, quality), anchor); @@ -954,7 +958,8 @@ export class Terrain { /** The rule at a quality: each step makes the range a quarter step smaller, down to the least. No step lowers the finest level. */ private rule(eye: { anchor: Anchor; above: number }, pixels: number, quality = this.quality): Rule { - return cdlod(eye, Math.max(RANGE.least, bestRange(pixels) * 2 ** (-quality / 4)), this.finest); + const lod = this.lod; + return cdlod(eye, Math.max(lod.least, bestRange(lod, pixels) * 2 ** (-quality / 4)), lod.morph, this.finest); } /** Whether a node's box can show: render space corners at its range of heights, against the frustum. */ @@ -1054,6 +1059,7 @@ export class Terrain { ints.set(anchor.whole, 0); floats.set([...anchor.part, anchor.unit, above, rule.range], 2); new Uint32Array(surface)[7] = rule.finest; + floats[104] = rule.morph; floats.set(forward, 8); work.origins.forEach((origin, level) => ints.set(origin, 28 + 4 * level)); device.queue.writeBuffer(r.surface, 0, surface); @@ -1090,11 +1096,11 @@ export class Terrain { } } -/** The range at which a level's grid cell spans CELL_PIXELS on a render target `pixels` high, within RANGE. */ -const bestRange = (pixels: number) => Math.min(RANGE.most, Math.max(RANGE.least, pixels / (2 * Math.tan(VFOV * RAD / 2)) / (GRID * CELL_PIXELS))); +/** The range at which a level's grid cell spans CELL_PIXELS on a render target `pixels` high, within the tier's limits. */ +const bestRange = ({ least, most }: Budget['lod'], pixels: number) => Math.min(most, Math.max(least, pixels / (2 * Math.tan(VFOV * RAD / 2)) / (GRID * CELL_PIXELS))); /** The quality steps that make the range smaller: 0 on a usual screen, whose best range is the least already. */ -const qualitySteps = (pixels: number) => Math.ceil(4 * Math.log2(bestRange(pixels) / RANGE.least)); +const qualitySteps = (lod: Budget['lod'], pixels: number) => Math.ceil(4 * Math.log2(bestRange(lod, pixels) / lod.least)); /** Whether a demand of slots per pool lowers that of `now` in every pool that `now` overfills. */ const lowers = (now: Record, next: Record, capacity: Record) => From a0ca100190b140e67caeae512aec47d9709ea808 Mon Sep 17 00:00:00 2001 From: timohueser Date: Sat, 21 Nov 2026 21:56:29 +0100 Subject: [PATCH 2/3] trailview: the README line on the LOD plateau at its old length Co-Authored-By: Claude Opus 5.5 --- builder/web/src/lib/trailview/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builder/web/src/lib/trailview/README.md b/builder/web/src/lib/trailview/README.md index d24b658bdd..5f25e23f51 100644 --- a/builder/web/src/lib/trailview/README.md +++ b/builder/web/src/lib/trailview/README.md @@ -170,8 +170,8 @@ uv run --locked --group planner-maps python FIX features features.pmtiles multiply by `look.screen.z`. - A still view shows the mean of 16 jittered frames; only new pages, nodes or extras restart them. - Debug colours lose bits in the `rg11b10ufloat` frame (2–4/255 near 1). -- A finer node meets a coarser one only on the LOD plateau: a lower least range needs a narrower - morph band (`lod` of `budget.ts`, `lod.test.ts`). +- A finer node meets a coarser one only on the LOD plateau: keep `lod` of `budget.ts` + (`lod.test.ts`). - The page pools have a fixed size. A view that wants more pages lowers `quality` in the HUD. - Never let a synthesis read a stamped page: a stored page keeps its raw layer and draws a copy. - The ground pool has a fixed size too: the farthest pages past it draw from their cover, two levels From 9002f25d206a33b073bec02011012cf1012646d3 Mon Sep 17 00:00:00 2001 From: timohueser Date: Sat, 21 Nov 2026 22:04:22 +0100 Subject: [PATCH 3/3] trailview: review fixes of the far terrain comments Co-Authored-By: Claude Opus 5.5 --- builder/web/src/lib/trailview/budget.ts | 4 ++-- builder/web/src/lib/trailview/ground/look.wgsl | 6 +++--- builder/web/src/lib/trailview/terrain/terrain.ts | 9 +++++---- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/builder/web/src/lib/trailview/budget.ts b/builder/web/src/lib/trailview/budget.ts index c06f2fd501..3751c25540 100644 --- a/builder/web/src/lib/trailview/budget.ts +++ b/builder/web/src/lib/trailview/budget.ts @@ -23,8 +23,8 @@ export interface Budget { /** * The desktop's canopy loads are the 3 × 3 tiles about the eye at once. An iPhone 13 does not load a view with more - * than 64 ground pages. The phone's range is 3.7 at every render size: at its 1,182 rows `bestRange` (terrain.ts) gives - * 4.0, and on the iPhone 13 the range × 0.8 of the desktop's least saved 4.5 ms of GPU time per frame. + * than 64 ground pages. The phone's least and most range are equal: its range does not follow the render size + * (`bestRange` of terrain.ts), and no quality step lowers it. */ export const BUDGETS: Record = { desktop: { frameRate: 60, terrainShare: 1, groundPages: 192, loads: { terrain: 6, ground: 4, houses: 6, stamps: 8, canopy: 9 }, lod: { least: 4.6, most: 8, morph: 0.3 } }, diff --git a/builder/web/src/lib/trailview/ground/look.wgsl b/builder/web/src/lib/trailview/ground/look.wgsl index ba88b513c7..39bfeafdec 100644 --- a/builder/web/src/lib/trailview/ground/look.wgsl +++ b/builder/web/src/lib/trailview/ground/look.wgsl @@ -34,9 +34,9 @@ // eye (`lod` of budget.ts): 4.6 nodes of level 16 on the desktop. At 71° N on a canvas 2880 pixels // tall, an output pixel there spans 0.37 m or more at the screen's centre, and 0.22 m at a corner of a // 16:9 frame. That is past the fade of the blades (0.18 m). The dots of a patch fade at 0.1 × size_m: -// the 3 m that rules.py allows fade before such a node up to 64° N. The phone's 3.7 nodes on an -// iPad's canvas of up to 2752 pixels give 0.19 m at a corner, and its dots fade before such a node up -// to 58° N. Blotches do not fade: rules.py keeps them two such pixels across. +// the 3 m that rules.py allows fade before such a node up to 64° N. The phone's 3.7 nodes keep both: +// its largest frame, an iPad of 2752 pixels in portrait (3:4), gives about 0.22 m at a corner. +// Blotches do not fade: rules.py keeps them two such pixels across. override DETAIL: bool = true; // A corridor's band: the ground beside a road, shaped by it, under no paint and with facets of its own. override BAND: bool = false; diff --git a/builder/web/src/lib/trailview/terrain/terrain.ts b/builder/web/src/lib/trailview/terrain/terrain.ts index 9175545582..b939a287a6 100644 --- a/builder/web/src/lib/trailview/terrain/terrain.ts +++ b/builder/web/src/lib/trailview/terrain/terrain.ts @@ -64,10 +64,11 @@ const PROBE_STEP = 1; /** * The probe runs again when the eye's height above the ground moves more than this many metres from that of the * last probe. The probe's answer sets that height, and the height moves the answer through the morph of `lod` - * (drawn-height.wgsl) by at most D / (morph · above · ln 2) per metre for a gap D between two levels. The eye's point - * morphs only above the start of the finest level's band, range · 2^−(18 + morph): 3.3 level-18 nodes on the phone, at - * least 166 m up to 71° N, where the bound is 0.06 D. At a walk's eye height the point lies on the finest level's - * plateau and the answer does not move. So repeated probes converge; float rounding then leaves a last swing of one step. The band ends it: 1 cm is 20 + * (drawn-height.wgsl) by at most D / (morph · above · ln 2) per metre for a gap D between two levels. The eye's + * point morphs only above the start of the finest level's band, range · 2^−(18 + morph): 3.3 level-18 nodes on + * the phone, at least 166 m up to 71° N, where the bound is 0.06 D. At a walk's eye height the point lies on the + * finest level's plateau and the answer does not move. So repeated probes converge; float rounding then leaves a + * last swing of one step. The band ends it: 1 cm is 20 * times the float32 step of a ground height below 8,192 m (at most 0.5 mm), and no change that a view shows. */ const PROBE_ABOVE_M = 0.01;