@woosh/meep-engine 3.39.0 → 3.41.0

package/src/shade/renderer/shadow/vsm/VSMMoverTracker.js

@@ -0,0 +1,153 @@
+import { assert } from "../../../../core/assert.js";
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import {
+    VSM_EMPTY_BOUND,
+    VSM_LAST_SEEN_GEOMETRY,
+    VSM_LAST_SEEN_MATERIAL,
+    VSM_LAST_SEEN_WORDS
+} from "./VSM_MOVER_LAYOUT.js";
+
+/**
+ * The scene's memory of where its casters were and what they were: {@link VSM_LAST_SEEN_WORDS} per
+ * row of the `meshes` table — the world box {@link shader_vsm_movers} saw each row with last frame,
+ * and its geometry and material — empty for a row that held nothing. Comparing against it is how the
+ * mover pass sees a row appear, leave, change shape or change mesh, which no per-row fact of the
+ * scene database says.
+ *
+ * Covers every row the table has ever had — a high-water mark, so a page of rows that was freed
+ * still gets compared once more and its casters' old shadows found. Grows by doubling; a grown
+ * buffer starts empty and takes the old one's rows by a copy recorded in the next mover pass, in
+ * order with the rest of the frame.
+ */
+export class VSMMoverTracker {
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GPUBuffer|null}
+     */
+    #buffer = null;
+
+    /**
+     * Rows {@link #buffer} covers.
+     * @type {number}
+     */
+    #rows = 0;
+
+    /**
+     * The buffer before the last growth, until the next pass has copied it over.
+     * @type {GPUBuffer|null}
+     */
+    #retired = null;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+    }
+
+    /**
+     * @returns {GPUBuffer|null}
+     */
+    get buffer() {
+        return this.#buffer;
+    }
+
+    /**
+     * @returns {number} rows the buffer covers
+     */
+    get row_count() {
+        return this.#rows;
+    }
+
+    /**
+     * Cover at least `rows` rows.
+     *
+     * @param {number} rows
+     */
+    ensure(rows) {
+        assert.isNonNegativeInteger(rows, 'rows');
+
+        if (rows <= this.#rows) {
+            return;
+        }
+
+        const capacity = Math.max(rows, this.#rows * 2);
+
+        const buffer = this.#device.createBuffer({
+            label: 'VSM / casters last seen',
+            size: capacity * VSM_LAST_SEEN_WORDS * Uint32Array.BYTES_PER_ELEMENT,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            mappedAtCreation: true,
+        });
+
+        const range = buffer.getMappedRange();
+        const floats = new Float32Array(range);
+        const words = new Uint32Array(range);
+
+        for (let i = 0; i < capacity; i++) {
+            const base = i * VSM_LAST_SEEN_WORDS;
+
+            floats[base] = VSM_EMPTY_BOUND;
+            floats[base + 1] = VSM_EMPTY_BOUND;
+            floats[base + 2] = VSM_EMPTY_BOUND;
+            floats[base + 3] = -VSM_EMPTY_BOUND;
+            floats[base + 4] = -VSM_EMPTY_BOUND;
+            floats[base + 5] = -VSM_EMPTY_BOUND;
+            words[base + VSM_LAST_SEEN_GEOMETRY] = GPU_DATABASE_NULL;
+            words[base + VSM_LAST_SEEN_MATERIAL] = GPU_DATABASE_NULL;
+        }
+
+        buffer.unmap();
+
+        if (this.#retired !== null) {
+            // grown twice before a pass ran: the older copy never landed, and the newer one holds
+            // nothing yet either — take the rows from the oldest
+            this.#buffer.destroy();
+        } else {
+            this.#retired = this.#buffer;
+        }
+
+        this.#buffer = buffer;
+        this.#rows = capacity;
+    }
+
+    /**
+     * Record the copy of the rows the buffer had before it grew, if it did since the last call, and
+     * let the old buffer go once the frame is done with it.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     */
+    encode_growth(encoder) {
+        const retired = this.#retired;
+
+        if (retired === null) {
+            return;
+        }
+
+        this.#retired = null;
+
+        encoder.copyBufferToBuffer(retired, 0, this.#buffer, 0, retired.size);
+        encoder.onFinished.addOne(() => retired.destroy());
+    }
+
+    destroy() {
+        if (this.#retired !== null) {
+            this.#retired.destroy();
+            this.#retired = null;
+        }
+
+        if (this.#buffer !== null) {
+            this.#buffer.destroy();
+            this.#buffer = null;
+        }
+
+        this.#rows = 0;
+    }
+}

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts

