@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,1408 @@
+import { assert } from "../../../../core/assert.js";
+import { IndexedFloatMaxHeap } from "../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { VT_ENTRY_INVALID, VT_ENTRY_PHYS_MASK, vt_entry_pack } from "../../texture/virtual/VT_CONSTANTS.js";
+import { VTPhysicalSlots } from "../../texture/virtual/VTPhysicalSlots.js";
+import { VSM_COVER_LEVEL_STEP } from "./VSM_COVER_LEVEL_STEP.js";
+import { VSM_FEEDBACK_LAYOUT, vsm_feedback_stale_offset } from "./VSM_FEEDBACK_LAYOUT.js";
+import { VSM_LEVEL_LIMIT } from "./VSM_LEVEL_LIMIT.js";
+
+/**
+ * Candidate kinds. A **cover** — a page several levels up that gives pixels with nothing resident
+ * above them a shadow at all — is served before anything else. Everything else is an **update**: a
+ * resident page that went stale under a mover while something looks at it, or a missing page that
+ * something coarser stands in for meanwhile.
+ */
+const KIND_UPDATE = 1;
+const KIND_COVER = 2;
+
+/**
+ * What a cover scores above: an update scores `log2((1 + importance)(1 + frames waited))`, which
+ * stays under 64 for any screen's importance and any frame count a session reaches.
+ */
+const COVER_SCORE = 128;
+
+/**
+ * Light spaces remembered: the view each recent light space began with, so that a reading recorded
+ * under one that has since been replaced can be carried into the current one rather than refused.
+ * A reading is at most a few frames old — three readbacks in flight — and a light turning every frame
+ * replaces its light space every frame, so sixteen is room to spare.
+ */
+const LIGHT_SPACE_HISTORY = 16;
+
+/**
+ * Where a page of a level lands when carried from one light view to another, through a receiver
+ * point at the page's centre and a depth along the old light: back to the world through the old
+ * view's transpose — light views are rotations — and into the new view. Exact for the point,
+ * approximate for the page.
+ *
+ * @param {ArrayLike<number>} from view the page was asked for under
+ * @param {number} from_offset where that view starts in `from`
+ * @param {ArrayLike<number>} to view to carry it into
+ * @param {number} size world size of a page of the level
+ * @param {number} x page
+ * @param {number} y page
+ * @param {number} depth along the old light
+ * @param {Float64Array} out [x, y, depth] in the new view
+ */
+function carry_page(from, from_offset, to, size, x, y, depth, out) {
+    const f = from_offset;
+
+    // light space as the old view saw it; its view z is the depth negated
+    const lx = (x + 0.5) * size - from[f + 12];
+    const ly = (y + 0.5) * size - from[f + 13];
+    const lz = -depth - from[f + 14];
+
+    const wx = from[f] * lx + from[f + 1] * ly + from[f + 2] * lz;
+    const wy = from[f + 4] * lx + from[f + 5] * ly + from[f + 6] * lz;
+    const wz = from[f + 8] * lx + from[f + 9] * ly + from[f + 10] * lz;
+
+    const nx = to[0] * wx + to[4] * wy + to[8] * wz + to[12];
+    const ny = to[1] * wx + to[5] * wy + to[9] * wz + to[13];
+    const nz = to[2] * wx + to[6] * wy + to[10] * wz + to[14];
+
+    out[0] = Math.floor(nx / size);
+    out[1] = Math.floor(ny / size);
+    out[2] = -nz;
+}
+
+/**
+ * A candidate's score.
+ *
+ * Updates compete by the importance of the pixels asking — their count, weighted by where they are
+ * on screen — times the frames they have waited: the weighting `compute_shadowmap_update_score`
+ * gives a local light's shadow map, area times staleness. A page
+ * kept stale by a mover is re-marked from zero each time it is redrawn, while a missing page's wait
+ * only grows until it arrives, so under constant motion the missing page still gets its turn: a
+ * strict "stale before missing" order starved it for as long as anything moved.
+ *
+ * In log2, so a float32 heap orders it exactly enough.
+ *
+ * @param {number} kind
+ * @param {number} importance of the pixels asking, as the demand pass sums it
+ * @param {number} waited frames
+ * @returns {number}
+ */
+function candidate_score(kind, importance, waited) {
+    if (kind === KIND_COVER) {
+        return COVER_SCORE + Math.log2(1 + importance);
+    }
+
+    return Math.log2((1 + importance) * (1 + waited));
+}
+
+/**
+ * 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 {
+
+    /**
+     * @type {number}
+     * @readonly
+     */
+    level_count;
+
+    /**
+     * A window's side, in pages. A power of two.
+     * @type {number}
+     * @readonly
+     */
+    pages_per_level;
+
+    /**
+     * World size of a level-0 texel.
+     * @type {number}
+     * @readonly
+     */
+    first_texel_size;
+
+    /**
+     * Texels on a page's side, without the border.
+     * @type {number}
+     * @readonly
+     */
+    page_size;
+
+    /**
+     * @type {number}
+     * @readonly
+     */
+    border;
+
+    /**
+     * The pool's slot bookkeeping.
+     * @type {VTPhysicalSlots}
+     * @readonly
+     */
+    slots;
+
+    /**
+     * Requests a reading holds at most — the feedback buffer's capacity.
+     * @type {number}
+     * @readonly
+     */
+    request_capacity;
+
+    /**
+     * 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
+     */
+    protect_frames;
+
+    /**
+     * Per window cell of every level, the slot holding it, or -1.
+     * @type {Int32Array}
+     */
+    #cell_slot;
+
+    /**
+     * Per slot, the level of its page, or -1 for an empty slot.
+     * @type {Int32Array}
+     */
+    #slot_level;
+
+    /**
+     * Per slot, its page's world coordinates.
+     * @type {Int32Array}
+     */
+    #slot_x;
+
+    /**
+     * @type {Int32Array}
+     */
+    #slot_y;
+
+    /**
+     * Per slot, 1 when a mover crossed it after it was last rendered.
+     * @type {Uint8Array}
+     */
+    #slot_stale;
+
+    /**
+     * Per slot, the frame it was last rendered in, or -1.
+     * @type {Float64Array}
+     */
+    #slot_rendered;
+
+    /**
+     * Per slot, the frame of the reading that marked it stale — how long a stale page has waited.
+     * @type {Float64Array}
+     */
+    #slot_stale_since;
+
+    /**
+     * Per cell, the frame a missing page started waiting, and the {@link select} it was last offered
+     * in — a page is waiting only while every select offers it.
+     * @type {Float64Array}
+     */
+    #cell_wait_since;
+    #cell_wait_select;
+    #select_index = 0;
+
+    /**
+     * Per level, the window's corner in world pages.
+     * @type {Int32Array}
+     */
+    #origin_x;
+
+    /**
+     * @type {Int32Array}
+     */
+    #origin_y;
+
+    /**
+     * Whether {@link update_windows} has placed the windows yet.
+     * @type {boolean}
+     */
+    #windows_placed = false;
+
+    /**
+     * The want set: the latest reading's requests, in its order.
+     */
+    #want_level;
+    #want_x;
+    #want_y;
+    #want_importance;
+    #want_depth;
+    #want_count = 0;
+
+    /**
+     * Recent light spaces, oldest overwritten first: each one's view, and the frame it began in.
+     */
+    #history_views = new Float64Array(LIGHT_SPACE_HISTORY * 16);
+    #history_frames = new Float64Array(LIGHT_SPACE_HISTORY).fill(Infinity);
+    #history_next = 0;
+
+    /**
+     * Where {@link carry_page} leaves a carried page.
+     */
+    #carried = new Float64Array(3);
+
+    /**
+     * The frame of the latest reading applied; an older one arriving late is not applied.
+     * @type {number}
+     */
+    #last_reading_frame = -Infinity;
+
+    /**
+     * The light space the pages were drawn in: the light view, and its depth range.
+     * @type {Float64Array}
+     */
+    #view = new Float64Array(16);
+    #near = 0;
+    #far = 0;
+    #light_space_set = false;
+
+    /**
+     * Candidate bookkeeping, per cell of every level: the heap, the stamp of the {@link select} that
+     * offered the cell, its kind, and the importance behind it.
+     */
+    #heap;
+    #candidate_stamp;
+    #candidate_kind;
+    #candidate_importance;
+    #candidate_waited;
+    #stamp = 0;
+
+    /**
+     * The frame's jobs: a slot to render and the page it holds.
+     */
+    #job_slot;
+    #job_level;
+    #job_x;
+    #job_y;
+    #job_count = 0;
+
+    /**
+     * Rows that changed since {@link clear_dirty}.
+     */
+    #dirty_cells;
+    #dirty_cell_mark;
+    #dirty_cell_count = 0;
+    #dirty_slots;
+    #dirty_slot_mark;
+    #dirty_slot_count = 0;
+    #levels_dirty = false;
+
+    /**
+     * What the manager did, cumulative since construction except where noted.
+     */
+    stats = {
+        /** wants in the latest reading */
+        wants: 0,
+        /** wants the latest {@link select} found with nothing resident to stand in for them */
+        uncovered: 0,
+        /** candidates the latest {@link select} left for later frames, those it found no slot for included */
+        backlog: 0,
+        /** pages rendered by the latest {@link select} */
+        renders: 0,
+        /** movers in the latest reading, and whether there were more than the GPU could list */
+        movers: 0,
+        /** requests the GPU dropped past its capacity, in the latest reading */
+        requests_dropped: 0,
+        readings_applied: 0,
+        readings_dropped: 0,
+        installs: 0,
+        evictions: 0,
+        scroll_evictions: 0,
+        refused: 0,
+        stale_marked: 0,
+        invalidations: 0,
+        re_rendered: 0,
+    };
+
+    /**
+     * @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,
+                }) {
+        assert.isPositiveInteger(level_count, 'level_count');
+        assert.lessThanOrEqual(level_count, VSM_LEVEL_LIMIT, 'level_count');
+        assert.isPositiveInteger(pages_per_level, 'pages_per_level');
+        assert.ok(isPowerOfTwo(pages_per_level), 'pages_per_level must be a power of two');
+        assert.greaterThanOrEqual(pages_per_level, 2, 'pages_per_level');
+        assert.isNumber(first_texel_size, 'first_texel_size');
+        assert.greaterThan(first_texel_size, 0, 'first_texel_size');
+        assert.isPositiveInteger(page_size, 'page_size');
+        assert.isNonNegativeInteger(border, 'border');
+        assert.isPositiveInteger(pool_size, 'pool_size');
+        assert.isPositiveInteger(request_capacity, 'request_capacity');
+        assert.isPositiveInteger(protect_frames, 'protect_frames');
+
+        this.level_count = level_count;
+        this.pages_per_level = pages_per_level;
+        this.first_texel_size = first_texel_size;
+        this.page_size = page_size;
+        this.border = border;
+        this.request_capacity = request_capacity;
+        this.protect_frames = protect_frames;
+
+        const slots = this.slots = new VTPhysicalSlots({ atlas_size: pool_size, page_size, border });
+
+        // a page-table entry names its slot in eight bits a side
+        assert.lessThanOrEqual(slots.slots_per_axis, VT_ENTRY_PHYS_MASK + 1, 'slots per pool side');
+
+        const cell_count = level_count * pages_per_level * pages_per_level;
+        const capacity = slots.capacity;
+
+        this.#cell_slot = new Int32Array(cell_count).fill(-1);
+
+        this.#slot_level = new Int32Array(capacity).fill(-1);
+        this.#slot_x = new Int32Array(capacity);
+        this.#slot_y = new Int32Array(capacity);
+        this.#slot_stale = new Uint8Array(capacity);
+        this.#slot_rendered = new Float64Array(capacity).fill(-1);
+        this.#slot_stale_since = new Float64Array(capacity);
+
+        this.#origin_x = new Int32Array(level_count);
+        this.#origin_y = new Int32Array(level_count);
+
+        this.#want_level = new Uint8Array(request_capacity);
+        this.#want_x = new Int32Array(request_capacity);
+        this.#want_y = new Int32Array(request_capacity);
+        this.#want_importance = new Uint32Array(request_capacity);
+        this.#want_depth = new Float32Array(request_capacity);
+
+        this.#heap = new IndexedFloatMaxHeap(cell_count);
+        this.#candidate_stamp = new Uint32Array(cell_count);
+        this.#candidate_kind = new Uint8Array(cell_count);
+        this.#candidate_importance = new Float64Array(cell_count);
+        this.#candidate_waited = new Float64Array(cell_count);
+
+        this.#cell_wait_since = new Float64Array(cell_count);
+        this.#cell_wait_select = new Float64Array(cell_count).fill(-1);
+
+        this.#job_slot = new Uint32Array(capacity);
+        this.#job_level = new Int32Array(capacity);
+        this.#job_x = new Int32Array(capacity);
+        this.#job_y = new Int32Array(capacity);
+
+        this.#dirty_cells = new Uint32Array(cell_count);
+        this.#dirty_cell_mark = new Uint8Array(cell_count);
+        this.#dirty_slots = new Uint32Array(capacity);
+        this.#dirty_slot_mark = new Uint8Array(capacity);
+    }
+
+    /**
+     * Cells of every level: the length of the page table.
+     * @returns {number}
+     */
+    get cell_count() {
+        return this.#cell_slot.length;
+    }
+
+    /**
+     * World units on the side of a page of a level.
+     *
+     * @param {number} level
+     * @returns {number}
+     */
+    page_world_size(level) {
+        return this.page_size * this.first_texel_size * 2 ** level;
+    }
+
+    /**
+     * 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, x, y) {
+        const n = this.pages_per_level;
+        const mask = n - 1;
+
+        return (level * n + (y & mask)) * n + (x & mask);
+    }
+
+    /**
+     * @param {number} level
+     * @returns {number} the level's window corner, world pages
+     */
+    origin_x(level) {
+        return this.#origin_x[level];
+    }
+
+    /**
+     * @param {number} level
+     * @returns {number}
+     */
+    origin_y(level) {
+        return this.#origin_y[level];
+    }
+
+    /**
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @returns {boolean}
+     */
+    window_contains(level, x, y) {
+        const n = this.pages_per_level;
+        const rx = x - this.#origin_x[level];
+        const ry = y - this.#origin_y[level];
+
+        return this.#windows_placed && rx >= 0 && ry >= 0 && rx < n && ry < n;
+    }
+
+    /**
+     * 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, x, y) {
+        if (!this.window_contains(level, x, y)) {
+            return -1;
+        }
+
+        return this.#cell_slot[this.cell_of(level, x, y)];
+    }
+
+    /**
+     * 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, light_y) {
+        assert.isFinite(light_x, 'light_x');
+        assert.isFinite(light_y, 'light_y');
+
+        const half = this.pages_per_level >> 1;
+
+        for (let level = 0; level < this.level_count; level++) {
+            const size = this.page_world_size(level);
+
+            const x = Math.floor(light_x / size) - half;
+            const y = Math.floor(light_y / size) - half;
+
+            const old_x = this.#origin_x[level];
+            const old_y = this.#origin_y[level];
+
+            if (this.#windows_placed) {
+                if (x === old_x && y === old_y) {
+                    continue;
+                }
+
+                this.#evict_vacated(level, old_x, old_y, x, y);
+            }
+
+            this.#origin_x[level] = x;
+            this.#origin_y[level] = y;
+            this.#levels_dirty = true;
+        }
+
+        this.#windows_placed = true;
+    }
+
+    /**
+     * Give back every resident page of a level that its window, moving from one corner to the other,
+     * leaves behind. Walks the strips it vacates, or the whole level when it jumps a window or more.
+     *
+     * @param {number} level
+     * @param {number} old_x
+     * @param {number} old_y
+     * @param {number} new_x
+     * @param {number} new_y
+     */
+    #evict_vacated(level, old_x, old_y, new_x, new_y) {
+        const n = this.pages_per_level;
+
+        if (Math.abs(new_x - old_x) >= n || Math.abs(new_y - old_y) >= n) {
+            const first = level * n * n;
+
+            for (let cell = first; cell < first + n * n; cell++) {
+                const slot = this.#cell_slot[cell];
+
+                if (slot !== -1) {
+                    this.#evict(slot);
+                    this.stats.scroll_evictions++;
+                }
+            }
+
+            return;
+        }
+
+        // the columns of the old window outside the new one, all rows
+        const keep_x0 = Math.max(old_x, new_x);
+        const keep_x1 = Math.min(old_x, new_x) + n;
+
+        for (let x = old_x; x < old_x + n; x++) {
+            if (x >= keep_x0 && x < keep_x1) {
+                continue;
+            }
+
+            for (let y = old_y; y < old_y + n; y++) {
+                this.#evict_page_for_scroll(level, x, y);
+            }
+        }
+
+        // then the rows outside it, over the columns both windows share
+        const keep_y0 = Math.max(old_y, new_y);
+        const keep_y1 = Math.min(old_y, new_y) + n;
+
+        for (let y = old_y; y < old_y + n; y++) {
+            if (y >= keep_y0 && y < keep_y1) {
+                continue;
+            }
+
+            for (let x = keep_x0; x < keep_x1; x++) {
+                this.#evict_page_for_scroll(level, x, y);
+            }
+        }
+    }
+
+    /**
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     */
+    #evict_page_for_scroll(level, x, y) {
+        const slot = this.#cell_slot[this.cell_of(level, x, y)];
+
+        if (slot === -1) {
+            return;
+        }
+
+        this.#evict(slot);
+        this.stats.scroll_evictions++;
+    }
+
+    /**
+     * 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, near, far, frame) {
+        assert.equal(view.length, 16, 'view.length');
+        assert.isFinite(near, 'near');
+        assert.isFinite(far, 'far');
+
+        const current = this.#view;
+
+        if (!this.#light_space_set) {
+            for (let i = 0; i < 16; i++) {
+                current[i] = view[i];
+            }
+
+            this.#near = near;
+            this.#far = far;
+            this.#light_space_set = true;
+
+            this.#remember_light_space(frame);
+
+            return false;
+        }
+
+        let changed = near !== this.#near || far !== this.#far;
+
+        for (let i = 0; i < 16 && !changed; i++) {
+            changed = view[i] !== current[i];
+        }
+
+        if (!changed) {
+            return false;
+        }
+
+        this.#reproject_wants(current, view);
+
+        for (let i = 0; i < 16; i++) {
+            current[i] = view[i];
+        }
+
+        this.#near = near;
+        this.#far = far;
+
+        this.#evict_all();
+
+        this.#remember_light_space(frame);
+        this.stats.invalidations++;
+
+        return true;
+    }
+
+    /**
+     * Remember the current light space as beginning in `frame`.
+     *
+     * @param {number} frame
+     */
+    #remember_light_space(frame) {
+        const i = this.#history_next;
+
+        this.#history_views.set(this.#view, i * 16);
+        this.#history_frames[i] = frame;
+
+        this.#history_next = (i + 1) % LIGHT_SPACE_HISTORY;
+    }
+
+    /**
+     * The remembered light space a reading recorded in `frame` was asked under: the latest one that
+     * began no later than it. -1 when it is older than every one remembered.
+     *
+     * @param {number} frame
+     * @returns {number} history index
+     */
+    #light_space_at(frame) {
+        let best = -1;
+        let best_frame = -Infinity;
+
+        for (let i = 0; i < LIGHT_SPACE_HISTORY; i++) {
+            const began = this.#history_frames[i];
+
+            if (began <= frame && began > best_frame) {
+                best = i;
+                best_frame = began;
+            }
+        }
+
+        return best;
+    }
+
+    /**
+     * Carry the want set from one light space to another, each want through its page centre and
+     * the receiver depth it recorded ({@link carry_page}). The next reading replaces it.
+     *
+     * @param {ArrayLike<number>} from
+     * @param {ArrayLike<number>} to
+     */
+    #reproject_wants(from, to) {
+        const count = this.#want_count;
+        const carried = this.#carried;
+
+        for (let i = 0; i < count; i++) {
+            carry_page(from, 0, to, this.page_world_size(this.#want_level[i]), this.#want_x[i], this.#want_y[i], this.#want_depth[i], carried);
+
+            this.#want_x[i] = carried[0];
+            this.#want_y[i] = carried[1];
+            this.#want_depth[i] = carried[2];
+        }
+    }
+
+    /**
+     * Give back every resident page.
+     */
+    #evict_all() {
+        const capacity = this.slots.capacity;
+
+        for (let slot = 0; slot < capacity; slot++) {
+            if (this.#slot_level[slot] !== -1) {
+                this.#evict(slot);
+            }
+        }
+    }
+
+    /**
+     * 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, floats, reading_frame) {
+        assert.equal(words.buffer, floats.buffer, 'words and floats must view the same memory');
+        assert.equal(words.byteOffset, floats.byteOffset, 'words and floats must start together');
+
+        const recorded_under = reading_frame > this.#last_reading_frame ? this.#light_space_at(reading_frame) : -1;
+
+        if (recorded_under === -1) {
+            this.stats.readings_dropped++;
+            return false;
+        }
+
+        // the light space has changed since: each want goes through the view it was asked under
+        const carry = this.#history_frames[recorded_under] !== this.#history_frames[(this.#history_next + LIGHT_SPACE_HISTORY - 1) % LIGHT_SPACE_HISTORY];
+        const carried = this.#carried;
+
+        this.#last_reading_frame = reading_frame;
+        this.stats.readings_applied++;
+
+        const L = VSM_FEEDBACK_LAYOUT;
+        const capacity = this.request_capacity;
+        const asked = words[L.REQUEST_COUNT];
+        const count = Math.min(asked, capacity);
+
+        this.stats.requests_dropped = asked - count;
+        this.stats.movers = words[L.MOVER_COUNT];
+
+        let wants = 0;
+
+        for (let i = 0; i < count; i++) {
+            const base = L.HEADER_WORDS + i * L.REQUEST_WORDS;
+            const level = words[base + L.REQUEST_LEVEL];
+
+            if (level >= this.level_count) {
+                continue;
+            }
+
+            let x = words[base + L.REQUEST_X] | 0;
+            let y = words[base + L.REQUEST_Y] | 0;
+            let depth = floats[base + L.REQUEST_DEPTH];
+
+            if (carry) {
+                carry_page(this.#history_views, recorded_under * 16, this.#view, this.page_world_size(level), x, y, depth, carried);
+
+                x = carried[0];
+                y = carried[1];
+                depth = carried[2];
+            }
+
+            this.#want_level[wants] = level;
+            this.#want_x[wants] = x;
+            this.#want_y[wants] = y;
+            this.#want_importance[wants] = words[base + L.REQUEST_IMPORTANCE];
+            this.#want_depth[wants] = depth;
+
+            wants++;
+
+            // what the pixels sample — the page, or whatever stands in for it — is in use
+            const slot = this.slot_of_page(level, x, y);
+
+            if (slot !== -1) {
+                this.#touch(slot, reading_frame);
+            } else {
+                const fallback = this.#find_fallback(level, x, y);
+
+                if (fallback !== -1) {
+                    this.#touch(fallback, reading_frame);
+                }
+            }
+        }
+
+        this.#want_count = wants;
+        this.stats.wants = wants;
+
+        const slot_capacity = this.slots.capacity;
+        const stale_offset = vsm_feedback_stale_offset(capacity);
+        const stale_count = Math.min(words[L.STALE_COUNT], slot_capacity);
+
+        for (let i = 0; i < stale_count; i++) {
+            const slot = words[stale_offset + i];
+
+            if (slot >= slot_capacity || this.#slot_level[slot] === -1) {
+                continue;
+            }
+
+            // a page drawn in the frame the mover was seen, or later, already shows it
+            if (this.#slot_rendered[slot] >= reading_frame) {
+                continue;
+            }
+
+            if (this.#slot_stale[slot] === 0) {
+                this.#slot_stale[slot] = 1;
+                this.#slot_stale_since[slot] = reading_frame;
+                this.stats.stale_marked++;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Touch a slot, never moving its last touch back: a late reading must not age a page a later
+     * frame used.
+     *
+     * @param {number} slot
+     * @param {number} frame
+     */
+    #touch(slot, frame) {
+        const slots = this.slots;
+
+        if (slots.last_touch(slot) < frame) {
+            slots.touch(slot, frame);
+        }
+    }
+
+    /**
+     * The resident page standing in for a world page: its nearest resident ancestor whose level's
+     * window holds it, or -1.
+     *
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @returns {number} slot
+     */
+    #find_fallback(level, x, y) {
+        for (let up = level + 1; up < this.level_count; up++) {
+            const shift = up - level;
+            const slot = this.slot_of_page(up, x >> shift, y >> shift);
+
+            if (slot !== -1) {
+                return slot;
+            }
+        }
+
+        return -1;
+    }
+
+    /**
+     * Offer a cell to this frame's heap. A cell offered twice keeps the higher kind, the sum of the
+     * importance behind it, and the longer wait.
+     *
+     * @param {number} cell
+     * @param {number} kind
+     * @param {number} importance
+     * @param {number} waited frames
+     */
+    #offer(cell, kind, importance, waited) {
+        const heap = this.#heap;
+
+        if (this.#candidate_stamp[cell] === this.#stamp) {
+            if (kind > this.#candidate_kind[cell]) {
+                this.#candidate_kind[cell] = kind;
+            }
+
+            if (waited > this.#candidate_waited[cell]) {
+                this.#candidate_waited[cell] = waited;
+            }
+
+            const total = this.#candidate_importance[cell] + importance;
+
+            this.#candidate_importance[cell] = total;
+
+            heap.update(cell, candidate_score(this.#candidate_kind[cell], total, this.#candidate_waited[cell]));
+
+            return;
+        }
+
+        this.#candidate_stamp[cell] = this.#stamp;
+        this.#candidate_kind[cell] = kind;
+        this.#candidate_importance[cell] = importance;
+        this.#candidate_waited[cell] = waited;
+
+        heap.insert(cell, candidate_score(kind, importance, waited));
+    }
+
+    /**
+     * How long a missing cell has waited: since the first of an unbroken run of selects that each
+     * offered it. A page that stopped being wanted, or arrived, starts again from nothing.
+     *
+     * @param {number} cell
+     * @param {number} frame
+     * @returns {number} frames
+     */
+    #missing_wait(cell, frame) {
+        const last = this.#cell_wait_select[cell];
+        const now = this.#select_index;
+
+        if (last !== now && last !== now - 1) {
+            this.#cell_wait_since[cell] = frame;
+        }
+
+        this.#cell_wait_select[cell] = now;
+
+        return frame - this.#cell_wait_since[cell];
+    }
+
+    /**
+     * @param {number} slot
+     * @param {number} frame
+     * @returns {number} frames the slot has been stale
+     */
+    #stale_wait(slot, frame) {
+        return Math.max(0, frame - this.#slot_stale_since[slot]);
+    }
+
+    /**
+     * 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, budget) {
+        assert.isNonNegativeInteger(budget, 'budget');
+
+        const heap = this.#heap;
+
+        heap.clear();
+        this.#job_count = 0;
+
+        this.#select_index++;
+        this.#stamp = (this.#stamp + 1) >>> 0;
+
+        if (this.#stamp === 0) {
+            // the stamps wrapped: no cell may still look offered
+            this.#candidate_stamp.fill(0);
+            this.#stamp = 1;
+        }
+
+        let uncovered = 0;
+
+        const level_count = this.level_count;
+
+        for (let i = 0; i < this.#want_count; i++) {
+            const level = this.#want_level[i];
+            const x = this.#want_x[i];
+            const y = this.#want_y[i];
+            const importance = this.#want_importance[i];
+
+            if (!this.window_contains(level, x, y)) {
+                // scrolled out of its window since it was asked for
+                continue;
+            }
+
+            const cell = this.cell_of(level, x, y);
+            const slot = this.#cell_slot[cell];
+
+            if (slot !== -1) {
+                if (this.#slot_stale[slot] !== 0) {
+                    this.#offer(cell, KIND_UPDATE, importance, this.#stale_wait(slot, frame));
+                }
+
+                continue;
+            }
+
+            const waited = this.#missing_wait(cell, frame);
+            const fallback = this.#find_fallback(level, x, y);
+
+            if (fallback !== -1) {
+                this.#offer(cell, KIND_UPDATE, importance, waited);
+
+                if (this.#slot_stale[fallback] !== 0) {
+                    // what these pixels see meanwhile is stale too
+                    this.#offer(this.#cell_of_slot(fallback), KIND_UPDATE, importance, this.#stale_wait(fallback, frame));
+                }
+
+                continue;
+            }
+
+            uncovered++;
+
+            // the page itself, behind the cover: a budget with room for both fills it this frame
+            this.#offer(cell, KIND_UPDATE, importance, waited);
+
+            let cover = Math.min(level + VSM_COVER_LEVEL_STEP, level_count - 1);
+
+            while (cover < level_count && !this.window_contains(cover, x >> (cover - level), y >> (cover - level))) {
+                cover++;
+            }
+
+            if (cover < level_count) {
+                const shift = cover - level;
+
+                this.#offer(this.cell_of(cover, x >> shift, y >> shift), KIND_COVER, importance, 0);
+            }
+        }
+
+        this.stats.uncovered = uncovered;
+
+        const n = this.pages_per_level;
+        const cells_per_level = n * n;
+        const mask = n - 1;
+
+        let renders = 0;
+
+        // once no slot can be had, none can for the rest of the frame — nothing below frees one —
+        // so the pages after it wait without a search of the pool each
+        let pool_exhausted = false;
+        let refused = 0;
+
+        while (renders < budget && heap.size > 0) {
+            const cell = heap.pop_max();
+            const slot = this.#cell_slot[cell];
+
+            if (slot !== -1) {
+                if (this.#slot_stale[slot] !== 0) {
+                    this.#render(slot, frame);
+                    this.stats.re_rendered++;
+                    renders++;
+                }
+
+                continue;
+            }
+
+            const level = (cell / cells_per_level) | 0;
+            const local = cell - level * cells_per_level;
+            const cell_x = local & mask;
+            const cell_y = (local / n) | 0;
+
+            // the window's page in that cell
+            const origin_x = this.#origin_x[level];
+            const origin_y = this.#origin_y[level];
+            const x = origin_x + ((cell_x - origin_x) & mask);
+            const y = origin_y + ((cell_y - origin_y) & mask);
+
+            const claimed = pool_exhausted ? -1 : this.#claim_slot(frame, level);
+
+            if (claimed === -1) {
+                pool_exhausted = true;
+                refused++;
+                continue;
+            }
+
+            this.#install(claimed, level, x, y, cell);
+            this.#render(claimed, frame);
+            renders++;
+        }
+
+        this.stats.renders = renders;
+        this.stats.refused += refused;
+        this.stats.backlog = heap.size + refused;
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {number} the cell its page sits in
+     */
+    #cell_of_slot(slot) {
+        return this.cell_of(this.#slot_level[slot], this.#slot_x[slot], this.#slot_y[slot]);
+    }
+
+    /**
+     * A free slot, or the least recently touched page's outside the protection window; -1 when
+     * there is neither.
+     *
+     * @param {number} frame
+     * @param {number} level the page coming in
+     * @returns {number}
+     */
+    #claim_slot(frame, level) {
+        const slots = this.slots;
+
+        const free = slots.allocate(frame, false, level);
+
+        if (free !== -1) {
+            return free;
+        }
+
+        const victim = slots.find_eviction_candidate(frame, this.protect_frames);
+
+        if (victim === -1) {
+            return -1;
+        }
+
+        this.#evict(victim);
+        this.stats.evictions++;
+
+        return slots.allocate(frame, false, level);
+    }
+
+    /**
+     * @param {number} slot
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @param {number} cell
+     */
+    #install(slot, level, x, y, cell) {
+        this.#cell_slot[cell] = slot;
+
+        this.#slot_level[slot] = level;
+        this.#slot_x[slot] = x;
+        this.#slot_y[slot] = y;
+        this.#slot_stale[slot] = 0;
+
+        this.#mark_cell(cell);
+        this.#mark_slot(slot);
+
+        this.stats.installs++;
+    }
+
+    /**
+     * @param {number} slot
+     * @param {number} frame
+     */
+    #render(slot, frame) {
+        const i = this.#job_count++;
+
+        this.#job_slot[i] = slot;
+        this.#job_level[i] = this.#slot_level[slot];
+        this.#job_x[i] = this.#slot_x[slot];
+        this.#job_y[i] = this.#slot_y[slot];
+
+        this.#slot_stale[slot] = 0;
+        this.#slot_rendered[slot] = frame;
+    }
+
+    /**
+     * @param {number} slot
+     */
+    #evict(slot) {
+        const cell = this.#cell_of_slot(slot);
+
+        this.#cell_slot[cell] = -1;
+        this.#mark_cell(cell);
+
+        this.#slot_level[slot] = -1;
+        this.#slot_stale[slot] = 0;
+        this.#slot_rendered[slot] = -1;
+        this.#mark_slot(slot);
+
+        this.slots.free(slot);
+    }
+
+    /**
+     * @param {number} cell
+     */
+    #mark_cell(cell) {
+        if (this.#dirty_cell_mark[cell] === 0) {
+            this.#dirty_cell_mark[cell] = 1;
+            this.#dirty_cells[this.#dirty_cell_count++] = cell;
+        }
+    }
+
+    /**
+     * @param {number} slot
+     */
+    #mark_slot(slot) {
+        if (this.#dirty_slot_mark[slot] === 0) {
+            this.#dirty_slot_mark[slot] = 1;
+            this.#dirty_slots[this.#dirty_slot_count++] = slot;
+        }
+    }
+
+    /**
+     * 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) {
+        const slot = this.#cell_slot[cell];
+
+        if (slot === -1) {
+            return VT_ENTRY_INVALID;
+        }
+
+        const per_axis = this.slots.slots_per_axis;
+
+        return vt_entry_pack(slot % per_axis, (slot / per_axis) | 0, this.#slot_level[slot]);
+    }
+
+    /**
+     * @param {number} cell
+     * @returns {number} the slot holding the cell's page, or -1
+     */
+    cell_slot(cell) {
+        return this.#cell_slot[cell];
+    }
+
+    /**
+     * @returns {number} cells whose entry changed since {@link clear_dirty}
+     */
+    get dirty_cell_count() {
+        return this.#dirty_cell_count;
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    dirty_cell(i) {
+        return this.#dirty_cells[i];
+    }
+
+    /**
+     * @returns {number} slots whose page changed since {@link clear_dirty}
+     */
+    get dirty_slot_count() {
+        return this.#dirty_slot_count;
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    dirty_slot(i) {
+        return this.#dirty_slots[i];
+    }
+
+    /**
+     * @returns {boolean} whether a window moved since {@link clear_dirty}
+     */
+    get levels_dirty() {
+        return this.#levels_dirty;
+    }
+
+    /**
+     * Forget what changed: the rows have been written.
+     */
+    clear_dirty() {
+        for (let i = 0; i < this.#dirty_cell_count; i++) {
+            this.#dirty_cell_mark[this.#dirty_cells[i]] = 0;
+        }
+
+        for (let i = 0; i < this.#dirty_slot_count; i++) {
+            this.#dirty_slot_mark[this.#dirty_slots[i]] = 0;
+        }
+
+        this.#dirty_cell_count = 0;
+        this.#dirty_slot_count = 0;
+        this.#levels_dirty = false;
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {number} the level of the slot's page, or -1 when it is empty
+     */
+    slot_level(slot) {
+        return this.#slot_level[slot];
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {number}
+     */
+    slot_x(slot) {
+        return this.#slot_x[slot];
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {number}
+     */
+    slot_y(slot) {
+        return this.#slot_y[slot];
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {boolean} whether a mover crossed the slot's page after it was last rendered
+     */
+    slot_stale(slot) {
+        return this.#slot_stale[slot] !== 0;
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {number} the frame it was last rendered in, or -1
+     */
+    slot_rendered_frame(slot) {
+        return this.#slot_rendered[slot];
+    }
+
+    /**
+     * @returns {number} wants in the want set
+     */
+    get want_count() {
+        return this.#want_count;
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_level(i) {
+        return this.#want_level[i];
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_x(i) {
+        return this.#want_x[i];
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    want_y(i) {
+        return this.#want_y[i];
+    }
+
+    /**
+     * @returns {number} pages {@link select} chose to render
+     */
+    get job_count() {
+        return this.#job_count;
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_slot(i) {
+        return this.#job_slot[i];
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_level(i) {
+        return this.#job_level[i];
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_x(i) {
+        return this.#job_x[i];
+    }
+
+    /**
+     * @param {number} i
+     * @returns {number}
+     */
+    job_y(i) {
+        return this.#job_y[i];
+    }
+}