@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/playground/ssr_variance/capture.js

@@ -1,96 +1,96 @@
-import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
-import { FramePhase } from "../../renderer/extension/FramePhase.js";
-import { SceneColor } from "../../renderer/extension/SceneColor.js";
-import { ImageShader } from "../../renderer/shader/ImageShader.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
-import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
-import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
-import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
-import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup().addTexture('tSource', 'unfilterable-float').addTexture('tNormal', 'uint');
-const shader = new ImageShader({
-    descriptor: ShaderDescriptor.from({ label: 'SSR variance / capture', resources,
-        body: CodeChunk.from(/* language=WGSL */ `
-struct Capture { @location(0) radiance: vec4f, @location(1) mask: vec4f }
-@fragment fn main(@builtin(position) coord: vec4f) -> Capture {
-    let p = vec2i(coord.xy);
-    var output: Capture;
-    output.radiance = textureLoad(tSource, p, 0);
-    output.mask = vec4f(select(0.0, 1.0, decode_g_buffer_normal(textureLoad(tNormal, p, 0).xy).y > 0.99));
-    return output;
-}`, [chunk_decode_g_buffer_normal]) }),
-    targets: [{ format: 'rgba32float' }, { format: 'rgba32float' }],
-});
-
-/** TAA-off currently leaves raster jitter active. Freeze only this lab's view before rasterization. */
-export class FixedProjection extends RenderExtension {
-    name = 'SSR variance / fixed projection';
-    phase = FramePhase.FrameStart;
-    record(frame) {
-        frame.view.setJitter(0, 0);
-        frame.view.camera.setViewportOffset(0, 0);
-        frame.view.camera.update();
-        frame.view.update_uniforms();
-    }
-}
-
-/** Exact textureLoad copies of production SSR stages, only on requested frames. */
-export class CaptureSSR extends RenderExtension {
-    name = 'SSR variance / capture';
-    phase = FramePhase.BeforePresent;
-    enabled = false;
-    textures = new Map();
-    constructor(device) { super(); this.device = device; }
-    record(frame) {
-        if (!this.enabled) { return; }
-        this.jitter = Array.from(frame.view.jitter);
-        const passes = frame.graph.__pass_nodes;
-        const resolve = passes.find(p => p.name === 'SSR resolve / IBL');
-        const spatial1 = passes.find(p => p.name === 'SSR / spatial denoise with metadata');
-        const temporal = passes.find(p => p.name === 'SSR Reproject');
-        const spatial = passes.filter(p => p.name === 'SSR / spatial denoise');
-        const taa = passes.find(p => p.name === 'TAA');
-        if (!resolve || !temporal) { throw new Error('SSR stages missing from the frame graph'); }
-        const resolved = resolve.data['@output'][0];
-        const reprojected = temporal.data['@output'][0];
-        const stages = {
-            resolve: resolved,
-            spatial1: spatial1?.data['@output'][0] ?? resolved,
-            temporal: reprojected,
-            spatial2: spatial[0]?.data['@output'][0] ?? reprojected,
-            spatial4: spatial[1]?.data['@output'][0] ?? reprojected,
-            'pre-taa': taa?.data.ColourTexture ?? frame.get(SceneColor).color,
-            scene: frame.get(SceneColor).color,
-        };
-        const [width, height] = frame.resolution;
-        const texture = name => {
-            let t = this.textures.get(name);
-            if (!t || t.width !== width || t.height !== height) {
-                t?.destroy();
-                t = GPUTextureContext.fromTexture(this.device.createTexture({
-                    label: `SSR variance / ${name}`, size: [width, height, 1], format: 'rgba32float',
-                    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
-                }), this.device);
-                this.textures.set(name, t);
-            }
-            return graph_import_texture(frame.graph, t, `SSR variance / ${name}`);
-        };
-        let mask = texture('mask');
-        for (const [name, handle] of Object.entries(stages)) {
-            [, mask] = graph_image_pass({ graph: frame.graph, shader,
-                inputs: { tSource: handle, tNormal: resolve.data.tNormal }, output: [texture(name), mask] });
-        }
-    }
-    async read() {
-        const result = {};
-        for (const [name, texture] of this.textures) {
-            result[name] = await download_texture_data({ device: this.device, source: texture.gpu_texture });
-        }
-        return result;
-    }
-}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup().addTexture('tSource', 'unfilterable-float').addTexture('tNormal', 'uint');
+const shader = new ImageShader({
+    descriptor: ShaderDescriptor.from({ label: 'SSR variance / capture', resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+struct Capture { @location(0) radiance: vec4f, @location(1) mask: vec4f }
+@fragment fn main(@builtin(position) coord: vec4f) -> Capture {
+    let p = vec2i(coord.xy);
+    var output: Capture;
+    output.radiance = textureLoad(tSource, p, 0);
+    output.mask = vec4f(select(0.0, 1.0, decode_g_buffer_normal(textureLoad(tNormal, p, 0).xy).y > 0.99));
+    return output;
+}`, [chunk_decode_g_buffer_normal]) }),
+    targets: [{ format: 'rgba32float' }, { format: 'rgba32float' }],
+});
+
+/** TAA-off currently leaves raster jitter active. Freeze only this lab's view before rasterization. */
+export class FixedProjection extends RenderExtension {
+    name = 'SSR variance / fixed projection';
+    phase = FramePhase.FrameStart;
+    record(frame) {
+        frame.view.setJitter(0, 0);
+        frame.view.camera.setViewportOffset(0, 0);
+        frame.view.camera.update();
+        frame.view.update_uniforms();
+    }
+}
+
+/** Exact textureLoad copies of production SSR stages, only on requested frames. */
+export class CaptureSSR extends RenderExtension {
+    name = 'SSR variance / capture';
+    phase = FramePhase.BeforePresent;
+    enabled = false;
+    textures = new Map();
+    constructor(device) { super(); this.device = device; }
+    record(frame) {
+        if (!this.enabled) { return; }
+        this.jitter = Array.from(frame.view.jitter);
+        const passes = frame.graph.__pass_nodes;
+        const resolve = passes.find(p => p.name === 'SSR resolve / IBL');
+        const spatial1 = passes.find(p => p.name.startsWith('SSR / spatial denoise with metadata'));
+        const temporal = passes.find(p => p.name.startsWith('SSR Reproject'));
+        const spatial = passes.filter(p => p.name === 'SSR / spatial denoise' || p.name === 'SSR / spatial denoise / tiles');
+        const taa = passes.find(p => p.name === 'TAA');
+        if (!resolve || !temporal) { throw new Error('SSR stages missing from the frame graph'); }
+        const resolved = resolve.data['@output'][0];
+        const reprojected = temporal.data['@output'][0];
+        const stages = {
+            resolve: resolved,
+            spatial1: spatial1?.data['@output'][0] ?? resolved,
+            temporal: reprojected,
+            spatial2: spatial[0]?.data['@output'][0] ?? reprojected,
+            spatial4: spatial[1]?.data['@output'][0] ?? reprojected,
+            'pre-taa': taa?.data.ColourTexture ?? frame.get(SceneColor).color,
+            scene: frame.get(SceneColor).color,
+        };
+        const [width, height] = frame.resolution;
+        const texture = name => {
+            let t = this.textures.get(name);
+            if (!t || t.width !== width || t.height !== height) {
+                t?.destroy();
+                t = GPUTextureContext.fromTexture(this.device.createTexture({
+                    label: `SSR variance / ${name}`, size: [width, height, 1], format: 'rgba32float',
+                    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+                }), this.device);
+                this.textures.set(name, t);
+            }
+            return graph_import_texture(frame.graph, t, `SSR variance / ${name}`);
+        };
+        let mask = texture('mask');
+        for (const [name, handle] of Object.entries(stages)) {
+            [, mask] = graph_image_pass({ graph: frame.graph, shader,
+                inputs: { tSource: handle, tNormal: resolve.data.tNormal }, output: [texture(name), mask] });
+        }
+    }
+    async read() {
+        const result = {};
+        for (const [name, texture] of this.textures) {
+            result[name] = await download_texture_data({ device: this.device, source: texture.gpu_texture });
+        }
+        return result;
+    }
+}

package/src/shade/playground/ssr_variance/reference.js

@@ -1,78 +1,78 @@
-import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
-import { ImageShader } from "../../renderer/shader/ImageShader.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
-import { f32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
-import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
-import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
-import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
-
-const settings = WebGPUStruct.from({ count: f32 });
-const resources = new ShaderResourceSetDescriptor();
-resources.setImmediate('settings', settings);
-resources.createGroup().addTexture('tInput', 'unfilterable-float').addTexture('tPrevious', 'unfilterable-float');
-const shader = new ImageShader({ descriptor: ShaderDescriptor.from({
-    label: 'SSR lab / later-sample reference', resources,
-    body: CodeChunk.from(/* language=WGSL */ `
-@fragment fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
-    let p = vec2i(coord.xy);
-    let sample = textureLoad(tInput, p, 0);
-    if (settings.count <= 1.0) { return sample; }
-    let previous = textureLoad(tPrevious, p, 0);
-    return previous + (sample - previous) / settings.count;
-}`, [settings.declaration_chunk]),
-}), targets: [{ format: 'rgba32float' }] });
-
-/** Unclipped float32 average of later pre-temporal samples, never fed into rendering. */
-export class ReflectionReference extends RenderExtension {
-    name = 'SSR lab / later-sample reference';
-    enabled = false;
-    count = 0;
-    textures = [];
-    constructor(device) { super(); this.device = device; }
-    record(frame) {
-        if (!this.enabled) { return; }
-        const temporal = frame.graph.__pass_nodes.find(p => p.name === 'SSR Reproject');
-        if (!temporal) { throw new Error('SSR is required for a reflection reference'); }
-        if (!this.textures.length) {
-            for (let i = 0; i < 2; i++) {
-                this.textures.push(GPUTextureContext.fromTexture(this.device.createTexture({
-                    size: [frame.resolution[0], frame.resolution[1], 1], format: 'rgba32float',
-                    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
-                }), this.device));
-            }
-        }
-        const index = this.count % 2;
-        const previous = graph_import_texture(frame.graph, this.textures[1 - index], 'SSR reference previous');
-        const output = graph_import_texture(frame.graph, this.textures[index], 'SSR reference output');
-        graph_image_pass({ graph: frame.graph, shader,
-            inputs: { tInput: temporal.data.tInput, tPrevious: previous, settings: { count: this.count + 1 } },
-            output: [output] });
-        this.count++;
-    }
-    async read() {
-        if (!this.count) { throw new Error('Reference has no samples'); }
-        return download_texture_data({ device: this.device,
-            source: this.textures[(this.count - 1) % 2].gpu_texture });
-    }
-}
-
-export function reflection_error(sample, reference, mask, width, height) {
-    let count = 0, squared_error = 0, bias = 0;
-    for (let y = Math.floor(height * 0.5); y < Math.floor(height * 0.92); y++) {
-        for (let x = Math.floor(width * 0.25); x < Math.floor(width * 0.75); x++) {
-            const p = (y * width + x) * 4;
-            if (mask[p] <= 0.5) { continue; }
-            const error = (sample[p] - reference[p]) * 0.2126
-                + (sample[p + 1] - reference[p + 1]) * 0.7152
-                + (sample[p + 2] - reference[p + 2]) * 0.0722;
-            if (!Number.isFinite(error)) { throw new Error('Non-finite convergence sample'); }
-            squared_error += error * error; bias += error; count++;
-        }
-    }
-    if (!count) { throw new Error('No reflection pixels in convergence sample'); }
-    return { pixels: count, mse: squared_error / count, rmse: Math.sqrt(squared_error / count), bias: bias / count };
-}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { f32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
+
+const settings = WebGPUStruct.from({ count: f32 });
+const resources = new ShaderResourceSetDescriptor();
+resources.setImmediate('settings', settings);
+resources.createGroup().addTexture('tInput', 'unfilterable-float').addTexture('tPrevious', 'unfilterable-float');
+const shader = new ImageShader({ descriptor: ShaderDescriptor.from({
+    label: 'SSR lab / later-sample reference', resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@fragment fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let p = vec2i(coord.xy);
+    let sample = textureLoad(tInput, p, 0);
+    if (settings.count <= 1.0) { return sample; }
+    let previous = textureLoad(tPrevious, p, 0);
+    return previous + (sample - previous) / settings.count;
+}`, [settings.declaration_chunk]),
+}), targets: [{ format: 'rgba32float' }] });
+
+/** Unclipped float32 average of later pre-temporal samples, never fed into rendering. */
+export class ReflectionReference extends RenderExtension {
+    name = 'SSR lab / later-sample reference';
+    enabled = false;
+    count = 0;
+    textures = [];
+    constructor(device) { super(); this.device = device; }
+    record(frame) {
+        if (!this.enabled) { return; }
+        const temporal = frame.graph.__pass_nodes.find(p => p.name.startsWith('SSR Reproject'));
+        if (!temporal) { throw new Error('SSR is required for a reflection reference'); }
+        if (!this.textures.length) {
+            for (let i = 0; i < 2; i++) {
+                this.textures.push(GPUTextureContext.fromTexture(this.device.createTexture({
+                    size: [frame.resolution[0], frame.resolution[1], 1], format: 'rgba32float',
+                    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+                }), this.device));
+            }
+        }
+        const index = this.count % 2;
+        const previous = graph_import_texture(frame.graph, this.textures[1 - index], 'SSR reference previous');
+        const output = graph_import_texture(frame.graph, this.textures[index], 'SSR reference output');
+        graph_image_pass({ graph: frame.graph, shader,
+            inputs: { tInput: temporal.data.tInput, tPrevious: previous, settings: { count: this.count + 1 } },
+            output: [output] });
+        this.count++;
+    }
+    async read() {
+        if (!this.count) { throw new Error('Reference has no samples'); }
+        return download_texture_data({ device: this.device,
+            source: this.textures[(this.count - 1) % 2].gpu_texture });
+    }
+}
+
+export function reflection_error(sample, reference, mask, width, height) {
+    let count = 0, squared_error = 0, bias = 0;
+    for (let y = Math.floor(height * 0.5); y < Math.floor(height * 0.92); y++) {
+        for (let x = Math.floor(width * 0.25); x < Math.floor(width * 0.75); x++) {
+            const p = (y * width + x) * 4;
+            if (mask[p] <= 0.5) { continue; }
+            const error = (sample[p] - reference[p]) * 0.2126
+                + (sample[p + 1] - reference[p + 1]) * 0.7152
+                + (sample[p + 2] - reference[p + 2]) * 0.0722;
+            if (!Number.isFinite(error)) { throw new Error('Non-finite convergence sample'); }
+            squared_error += error * error; bias += error; count++;
+        }
+    }
+    if (!count) { throw new Error('No reflection pixels in convergence sample'); }
+    return { pixels: count, mse: squared_error / count, rmse: Math.sqrt(squared_error / count), bias: bias / count };
+}