@@ -0,0 +1,327 @@
+/**
+ * The CPU half of a virtual shadow map: what is resident where, what the GPU said it wanted and
+ * what it said went stale, and which pages to render this frame.
+ *
+ * It holds no GPU resource and draws nothing. The GPU's feedback comes in through
+ * {@link apply_reading}; the frame's pages go out through the job list {@link select} fills; and
+ * the rows the GPU reads — page-table entries, slot pages, window corners — change only as pages
+ * are installed, evicted and scrolled away, which the dirty lists say ({@link dirty_cell_count} and
+ * friends), so that writing them is O(what changed).
+ *
+ * **The clipmap.** `level_count` levels; a page of level `k` is `page_size · first_texel_size · 2^k`
+ * world units on a side, anchored to the world in light space. Each level keeps a window of
+ * `pages_per_level²` pages around the camera ({@link update_windows}), and a page of the window sits
+ * in cell `(x mod N, y mod N)` of the level — so a window that scrolls keeps every page still inside
+ * it where it was, and gives back only the pages it left behind.
+ *
+ * **The pool** is a {@link VTPhysicalSlots}: VT's slot grid, least-recently-touched eviction outside
+ * a protection window, and the finest page shed first on a tie.
+ *
+ * **What is rendered.** Each reading replaces the want set — it is a whole frame's snapshot — and
+ * {@link select} turns it into candidates for a max-heap, drained to the frame's budget:
+ * 1. first, a **cover** for every page that is missing with nothing coarser resident: one page
+ *    {@link VSM_COVER_LEVEL_STEP} levels up, which gives every pixel under it a shadow at once,
+ *    ordered by the importance of the pixels under it;
+ * 2. then the **updates** — a stale page something still looks at (wanted itself, or standing in
+ *    for a wanted one), and a missing page something coarser stands in for meanwhile — ordered by
+ *    the importance of the pixels asking times the frames waited, so that neither kind can starve
+ *    the other.
+ *
+ * A pixel's importance is its weight under the screen importance mask, the automatic exposure's
+ * metering mask: full over most of the screen, less toward its edges.
+ */
+export class VSMPageManager {
+    /**
+     * @param {Object} options
+     * @param {number} options.level_count
+     * @param {number} options.pages_per_level a power of two
+     * @param {number} options.first_texel_size world size of a level-0 texel
+     * @param {number} options.page_size texels on a page's side, without the border
+     * @param {number} options.border texels of border each side
+     * @param {number} options.pool_size texels on the pool's side
+     * @param {number} options.request_capacity requests a reading holds at most
+     * @param {number} options.protect_frames frames a touched page is safe from eviction for
+     */
+    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, }: {
+        level_count: number;
+        pages_per_level: number;
+        first_texel_size: number;
+        page_size: number;
+        border: number;
+        pool_size: number;
+        request_capacity: number;
+        protect_frames: number;
+    });
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly level_count: number;
+    /**
+     * A window's side, in pages. A power of two.
+     * @type {number}
+     * @readonly
+     */
+    readonly pages_per_level: number;
+    /**
+     * World size of a level-0 texel.
+     * @type {number}
+     * @readonly
+     */
+    readonly first_texel_size: number;
+    /**
+     * Texels on a page's side, without the border.
+     * @type {number}
+     * @readonly
+     */
+    readonly page_size: number;
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly border: number;
+    /**
+     * The pool's slot bookkeeping.
+     * @type {VTPhysicalSlots}
+     * @readonly
+     */
+    readonly slots: VTPhysicalSlots;
+    /**
+     * Requests a reading holds at most — the feedback buffer's capacity.
+     * @type {number}
+     * @readonly
+     */
+    readonly request_capacity: number;
+    /**
+     * Frames a touched page is safe from eviction for. Has to outlast the readback, or a page in
+     * view is evicted between the frame that asked for it and the reading that says so.
+     * @type {number}
+     * @readonly
+     */
+    readonly protect_frames: number;
+    /**
+     * What the manager did, cumulative since construction except where noted.
+     */
+    stats: {
+        /** wants in the latest reading */
+        wants: number;
+        /** wants the latest {@link select} found with nothing resident to stand in for them */
+        uncovered: number;
+        /** candidates the latest {@link select} left for later frames, those it found no slot for included */
+        backlog: number;
+        /** pages rendered by the latest {@link select} */
+        renders: number;
+        /** movers in the latest reading, and whether there were more than the GPU could list */
+        movers: number;
+        /** requests the GPU dropped past its capacity, in the latest reading */
+        requests_dropped: number;
+        readings_applied: number;
+        readings_dropped: number;
+        installs: number;
+        evictions: number;
+        scroll_evictions: number;
+        refused: number;
+        stale_marked: number;
+        invalidations: number;
+        re_rendered: number;
+    };
+    /**
+     * Cells of every level: the length of the page table.
+     * @returns {number}
+     */
+    get cell_count(): number;
+    /**
+     * World units on the side of a page of a level.
+     *
+     * @param {number} level
+     * @returns {number}
+     */
+    page_world_size(level: number): number;
+    /**
+     * The page-table row, from the map's first, of a world page's cell.
+     *
+     * @param {number} level
+     * @param {number} x world page
+     * @param {number} y world page
+     * @returns {number}
+     */
+    cell_of(level: number, x: number, y: number): number;
+    /**
+     * @param {number} level
+     * @returns {number} the level's window corner, world pages
+     */
+    origin_x(level: number): number;
+    /**
+     * @param {number} level
+     * @returns {number}
+     */
+    origin_y(level: number): number;
+    /**
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @returns {boolean}
+     */
+    window_contains(level: number, x: number, y: number): boolean;
+    /**
+     * The slot holding a world page, or -1 when it is not resident or not in its level's window.
+     *
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @returns {number}
+     */
+    slot_of_page(level: number, x: number, y: number): number;
+    /**
+     * Place every level's window around the camera, giving back the pages a window leaves behind.
+     *
+     * @param {number} light_x the camera, across the light
+     * @param {number} light_y
+     */
+    update_windows(light_x: number, light_y: number): void;
+    /**
+     * Take the light space the pages are drawn in. A light space that differs from the last one —
+     * the light turned, or the depth range moved — invalidates every page: the want set is carried
+     * into the new light space through the receiver point each want recorded, every page is given
+     * back, and readings recorded before `frame` are refused.
+     *
+     * @param {ArrayLike<number>} view world to light space, column-major, rotation only
+     * @param {number} near
+     * @param {number} far
+     * @param {number} frame
+     * @returns {boolean} whether the pages were invalidated
+     */
+    set_light_space(view: ArrayLike<number>, near: number, far: number, frame: number): boolean;
+    /**
+     * Take a frame's feedback: the pages wanted, which become the want set, and the slots a mover
+     * crossed. A reading recorded under a light space that has since been replaced has its wants
+     * carried into the current one through the view it was recorded under; one older than every
+     * light space remembered, or older than a reading already applied, is refused.
+     *
+     * @param {Uint32Array} words the feedback buffer, {@link VSM_FEEDBACK_LAYOUT}
+     * @param {Float32Array} floats the same words as f32
+     * @param {number} reading_frame the frame the GPU recorded it in
+     * @returns {boolean} whether it was applied
+     */
+    apply_reading(words: Uint32Array, floats: Float32Array, reading_frame: number): boolean;
+    /**
+     * Choose and claim this frame's pages: candidates from the want set into the heap, then drained
+     * best first until `budget` pages are to be rendered. A missing page takes a free slot, or the
+     * least recently touched one outside the protection window; when there is none it is refused
+     * and the next candidate is tried. Fills the job list.
+     *
+     * @param {number} frame
+     * @param {number} budget pages to render at most
+     */
+    select(frame: number, budget: number): void;
+    /**
+     * The page-table entry of a cell: the slot holding it, as {@link vt_entry_pack} packs it, or
+     * {@link VT_ENTRY_INVALID}.
+     *
+     * @param {number} cell
+     * @returns {number}
+     */
+    cell_entry(cell: number): number;
+    /**
+     * @param {number} cell
+     * @returns {number} the slot holding the cell's page, or -1
+     */
+    cell_slot(cell: number): number;
+    /**
+     * @returns {number} cells whose entry changed since {@link clear_dirty}
+     */
+    get dirty_cell_count(): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    dirty_cell(i: number): number;
+    /**
+     * @returns {number} slots whose page changed since {@link clear_dirty}
+     */
+    get dirty_slot_count(): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    dirty_slot(i: number): number;
+    /**
+     * @returns {boolean} whether a window moved since {@link clear_dirty}
+     */
+    get levels_dirty(): boolean;
+    /**
+     * Forget what changed: the rows have been written.
+     */
+    clear_dirty(): void;
+    /**
+     * @param {number} slot
+     * @returns {number} the level of the slot's page, or -1 when it is empty
+     */
+    slot_level(slot: number): number;
+    /**
+     * @param {number} slot
+     * @returns {number}
+     */
+    slot_x(slot: number): number;
+    /**
+     * @param {number} slot
+     * @returns {number}
+     */
+    slot_y(slot: number): number;
+    /**
+     * @param {number} slot
+     * @returns {boolean} whether a mover crossed the slot's page after it was last rendered
+     */
+    slot_stale(slot: number): boolean;
+    /**
+     * @param {number} slot
+     * @returns {number} the frame it was last rendered in, or -1
+     */
+    slot_rendered_frame(slot: number): number;
+    /**
+     * @returns {number} wants in the want set
+     */
+    get want_count(): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_level(i: number): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_x(i: number): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_y(i: number): number;
+    /**
+     * @returns {number} pages {@link select} chose to render
+     */
+    get job_count(): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_slot(i: number): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_level(i: number): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_x(i: number): number;
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_y(i: number): number;
+    #private;
+}
+import { VTPhysicalSlots } from "../../texture/virtual/VTPhysicalSlots.js";
+//# sourceMappingURL=VSMPageManager.d.ts.map

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VSMPageManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMPageManager.js"],"names":[],"mappings":"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"}