@woosh/meep-engine 3.39.0 → 3.40.0

package/src/shade/renderer/texture/virtual/VTPhysicalCache.d.ts

@@ -13,11 +13,10 @@
  * no mip chain — virtual mip selection happens in the page table, physical
  * sampling is always level 0.
  *
- * Eviction metadata (last-touch frame, lock flag) lives here as flat
- * parallel arrays; the pick is a linear scan, which at the typical slot
- * count (≤ ~1k) is cheaper than maintaining a heap.
+ * The slot bookkeeping — allocation, touches, locks, the eviction pick — is
+ * {@link VTPhysicalSlots}'; this adds the textures the slots address.
  */
-export class VTPhysicalCache {
+export class VTPhysicalCache extends VTPhysicalSlots {
     /**
      *
      * @param {GPUDevice} device
@@ -40,42 +39,6 @@ export class VTPhysicalCache {
             premultiplied?: boolean;
         }[];
     });
-    /**
-     * Payload texels per page side, without border.
-     * @type {number}
-     * @readonly
-     */
-    readonly page_size: number;
-    /**
-     * Border texels on each side of the payload.
-     * @type {number}
-     * @readonly
-     */
-    readonly border: number;
-    /**
-     * page_size + 2*border.
-     * @type {number}
-     * @readonly
-     */
-    readonly slot_size: number;
-    /**
-     * Atlas side length in texels.
-     * @type {number}
-     * @readonly
-     */
-    readonly atlas_size: number;
-    /**
-     * Slots along one atlas axis.
-     * @type {number}
-     * @readonly
-     */
-    readonly slots_per_axis: number;
-    /**
-     * Total slot count.
-     * @type {number}
-     * @readonly
-     */
-    readonly capacity: number;
     /**
      * @typedef {Object} VTCacheLayer
      * @property {string} name
@@ -106,55 +69,6 @@ export class VTPhysicalCache {
      * @readonly
      */
     readonly views: GPUTextureView[];
-    /**
-     * Number of allocated slots.
-     * @returns {number}
-     */
-    get used(): number;
-    /**
-     *
-     * @param {number} slot
-     * @returns {{x: number, y: number}} slot grid coordinates
-     */
-    slot_coords(slot: number): {
-        x: number;
-        y: number;
-    };
-    /**
-     *
-     * @param {number} current_frame
-     * @param {boolean} [locked]
-     * @param {number} [mip] virtual mip of the incoming page
-     * @returns {number} slot index, or -1 when full
-     */
-    allocate(current_frame: number, locked?: boolean, mip?: number): number;
-    /**
-     *
-     * @param {number} slot
-     */
-    free(slot: number): void;
-    /**
-     *
-     * @param {number} slot
-     * @param {number} frame
-     */
-    touch(slot: number, frame: number): void;
-    /**
-     *
-     * @param {number} slot
-     * @returns {number}
-     */
-    last_touch(slot: number): number;
-    /**
-     * Pick the least-recently-touched evictable slot.
-     *
-     * @param {number} current_frame
-     * @param {number} protect_window slots touched within this many frames
-     *      are not eligible — feedback readback runs a couple of frames
-     *      behind, so "recently touched" really means "probably on screen"
-     * @returns {number} slot index, or -1 when nothing is evictable
-     */
-    find_eviction_candidate(current_frame: number, protect_window: number): number;
     /**
      * Upload one layer of a page into a slot.
      *
@@ -173,6 +87,6 @@ export class VTPhysicalCache {
         bytes_per_row?: number;
     }): void;
     destroy(): void;
-    #private;
 }
+import { VTPhysicalSlots } from "./VTPhysicalSlots.js";
 //# sourceMappingURL=VTPhysicalCache.d.ts.map

package/src/shade/renderer/texture/virtual/VTPhysicalCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VTPhysicalCache.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/VTPhysicalCache.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAuGI;;;;;;;;OAQG;IACH;qBALW,MAAM;oBACN,MAAM;iBACN,MAAM;;kBA/DH,MAAM;;;;;4BAEN,OAAO;;OAgHpB;IA9JD;;;;OAIG;IACH,oBAHU,MAAM,CAGN;IAEV;;;;OAIG;IACH,iBAHU,MAAM,CAGT;IAEP;;;;OAIG;IACH,oBAHU,MAAM,CAGN;IAEV;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,yBAHU,MAAM,CAGD;IAEf;;;;OAIG;IACH,mBAHU,MAAM,CAGP;IAET;;;;;OAKG;IAEH;;;OAGG;IACH;cATc,MAAM;;;;;wBAEN,OAAO;QAOd;IAEP;;;OAGG;IACH,mBAHU,YAAY,CAGR;IAEd;;;;;OAKG;IACH,gBAHU,gBAAgB,CAGf;IA6FX;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAOlC;IAED;;;;;;OAMG;IACH,wBALW,MAAM,WACN,OAAO,QACP,MAAM,GACJ,MAAM,CAelB;IAED;;;OAGG;IACH,WAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,YAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,kBACN,MAAM,GAGJ,MAAM,CA4BlB;IAED;;;;;;;;;;;;OAYG;IACH,8BAJW,MAAM,eACN,MAAM,WACN,WAAW,GAAC,eAAe,GAAC,iBAAiB,GAAC,SAAS,GAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAC,QAqC5G;IAED,gBAIC;;CACJ"}
+{"version":3,"file":"VTPhysicalCache.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/VTPhysicalCache.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH;IA6BI;;;;;;;;OAQG;IACH;qBALW,MAAM;oBACN,MAAM;iBACN,MAAM;;kBA/BH,MAAM;;;;;4BAEN,OAAO;;OA4DpB;IAhED;;;;;OAKG;IAEH;;;OAGG;IACH;cATc,MAAM;;;;;wBAEN,OAAO;QAOd;IAEP;;;OAGG;IACH,mBAHU,YAAY,CAGR;IAEd;;;;;OAKG;IACH,gBAHU,gBAAgB,CAGf;IAyCX;;;;;;;;;;;;OAYG;IACH,8BAJW,MAAM,eACN,MAAM,WACN,WAAW,GAAC,eAAe,GAAC,iBAAiB,GAAC,SAAS,GAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAC,QAqC5G;IAED,gBAIC;CACJ;gCA/I+B,sBAAsB"}

package/src/shade/renderer/texture/virtual/VTPhysicalCache.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { VTPhysicalSlots } from "./VTPhysicalSlots.js";
 
 /**
  * Physical page cache: one atlas texture per layer, all layers sharing a
@@ -15,53 +16,10 @@ import { assert } from "../../../../core/assert.js";
  * no mip chain — virtual mip selection happens in the page table, physical
  * sampling is always level 0.
  *
- * Eviction metadata (last-touch frame, lock flag) lives here as flat
- * parallel arrays; the pick is a linear scan, which at the typical slot
- * count (≤ ~1k) is cheaper than maintaining a heap.
+ * The slot bookkeeping — allocation, touches, locks, the eviction pick — is
+ * {@link VTPhysicalSlots}'; this adds the textures the slots address.
  */
-export class VTPhysicalCache {
-
-    /**
-     * Payload texels per page side, without border.
-     * @type {number}
-     * @readonly
-     */
-    page_size;
-
-    /**
-     * Border texels on each side of the payload.
-     * @type {number}
-     * @readonly
-     */
-    border;
-
-    /**
-     * page_size + 2*border.
-     * @type {number}
-     * @readonly
-     */
-    slot_size;
-
-    /**
-     * Atlas side length in texels.
-     * @type {number}
-     * @readonly
-     */
-    atlas_size;
-
-    /**
-     * Slots along one atlas axis.
-     * @type {number}
-     * @readonly
-     */
-    slots_per_axis;
-
-    /**
-     * Total slot count.
-     * @type {number}
-     * @readonly
-     */
-    capacity;
+export class VTPhysicalCache extends VTPhysicalSlots {
 
     /**
      * @typedef {Object} VTCacheLayer
@@ -90,38 +48,6 @@ export class VTPhysicalCache {
      */
     views = [];
 
-    /**
-     * Free slot indices, used as a stack.
-     * @type {number[]}
-     */
-    #free = [];
-
-    /**
-     * Per-slot: frame index of the last feedback touch.
-     * @type {Uint32Array}
-     */
-    #last_touch;
-
-    /**
-     * Per-slot: 1 when the slot must never be evicted (stack root pages).
-     * @type {Uint8Array}
-     */
-    #locked;
-
-    /**
-     * Per-slot: 1 when the slot is allocated.
-     * @type {Uint8Array}
-     */
-    #occupied;
-
-    /**
-     * Per-slot: virtual mip of the resident page — eviction tie-break only
-     * (prefer shedding fine pages, shrinking the resident quadtree from the
-     * leaves).
-     * @type {Uint8Array}
-     */
-    #mip;
-
     /**
      *
      * @param {GPUDevice} device
@@ -138,21 +64,10 @@ export class VTPhysicalCache {
         layers,
     }) {
         assert.defined(device, 'device');
-        assert.isNonNegativeInteger(atlas_size, 'atlas_size');
-        assert.isNonNegativeInteger(page_size, 'page_size');
-        assert.isNonNegativeInteger(border, 'border');
         assert.isArray(layers, 'layers');
         assert.greaterThan(layers.length, 0, 'layers.length');
 
-        this.page_size = page_size;
-        this.border = border;
-        this.slot_size = page_size + border * 2;
-        this.atlas_size = atlas_size;
-
-        this.slots_per_axis = Math.floor(atlas_size / this.slot_size);
-        this.capacity = this.slots_per_axis * this.slots_per_axis;
-
-        assert.greaterThan(this.capacity, 0, 'cache capacity');
+        super({ atlas_size, page_size, border });
 
         this.layers = layers;
 
@@ -170,125 +85,6 @@ export class VTPhysicalCache {
             this.textures.push(texture);
             this.views.push(texture.createView());
         }
-
-        this.#last_touch = new Uint32Array(this.capacity);
-        this.#locked = new Uint8Array(this.capacity);
-        this.#occupied = new Uint8Array(this.capacity);
-        this.#mip = new Uint8Array(this.capacity);
-
-        for (let i = this.capacity - 1; i >= 0; i--) {
-            this.#free.push(i);
-        }
-    }
-
-    /**
-     * Number of allocated slots.
-     * @returns {number}
-     */
-    get used() {
-        return this.capacity - this.#free.length;
-    }
-
-    /**
-     *
-     * @param {number} slot
-     * @returns {{x: number, y: number}} slot grid coordinates
-     */
-    slot_coords(slot) {
-        return {
-            x: slot % this.slots_per_axis,
-            y: (slot / this.slots_per_axis) | 0,
-        };
-    }
-
-    /**
-     *
-     * @param {number} current_frame
-     * @param {boolean} [locked]
-     * @param {number} [mip] virtual mip of the incoming page
-     * @returns {number} slot index, or -1 when full
-     */
-    allocate(current_frame, locked = false, mip = 0) {
-        if (this.#free.length === 0) {
-            return -1;
-        }
-
-        const slot = this.#free.pop();
-
-        this.#occupied[slot] = 1;
-        this.#locked[slot] = locked ? 1 : 0;
-        this.#last_touch[slot] = current_frame;
-        this.#mip[slot] = mip;
-
-        return slot;
-    }
-
-    /**
-     *
-     * @param {number} slot
-     */
-    free(slot) {
-        assert.equal(this.#occupied[slot], 1, `slot ${slot} is not allocated`);
-
-        this.#occupied[slot] = 0;
-        this.#locked[slot] = 0;
-
-        this.#free.push(slot);
-    }
-
-    /**
-     *
-     * @param {number} slot
-     * @param {number} frame
-     */
-    touch(slot, frame) {
-        this.#last_touch[slot] = frame;
-    }
-
-    /**
-     *
-     * @param {number} slot
-     * @returns {number}
-     */
-    last_touch(slot) {
-        return this.#last_touch[slot];
-    }
-
-    /**
-     * Pick the least-recently-touched evictable slot.
-     *
-     * @param {number} current_frame
-     * @param {number} protect_window slots touched within this many frames
-     *      are not eligible — feedback readback runs a couple of frames
-     *      behind, so "recently touched" really means "probably on screen"
-     * @returns {number} slot index, or -1 when nothing is evictable
-     */
-    find_eviction_candidate(current_frame, protect_window) {
-        let best = -1;
-        let best_touch = 0xFFFFFFFF;
-        let best_mip = 0xFF;
-
-        for (let slot = 0; slot < this.capacity; slot++) {
-            if (this.#occupied[slot] === 0 || this.#locked[slot] === 1) {
-                continue;
-            }
-
-            const touch = this.#last_touch[slot];
-
-            if (current_frame - touch < protect_window) {
-                continue;
-            }
-
-            const mip = this.#mip[slot];
-
-            if (touch < best_touch || (touch === best_touch && mip < best_mip)) {
-                best_touch = touch;
-                best_mip = mip;
-                best = slot;
-            }
-        }
-
-        return best;
     }
 
     /**
@@ -305,7 +101,7 @@ export class VTPhysicalCache {
      * @param {ImageBitmap|OffscreenCanvas|HTMLCanvasElement|ImageData|{data: Uint8Array, bytes_per_row?: number}} payload
      */
     upload(queue, slot, layer_index, payload) {
-        assert.equal(this.#occupied[slot], 1, `slot ${slot} is not allocated`);
+        assert.equal(this.is_occupied(slot), true, `slot ${slot} is not allocated`);
 
         const layer = this.layers[layer_index];
         const { x, y } = this.slot_coords(slot);

package/src/shade/renderer/texture/virtual/VTPhysicalSlots.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The slot bookkeeping of a physical page cache — a square grid of `page_size + 2*border` slots
+ * over an atlas — with no texture behind it: which slots are taken, when each was last touched,
+ * which may never be evicted, and the mip each holds.
+ *
+ * {@link VTPhysicalCache} adds the layer textures and uploads on top of this. A cache whose pages
+ * are drawn rather than uploaded — the virtual shadow map's pool is a region of the shadow atlas —
+ * uses it on its own.
+ *
+ * Eviction metadata lives here as flat parallel arrays; the pick is a linear scan, which at the
+ * typical slot count (≤ ~1k) is cheaper than maintaining a heap.
+ */
+export class VTPhysicalSlots {
+    /**
+     *
+     * @param {Object} options
+     * @param {number} [options.atlas_size]
+     * @param {number} [options.page_size]
+     * @param {number} [options.border]
+     */
+    constructor({ atlas_size, page_size, border, }: {
+        atlas_size?: number;
+        page_size?: number;
+        border?: number;
+    });
+    /**
+     * Payload texels per page side, without border.
+     * @type {number}
+     * @readonly
+     */
+    readonly page_size: number;
+    /**
+     * Border texels on each side of the payload.
+     * @type {number}
+     * @readonly
+     */
+    readonly border: number;
+    /**
+     * page_size + 2*border.
+     * @type {number}
+     * @readonly
+     */
+    readonly slot_size: number;
+    /**
+     * Atlas side length in texels.
+     * @type {number}
+     * @readonly
+     */
+    readonly atlas_size: number;
+    /**
+     * Slots along one atlas axis.
+     * @type {number}
+     * @readonly
+     */
+    readonly slots_per_axis: number;
+    /**
+     * Total slot count.
+     * @type {number}
+     * @readonly
+     */
+    readonly capacity: number;
+    /**
+     * Number of allocated slots.
+     * @returns {number}
+     */
+    get used(): number;
+    /**
+     *
+     * @param {number} slot
+     * @returns {{x: number, y: number}} slot grid coordinates
+     */
+    slot_coords(slot: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     *
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_occupied(slot: number): boolean;
+    /**
+     *
+     * @param {number} current_frame
+     * @param {boolean} [locked]
+     * @param {number} [mip] virtual mip of the incoming page
+     * @returns {number} slot index, or -1 when full
+     */
+    allocate(current_frame: number, locked?: boolean, mip?: number): number;
+    /**
+     *
+     * @param {number} slot
+     */
+    free(slot: number): void;
+    /**
+     *
+     * @param {number} slot
+     * @param {number} frame
+     */
+    touch(slot: number, frame: number): void;
+    /**
+     *
+     * @param {number} slot
+     * @returns {number}
+     */
+    last_touch(slot: number): number;
+    /**
+     * Pick the least-recently-touched evictable slot.
+     *
+     * @param {number} current_frame
+     * @param {number} protect_window slots touched within this many frames
+     *      are not eligible — feedback readback runs a couple of frames
+     *      behind, so "recently touched" really means "probably on screen"
+     * @returns {number} slot index, or -1 when nothing is evictable
+     */
+    find_eviction_candidate(current_frame: number, protect_window: number): number;
+    #private;
+}
+//# sourceMappingURL=VTPhysicalSlots.d.ts.map

package/src/shade/renderer/texture/virtual/VTPhysicalSlots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VTPhysicalSlots.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/VTPhysicalSlots.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH;IA4EI;;;;;;OAMG;IACH;QAJ4B,UAAU,GAA3B,MAAM;QACW,SAAS,GAA1B,MAAM;QACW,MAAM,GAAvB,MAAM;OA6BhB;IA5GD;;;;OAIG;IACH,oBAHU,MAAM,CAGN;IAEV;;;;OAIG;IACH,iBAHU,MAAM,CAGT;IAEP;;;;OAIG;IACH,oBAHU,MAAM,CAGN;IAEV;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,yBAHU,MAAM,CAGD;IAEf;;;;OAIG;IACH,mBAHU,MAAM,CAGP;IAsET;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAOlC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,wBALW,MAAM,WACN,OAAO,QACP,MAAM,GACJ,MAAM,CAelB;IAED;;;OAGG;IACH,WAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,YAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,kBACN,MAAM,GAGJ,MAAM,CA4BlB;;CACJ"}