package/src/shade/playground/vsm/README.md

@@ -0,0 +1,96 @@
+# Virtual shadow maps
+
+`npm run dev`, then `/src/shade/playground/vsm/`.
+
+A directional light's virtual shadow map — a clipmap of 128-texel pages around the camera, rendered
+into a pool in the shadow atlas as the view asks for them and as moving casters make them stale,
+under a budget of page updates per frame. The design is in
+`src/shade/renderer/shadow/vsm/PLAN.md`.
+
+## Scenes
+
+* **Courtyard.** Structure at every scale the clipmap covers: 5 cm fence slats by the camera, pillars
+  and walls, an overhang, thin poles twenty metres off, and an avenue reaching two hundred metres.
+  The movers each exercise a different case of the GPU mover pass:
+  - orbiting boxes (translation);
+  - a bobbing column;
+  - a turning bar (a rotation about its own centre);
+  - a block that blinks in and out of the scene (a row appearing and leaving).
+* **Crowd.** N wandering boxes, adjustable from 50 to 6000, added to or taken from the same scene.
+  Past 4096 the mover list overflows and every occupied page is taken to be stale, which the stats
+  say.
+
+## Controls
+
+* **Technique.** Virtual shadow map, or the engine's cascades for an A/B comparison in the same
+  scene.
+* **Page updates per frame.** `Renderer.shadow_virtual_page_budget`. Pages wanted beyond it wait,
+  best first:
+  - covers for unshadowed pixels come first;
+  - then stale and missing pages, by the importance of the pixels asking × frames waited. A
+    pixel's importance is its weight under the automatic exposure's metering mask: full over most of
+    the screen, falling toward its edges, so the middle of the view resolves first.
+* **LOD bias, finest texel.** `shadow_virtual_lod_bias`, `shadow_virtual_first_texel_size`. The texel
+  size rebuilds the map.
+* **Pause page updates** sets the budget to 0: no page is drawn or installed, so a stale page stays
+  as it was last drawn and a missing one stays missing. Pages still leave when the camera scrolls
+  their window past them, and all of them when the sun turns.
+* **Sweep the sun / Nudge the sun.** Any change of light direction invalidates every page; see
+  "Known limits" in the plan.
+
+## Debug views
+
+* **Overlay** — what shadows each pixel. It runs the same lookup the lighting does:
+  - **Serving level**: the level of the page that shadows the pixel, red (finest) through to violet.
+  - **Resolution deficit**: how many levels coarser that page is than the level the pixel asked for.
+    Green means exactly the level asked for, yellow one coarser, orange two, red more. Magenta means
+    nothing resident covers the pixel at all.
+  - **Page IDs and edges**: a colour per page, its edges drawn at its own resolution.
+* **Physical pool inset** (bottom left): every slot of the pool, its depth banded every 2 m along the
+  light. Slot edges are tinted by the page's level, and grey where the slot is empty. A slot the page
+  manager holds stale (a mover crossed it and it has not been drawn since) is washed red all over.
+* **Clipmap panel**: the CPU's view of each level's window, one pixel per page, light-space y up.
+  - green: resident; white: drawn this frame; red: stale;
+  - amber: wanted by the latest reading and missing;
+  - cyan cross: the camera.
+  
+  "Panel shows" picks one level, drawn large.
+* **State**: what the page manager did. This frame: pages drawn and waiting. The latest reading:
+  wanted, uncovered, dropped. Also movers, stale marks, installs and evictions, invalidations, and
+  readbacks in flight.
+
+`T` records a GPU profile (`.sgpt`).
+
+## Console
+
+* `vsm_lab.map()` is the `VirtualShadowMap`; `vsm_lab.stats()` copies its page manager's stats.
+* `await vsm_lab.configure({ id: value, … })` sets controls by element id; a `scene` or `crowd`
+  change is in place when it resolves.
+* `vsm_lab.frame_preset('near' | 'overview' | 'avenue' | 'crowd')`.
+* `await verify()` holds the movers and the sun still and waits for the pages to settle: a reading
+  recorded after the stop that asks for pages and leaves nothing uncovered or waiting. It then holds
+  page updates, reads the light database back from the GPU, and checks:
+  - every row the map claimed came back, and its record names its runs and depth range;
+  - every page-table entry, slot row and window corner equals the CPU's;
+  - on the GPU alone, every resident entry's slot holds a page of the entry's own cell;
+  - no page is held twice.
+
+  It returns `{ pass, checks, stats }`, and puts the controls back as they were.
+
+## Measured (RTX 4090, headless Chrome, 1600×900, 2026-10-04)
+
+Courtyard, near camera, movers animating. GPU time per frame, paired arms in one launch:
+
+| arm | frame p50 | pages drawn / frame |
+|---|---|---|
+| VSM, budget 0 (feedback only) | 734–758 µs | 0 |
+| VSM, budget 1 | 779–795 µs | 1.0 |
+| VSM, budget 8 | 1072–1076 µs | 7.1–7.5 |
+| cascades (3) | 1273–1305 µs | — |
+
+- The feedback passes (`VSM/*`) cost about 59 µs a frame, 46 µs of it the demand pass at 1600×900.
+- A page costs about 40–45 µs of GPU time and about 85 µs of CPU in `render()`. CPU p50 per frame
+  is 1.3 ms at budget 0, 2.0 ms at budget 8, 2.0 ms with cascades, and 3.1–3.3 ms at budget 32 (17
+  pages drawn).
+- `verify()` passes: settled four frames after the movers stopped; 49,152 page-table entries, 900
+  slots and 12 windows agree.

