@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js

@@ -43,7 +43,7 @@ import { shader_mesh_cards_log } from "./cards/shader_mesh_cards_log.js";
 import { shader_mesh_cards_merge } from "./cards/shader_mesh_cards_merge.js";
 import { shader_mesh_cards_pages } from "./cards/shader_mesh_cards_pages.js";
 import { shader_mesh_cards_split } from "./cards/shader_mesh_cards_split.js";
-import { MESH_SDF_BRICK_TEXELS, MeshSDFState } from "./MESH_SDF.js";
+import { MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_VOXELS, MeshSDFState } from "./MESH_SDF.js";
 import { MESH_SDF_SAMPLER } from "./MESH_SDF_RESOURCES.js";
 import { MESH_SDF_STRUCT } from "./MESH_SDF_STRUCT.js";
 import { MeshSDFLayout } from "./MeshSDFLayout.js";
@@ -53,6 +53,16 @@ import { MeshSDFLayout } from "./MeshSDFLayout.js";
  * @typedef {import("../GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
  * @typedef {import("../GPUGeometryMetadata.js").GPUGeometryMetadata} GPUGeometryMetadata
  * @typedef {import("../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext} GPUResidentMaterialContext
+ * @typedef {import("../../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
+ */
+
+/**
+ * What makes caches for geometries the bake cannot bake from a tree of their own
+ * ({@link GPUGeometrySDFManager#add_source}): it learns what is asked for from `onRequested`, records its own work in
+ * each frame's graph ahead of the bake, and hands each cache in through `adopt`.
+ *
+ * @typedef {Object} MeshSDFSource
+ * @property {function(FrameGraph): void} graph_update records the source's work for the frame, ahead of the bake
  */
 
 /*
@@ -216,6 +226,12 @@ function grow_typed(array, length) {
  * {@link cards}, whose card sets — one per (geometry, material) pair — are captured after the bake,
  * `capture_budget` pages a frame.
  *
+ * **Sources** ({@link add_source}) make the caches of geometries with no tree of their own to bake from,
+ * a virtual geometry's: such a geometry waits queued, as one whose tree is not resident yet does. A
+ * source hears of each geometry queued ({@link onRequested}), records its own work each frame ahead of
+ * the bake, and bakes a proxy of it here as any geometry, whose resident cache it then gives the
+ * geometry ({@link adopt}).
+ *
  * **Readers** bind {@link headers}, {@link indirection}, {@link texture} and {@link MESH_SDF_SAMPLER}
  * (see {@link write_bindings}) and sample through `mesh_sdf_sample`, which only a resident header
  * should be given to.
@@ -240,6 +256,18 @@ export class GPUGeometrySDFManager {
      */
     onBaked = new Signal();
 
+    /**
+     * Sent with a geometry's record each time its cache is queued for a bake: what a source listens to.
+     * @type {Signal<GPUGeometryMetadata>}
+     */
+    onRequested = new Signal();
+
+    /**
+     * Run first in each {@link graph_bake}.
+     * @type {MeshSDFSource[]}
+     */
+    #sources = [];
+
     #voxel_size = 0.125;
     #max_bricks = 18;
 
@@ -265,6 +293,8 @@ export class GPUGeometrySDFManager {
     #card_pages = new Uint32Array(64);
     /** Words the placed layout keeps. */
     #card_words = new Uint32Array(64);
+    /** Texels a side of the layout's largest card: the grid's longest axis in voxels, plus one. */
+    #card_side = new Uint32Array(64);
 
     /**
      * The range each geometry's cards are being placed in.
@@ -522,8 +552,7 @@ export class GPUGeometrySDFManager {
             }
 
             if (this.#references[id] > 0 && state[id] === HOST_NONE) {
-                state[id] = HOST_QUEUED;
-                this.#queue.push(id);
+                this.#request(id);
             }
         }
 
@@ -569,8 +598,7 @@ export class GPUGeometrySDFManager {
         }
 
         if (++this.#references[id] === 1 && this.#state[id] === HOST_NONE) {
-            this.#state[id] = HOST_QUEUED;
-            this.#queue.push(id);
+            this.#request(id);
         }
 
         this.#holders_changed.push(id);
@@ -699,6 +727,103 @@ export class GPUGeometrySDFManager {
         }
     }
 
+    /**
+     * Whether a geometry's cache waits for its bake: queued, and not admitted. A cache whose last holder went is
+     * baked all the same until a {@link trim} drops it, as one admitted is.
+     *
+     * @param {GPUGeometryMetadata} record
+     * @returns {boolean}
+     */
+    is_requested(record) {
+        return this.#state[record.index] === HOST_QUEUED;
+    }
+
+    /**
+     * Whether a holder of a geometry's cache draws both sides of it: the side a bake of it takes.
+     *
+     * @param {GPUGeometryMetadata} record
+     * @returns {boolean}
+     */
+    holds_two_sided(record) {
+        return (this.#two_sided_references[record.index] ?? 0) > 0;
+    }
+
+    /**
+     * @param {MeshSDFSource} source run first in each {@link graph_bake} from here on
+     */
+    add_source(source) {
+        assert.defined(source, 'source');
+        assert.equal(this.#sources.includes(source), false, 'source added already');
+
+        this.#sources.push(source);
+    }
+
+    /**
+     * @param {MeshSDFSource} source
+     */
+    remove_source(source) {
+        const index = this.#sources.indexOf(source);
+
+        if (index !== -1) {
+            this.#sources.splice(index, 1);
+        }
+    }
+
+    /**
+     * Give `target` the resident cache baked for `proxy`: a source's hand-in, for a geometry with no tree of its own,
+     * of a proxy in the same local space baked as any geometry is. Nothing is copied. The target's header takes the
+     * proxy's layout, entries and side, and the proxy's reads None, as dropped; {@link onBaked} is sent with the
+     * target. The cache has no cards, the target having no tree to capture them with. Held for another side than the
+     * proxy was baked for, it is queued again at the next bake, as any cache is.
+     *
+     * @param {GPUGeometryMetadata} target waiting for its bake ({@link is_requested})
+     * @param {GPUGeometryMetadata} proxy whose cache is resident
+     * @returns {boolean} whether it was adopted: false, changing nothing, when `target` no longer waits or `proxy`'s
+     *   cache is not resident
+     */
+    adopt(target, proxy) {
+        assert.defined(target, 'target');
+        assert.defined(proxy, 'proxy');
+        assert.notEqual(target.index, proxy.index, 'a geometry cannot adopt its own cache');
+
+        const id = target.index;
+        const from = proxy.index;
+
+        if (!this.is_requested(target) || this.#state[from] !== HOST_RESIDENT) {
+            return false;
+        }
+
+        this.#drop_cards(from);
+
+        const range = this.#ranges[from];
+
+        this.#ranges[id] = range;
+        this.#ranges[from] = null;
+        this.#brick_count[id] = this.#brick_count[from];
+        this.#two_sided[id] = this.#two_sided[from];
+        this.#generation[id]++;
+
+        this.#state[from] = HOST_NONE;
+        this.#state[id] = HOST_RESIDENT;
+
+        // the layout the proxy was admitted with: a configure since would have dropped its cache
+        const layout = this.#layout;
+
+        layout.compute(proxy.geometry.bounding_box, this.#voxel_size, this.#max_bricks);
+
+        this.#write_header(id, layout, range.offset + 1, MeshSDFState.Resident);
+
+        this.#word_scratch[0] = MeshSDFState.None;
+        this.#device.queue.writeBuffer(this.#headers, from * HEADER_BYTES + HEADER_STATE, this.#word_scratch, 0, 1);
+
+        // the side its holders draw is checked at the next bake
+        this.#holders_changed.push(id);
+
+        this.onBaked.send1(id);
+
+        return true;
+    }
+
     /**
      * Geometries whose layout was coarsened by the cap, of those baked: coarser than asked.
      * @returns {number}
@@ -857,8 +982,10 @@ export class GPUGeometrySDFManager {
      *        captures nothing
      * @param {GPUResidentMaterialContext|null} [options.materials] what the capture shades with, as it
      *        stands this frame; needed with a `capture_budget`
+     * @param {GPUMaterialManager|null} [options.material_contexts] what a raster capture draws with
+     *        ({@link GPUMeshCardSets#capture_mode}); needed with a `capture_budget` in that mode
      */
-    graph_bake({ graph, budget, capture_budget = 0, materials = null }) {
+    graph_bake({ graph, budget, capture_budget = 0, materials = null, material_contexts = null }) {
         assert.defined(graph, 'graph');
         assert.isPositiveInteger(budget, 'budget');
         assert.lessThanOrEqual(budget, MESH_SDF_BAKE_BUDGET_MAX, 'budget');
@@ -867,6 +994,13 @@ export class GPUGeometrySDFManager {
 
         this.#frame++;
 
+        // the sources first: a cache adopted here is not admitted to a bake of its own below
+        const sources = this.#sources;
+
+        for (let i = 0; i < sources.length; i++) {
+            sources[i].graph_update(graph);
+        }
+
         this.#follow_sides();
 
         // the last bake's commands were submitted before this call: what they read may be handed out
@@ -880,12 +1014,12 @@ export class GPUGeometrySDFManager {
 
         const queued_bound = this.#read_queued + (this.#admitted_total - this.#read_admitted);
 
-        const has_work = this.#queue.length > 0
+        const has_work = this.#admittable()
             || queued_bound > 0
             || this.#freed.length > 0
             || this.#pushes.length > 0
             || this.#fill_pending
-            || this.#place_queue.length > 0
+            || this.#placeable()
             || this.#compact_queue.length > 0;
 
         let arena = -1;
@@ -916,7 +1050,15 @@ export class GPUGeometrySDFManager {
             blas.meshlet_metadata = geometries.meshlets.buffer_metadata;
             blas.meshlet_data = geometries.meshlets.buffer_data;
 
-            this.#cards.graph_capture({ graph, budget: capture_budget, arena, headers: this.#headers, materials, blas });
+            this.#cards.graph_capture({
+                graph,
+                budget: capture_budget,
+                arena,
+                headers: this.#headers,
+                materials,
+                material_contexts,
+                blas,
+            });
         }
     }
 
@@ -1008,9 +1150,7 @@ export class GPUGeometrySDFManager {
             }
 
             this.#drop(id);
-
-            this.#state[id] = HOST_QUEUED;
-            this.#queue.push(id);
+            this.#request(id);
         }
 
         changed.length = 0;
@@ -1084,12 +1224,69 @@ export class GPUGeometrySDFManager {
             this.#card_state[id] = CARDS_PLACED;
             this.#write_header_cards(id, target.offset);
 
-            this.#cards.set_layout(id, this.#card_pages[id]);
+            this.#cards.set_layout(id, this.#card_pages[id], this.#card_side[id]);
         }
 
         queue.length = 0;
     }
 
+    /**
+     * Whether a queued geometry's tree is traceable, so that a bake could admit it. A geometry that
+     * waits for its tree, or for a source's cache, records no bake while it waits. Drops from the queue
+     * what was dropped, or adopted, since it was queued.
+     *
+     * @returns {boolean}
+     */
+    #admittable() {
+        const queue = this.#queue;
+        const blas = this.#geometries.blas;
+
+        let kept = 0;
+        let admittable = false;
+
+        for (let i = 0; i < queue.length; i++) {
+            const id = queue[i];
+
+            if (this.#state[id] !== HOST_QUEUED) {
+                continue;
+            }
+
+            queue[kept++] = id;
+
+            if (!admittable && blas.get_address(this.#records[id]) !== undefined) {
+                admittable = true;
+            }
+        }
+
+        queue.length = kept;
+
+        return admittable;
+    }
+
+    /**
+     * Whether a resident geometry's cards wait for placement. Drops from the queue what was dropped, or
+     * adopted away, since it was queued.
+     *
+     * @returns {boolean}
+     */
+    #placeable() {
+        const queue = this.#place_queue;
+
+        let kept = 0;
+
+        for (let i = 0; i < queue.length; i++) {
+            const id = queue[i];
+
+            if (this.#state[id] === HOST_RESIDENT && this.#card_state[id] === CARDS_QUEUED) {
+                queue[kept++] = id;
+            }
+        }
+
+        queue.length = kept;
+
+        return kept > 0;
+    }
+
     /**
      * Admit queued geometries in request order: those whose tree is resident, while every brick they
      * could queue fits on the ring beside what may be on it already.
@@ -1153,7 +1350,7 @@ export class GPUGeometrySDFManager {
                 this.#coarsened_count++;
             }
 
-            this.#write_header_baking(id, layout, range.offset + 1);
+            this.#write_header(id, layout, range.offset + 1, MeshSDFState.Baking);
 
             // level 0's grid, which the cards are placed over
             const grid = layout.bricks;
@@ -1162,6 +1359,7 @@ export class GPUGeometrySDFManager {
             this.#placement_words[id] = placement.words;
             this.#placement_scratch[id] = placement.histograms;
             this.#placement_columns[id] = 2 * (grid[0] * grid[1] + grid[1] * grid[2] + grid[0] * grid[2]);
+            this.#card_side[id] = Math.max(grid[0], grid[1], grid[2]) * MESH_SDF_BRICK_VOXELS + 1;
 
             this.#word_scratch[0] = count;
             this.#device.queue.writeBuffer(this.#indirection, range.offset * 4, this.#word_scratch, 0, 1);
@@ -1605,12 +1803,25 @@ export class GPUGeometrySDFManager {
         }
     }
 
+    /**
+     * Queue a held geometry's bake, and say so.
+     *
+     * @param {number} id
+     */
+    #request(id) {
+        this.#state[id] = HOST_QUEUED;
+        this.#queue.push(id);
+
+        this.onRequested.send1(this.#records[id]);
+    }
+
     /**
      * @param {number} id
      * @param {MeshSDFLayout} layout
      * @param {number} indirection
+     * @param {MeshSDFState} state
      */
-    #write_header_baking(id, layout, indirection) {
+    #write_header(id, layout, indirection, state) {
         const view = this.#header_scratch;
 
         for (let axis = 0; axis < 3; axis++) {
@@ -1622,7 +1833,7 @@ export class GPUGeometrySDFManager {
         view.setUint32(HEADER_LEVEL_COUNT, layout.level_count, true);
         view.setUint32(HEADER_INDIRECTION, indirection, true);
         view.setUint32(HEADER_CARDS, GPU_DATABASE_NULL, true);
-        view.setUint32(HEADER_STATE, MeshSDFState.Baking, true);
+        view.setUint32(HEADER_STATE, state, true);
         view.setUint32(HEADER_SOURCE, GPU_DATABASE_NULL, true);
         view.setUint32(HEADER_GENERATION, this.#generation[id], true);
         view.setUint32(HEADER_TWO_SIDED, this.#two_sided[id], true);
@@ -1665,6 +1876,7 @@ export class GPUGeometrySDFManager {
         this.#placement_columns = grow_typed(this.#placement_columns, length);
         this.#card_pages = grow_typed(this.#card_pages, length);
         this.#card_words = grow_typed(this.#card_words, length);
+        this.#card_side = grow_typed(this.#card_side, length);
     }
 
     #ensure_device() {

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts

@@ -33,6 +33,10 @@ export const MESH_CARD_CAPTURE_BUDGET_MAX: number;
  * the order they were asked for, then recaptures in the order queued. A card set's pages may span
  * frames. {@link recapture} queues a resident card set again, which reads its last capture until the
  * new one is done; a card set whose capture is under way starts it again.
+ *
+ * **Modes** ({@link capture_mode}). A traced card set is a run of pages, a thread a texel. A
+ * rastered one is taken whole: its cards are drawn into a region of a scratch, a cell a card, and its
+ * pages scattered from there into the atlas; the frame's last one may take the budget past its end.
  */
 export class GPUMeshCardSets {
     /**
@@ -79,6 +83,17 @@ export class GPUMeshCardSets {
      * @returns {number}
      */
     get pages_queued(): number;
+    /**
+     * A change captures every card set again in the new mode: resident ones read their last capture
+     * until it is done, and captures under way start again.
+     *
+     * @param {MeshCardCaptureMode} mode
+     */
+    set capture_mode(mode: number);
+    /**
+     * @returns {MeshCardCaptureMode}
+     */
+    get capture_mode(): number;
     /**
      * Whether readers may use the card set: captured at least once, and its layout still there.
      *
@@ -127,8 +142,10 @@ export class GPUMeshCardSets {
      *
      * @param {number} geometry
      * @param {number} pages
+     * @param {number} side texels a side of the layout's largest card: its grid's longest axis in
+     *        voxels, plus one, the lattice having a point at either end
      */
-    set_layout(geometry: number, pages: number): void;
+    set_layout(geometry: number, pages: number, side: number): void;
     /**
      * A geometry's layout is gone: its card sets wait for the next.
      *
@@ -145,15 +162,19 @@ export class GPUMeshCardSets {
      * @param {number} options.budget pages captured at most, `card_capture_budget`
      * @param {number} options.arena graph handle of the arena, as the frame's bake left it
      * @param {GPUBuffer} options.headers
-     * @param {GPUResidentMaterialContext} options.materials
-     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with
+     * @param {GPUMaterialManager} options.material_contexts what the raster draws with: each
+     *        material's template and bind group
+     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads, whose
+     *        geometry and meshlet buffers the raster pulls vertices from
      */
-    graph_capture({ graph, budget, arena, headers, materials, blas }: {
+    graph_capture({ graph, budget, arena, headers, materials, material_contexts, blas }: {
         graph: FrameGraph;
         budget: number;
         arena: number;
         headers: GPUBuffer;
         materials: GPUResidentMaterialContext;
+        material_contexts: GPUMaterialManager;
         blas: any;
     }): void;
     /**
@@ -166,6 +187,8 @@ export class GPUMeshCardSets {
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 export type ShadeMaterial = import("../../../material/ShadeMaterial.js").ShadeMaterial;
 export type GPUResidentMaterialContext = import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext;
+export type GPUMaterialManager = import("../../../material/GPUMaterialManager.js").GPUMaterialManager;
+export type GPUMaterialContext = import("../../../material/GPUMaterialContext.js").GPUMaterialContext;
 export type Allocation = import("../../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
 import { GPUTileAtlas2D } from "../../../texture/atlas/GPUTileAtlas2D.js";
 //# sourceMappingURL=GPUMeshCardSets.d.ts.map

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AA0CA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AArBD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA2CnG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAoGI;;OAEG;IACH,+BAIC;IApGD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IA4F3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CA+BlB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,SACN,MAAM,QAkBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA6BhB;IAoMD;;;;;;;;;;;;OAYG;IACH;QAP+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QACV,IAAI;aA6C9B;IA6HD;;OAEG;IACH,+BAgBC;IAED,gBAQC;;CACJ;yBAp2BY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;yBAC7F,OAAO,yDAAyD,EAAE,UAAU;+BAV1D,0CAA0C"}
+{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AAyEA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AApCD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA0DnG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAmLI;;OAEG;IACH,+BAIC;IAnLD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IA2K3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IASD;;;;;OAKG;IACH,+BAgBC;IA7BD;;OAEG;IACH,2BAEC;IA0BD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CA+BlB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,SACN,MAAM,QACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA+BhB;IAuSD;;;;;;;;;;;;;;;OAeG;IACH;QAV+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QACE,iBAAiB,EAA7C,kBAAkB;QAEF,IAAI;aAiG9B;IAiTD;;OAEG;IACH,+BAuBC;IAED,gBAoBC;;CACJ;yBA70CY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;iCAC7F,OAAO,yCAAyC,EAAE,kBAAkB;iCACpE,OAAO,yCAAyC,EAAE,kBAAkB;yBACpE,OAAO,yDAAyD,EAAE,UAAU;+BAxB1D,0CAA0C"}