package/src/shade/playground/vsm/VSMDebugOverlay.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What the overlay shows over the picture.
+ */
+export type VSMDebugView = number;
+export namespace VSMDebugView {
+    let None: number;
+    let ServingLevel: number;
+    let Deficit: number;
+    let Pages: number;
+}
+/**
+ * The playground's view into a virtual shadow map, drawn over the frame before it is presented:
+ * a tint per pixel saying what shadows it ({@link VSMDebugView}), and an inset of the physical pool
+ * — every slot's depth, its edge tinted by its page's level, washed red where the page manager holds
+ * it stale (a mover crossed it and it has not been drawn since), its edge grey where it is empty.
+ *
+ * The tint runs the lighting's own page lookup on the frame's light database rows, so the page it
+ * names for a pixel is the page the lighting samples there. The stale state is the CPU's, uploaded
+ * each frame the inset is drawn.
+ */
+export class VSMDebugOverlay extends RenderExtension {
+    /**
+     * @param {import("../../renderer/GraphicsContext.js").GraphicsContext} graphics
+     */
+    constructor(graphics: import("../../renderer/GraphicsContext.js").GraphicsContext);
+    /**
+     * @type {number} a {@link VSMDebugView}
+     */
+    mode: number;
+    /**
+     * Whether to draw the pool inset.
+     * @type {boolean}
+     */
+    inset: boolean;
+    /**
+     * The map to show; the overlay draws nothing without one.
+     * @type {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap|null}
+     */
+    map: import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap | null;
+    /**
+     * The shadow context whose atlas the map's pool is in.
+     * @type {import("../../renderer/shadow/map/GPUSceneShadowmapContext.js").GPUSceneShadowmapContext|null}
+     */
+    shadows: import("../../renderer/shadow/map/GPUSceneShadowmapContext.js").GPUSceneShadowmapContext | null;
+    destroy(): void;
+    #private;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=VSMDebugOverlay.d.ts.map

package/src/shade/playground/vsm/VSMDebugOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VSMDebugOverlay.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vsm/VSMDebugOverlay.js"],"names":[],"mappings":";;;2BAyBU,MAAM;;;;;;;AA2LhB;;;;;;;;;GASG;AACH;IAuCI;;OAEG;IACH,sBAFW,OAAO,mCAAmC,EAAE,eAAe,EAMrE;IAzCD;;OAEG;IACH,MAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,OAFU,OAAO,CAEH;IAEd;;;OAGG;IACH,KAFU,OAAO,+CAA+C,EAAE,gBAAgB,GAAC,IAAI,CAE5E;IAEX;;;OAGG;IACH,SAFU,OAAO,uDAAuD,EAAE,wBAAwB,GAAC,IAAI,CAExF;IAiGf,gBAIC;;CACJ;gCA3V+B,6CAA6C"}