@woosh/meep-engine 3.61.2 → 3.61.3

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts

@@ -14,8 +14,8 @@ export const MESH_SDF_BAKE_BUDGET_MAX: number;
  * queues a bake; the last one going leaves the cache in place until {@link trim}, which only a user of
  * the caches calls, so a cache outlives a mode that stops using it and is there when the mode comes
  * back (D28). {@link forget} drops a geometry the geometry manager has let go of, whatever holds it.
- * {@link alias} points a geometry's id at another's cache, which readers follow, and whose holders and card sets
- * the aliased geometry's become: a skinned clone's at its source's, a virtual geometry's at its proxy's.
+ * {@link alias} points a geometry's id at another's cache, which readers follow, and whose holders and surface
+ * caches the aliased geometry's become: a skinned clone's at its source's, a virtual geometry's at its proxy's.
  *
  * **Side.** A holder says whether it draws both sides of the geometry. A field is baked two-sided
  * while any of its holders does: its vote then counts no back face, so nothing is inside it.
@@ -25,21 +25,29 @@ export const MESH_SDF_BAKE_BUDGET_MAX: number;
  *
  * **The bake** ({@link graph_bake}, once a frame) admits queued geometries in request order whose
  * trees are resident, while the ring has room for every brick they could queue, and runs free,
- * classify, take, evaluate and store (`bake/`). At most `budget` bricks are evaluated a frame. The
- * device logs each geometry it completes; the log is read back, and the host turns the header
- * resident and sends {@link onBaked}. A take held back by the free slots is logged too, and the atlas
- * and its slot stack double.
+ * classify, take, evaluate, key, resolve and store (`bake/`). At most `budget` bricks are evaluated a
+ * frame. The device logs each geometry it completes; the log is read back, and the host turns the
+ * header resident and sends {@link onBaked}. A take held back by the free slots is logged too, and the
+ * atlas and its slot stack double.
  *
- * **Cards** (§6.5): a geometry turned resident has its cards placed by the next bake that has room
- * (`cards/`), in a range sized for any layout of its grid. The placement is logged with the columns
- * and pages it took; on that readback the geometry gets a range of exactly that size, and the next bake
- * moves the layout into it and gives the placement's range back. The layout then reaches
- * {@link cards}, whose card sets — one per (geometry, material) pair — are captured after the bake,
- * `capture_budget` pages a frame.
+ * **Shared bricks.** Bricks of the same bytes, of one geometry or of many, share one slot: a slot
+ * counts the entries holding it and is given back with the last. A content table lists slots by the
+ * content keys of their bytes (`chunk_mesh_sdf_contents`, `MESH_SDF_BRICK_KEY.js`), and a brick takes
+ * a slot it finds there only once their bytes compare equal: a key that two bytes share costs a share,
+ * never a brick its bytes.
+ *
+ * **Bundles.** {@link export_bundle} reads resident fields and surface caches out as a
+ * `ModelCacheBundle`, each brick once; {@link upload_bundle} takes one back as the fields of geometries
+ * that have none, its bricks placed by the next bake, with or without sharing them with what is
+ * resident, and its caches offered to the surface caches.
+ *
+ * **Surface caches**: a geometry turned resident reaches {@link surfaces} with the bricks its field
+ * stored, whose Model Surface Caches, one per (geometry, material) pair, are baked after the bake,
+ * `surface_budget` bricks a frame.
  *
  * **A geometry with no tree of its own** to bake from, a virtual geometry's, waits queued, as one whose
  * tree is not resident yet does, until it is pointed at a stand-in ({@link alias}): an ordinary geometry
- * in the same local space, baked, placed and captured here as any is. Whoever makes stand-ins hears of
+ * in the same local space, baked here as any is. Whoever makes stand-ins hears of
  * each geometry queued ({@link onRequested}) and let go ({@link onForgotten}), and aliases between
  * frames, its stand-in added to the geometry manager as any geometry is.
  *
@@ -74,11 +82,12 @@ export class GPUGeometrySDFManager {
      */
     onForgotten: any;
     /**
-     * The card sets: one capture of a geometry's layout per (geometry, material) pair, which their
-     * user acquires and releases. Layouts reach it as they are placed.
-     * @returns {GPUMeshCardSets}
+     * The Model Surface Caches: one (geometry, material) pair's surface material texels on its
+     * geometry's field, which their user acquires and releases. Fields reach it as they turn resident,
+     * with the bricks they stored.
+     * @returns {GPUMeshSurfaceCaches}
      */
-    get cards(): GPUMeshCardSets;
+    get surfaces(): GPUMeshSurfaceCaches;
     /**
      * Level 0's voxel, in the geometry's local units, and the bricks per axis past which it grows. A
      * change rebakes every cache.
@@ -126,9 +135,9 @@ export class GPUGeometrySDFManager {
      * follows the source through its bake.
      *
      * Whatever held `clone`'s own cache holds `source`'s from here on, its side included, as does every holder of
-     * `clone` after; and `clone`'s card sets capture `source`'s layout through `source`'s meshlets
-     * ({@link GPUMeshCardSets#alias}). So a source whose stand-in arrives after `clone` was asked for needs
-     * nothing moved by its holders.
+     * `clone` after; and `clone`'s surface caches follow `source`'s field and are baked from `source`'s
+     * triangles ({@link GPUMeshSurfaceCaches#alias}). So a source whose stand-in arrives after `clone` was
+     * asked for needs nothing moved by its holders.
      *
      * @param {GPUGeometryMetadata} clone
      * @param {GPUGeometryMetadata} source
@@ -185,6 +194,17 @@ export class GPUGeometrySDFManager {
      * @returns {number}
      */
     get bricks_evaluated(): number;
+    /**
+     * Bricks the bake gave a slot already holding their bytes, as read back.
+     * @returns {number}
+     */
+    get bricks_shared(): number;
+    /**
+     * Bricks the bake gave a slot of their own because the slot their content key found, or the
+     * frame's first brick of that key, holds other bytes, as read back.
+     * @returns {number}
+     */
+    get bricks_collided(): number;
     /**
      * Free slots of the atlas before the last take read back.
      * @returns {number}
@@ -227,29 +247,57 @@ export class GPUGeometrySDFManager {
      * @returns {number} bytes
      */
     get gpu_memory_usage(): number;
+    /**
+     * Take a bundle's fields (`ModelCacheBundle`) as the caches of the geometries `records` names, in
+     * place of baking them, and offer its surface caches to the caches of the materials `materials`
+     * names. A field is taken by a geometry that has no cache and no bake under way, whose layout at this
+     * manager's voxel size and cap is the field's; any other is left to bake as it would. The next bake
+     * places the bundle's bricks and links the fields' entries to them, and the fields are resident from
+     * the bake after, their surface caches laid out by the bundle's tables (`GPUMeshSurfaceCaches.adopt_layout`).
+     *
+     * A bundle keeps each brick once however many fields hold it. Deduplicating, a brick whose bytes a
+     * slot already holds takes that slot, and the rest are listed for bricks baked later to share; not
+     * deduplicating, each takes a slot of its own, never shared, which suits a bundle of a whole scene
+     * loaded alone. The atlas grows ahead of the bake for every brick, so none waits for a slot.
+     *
+     * A field taken is the geometry's like a baked one: held, released and trimmed alike.
+     *
+     * @param {ModelCacheBundle} bundle baked at this manager's `configure`
+     * @param {(GPUGeometryMetadata|null)[]} records the geometry of each of the bundle's fields; null takes none
+     * @param {(ShadeMaterial|null)[]} materials the material of each of the bundle's caches; null offers none
+     * @param {boolean} deduplicate whether its bricks share slots with those resident, and are shared
+     * @returns {number} the fields taken
+     */
+    upload_bundle(bundle: ModelCacheBundle, records: (GPUGeometryMetadata | null)[], materials: (ShadeMaterial | null)[], deduplicate: boolean): number;
+    /**
+     * A bundle (`ModelCacheBundle`) of the resident fields of `records` and the resident surface caches
+     * `caches`, as the device holds them when the readbacks land: each brick once, however many fields
+     * hold it, and each cache naming its field. Read while nothing bakes, it is what was baked.
+     *
+     * @param {GPUGeometryMetadata[]} records
+     * @param {number[]} caches surface cache ids, each of a geometry of `records`
+     * @returns {Promise<ModelCacheBundle>}
+     */
+    export_bundle(records: GPUGeometryMetadata[], caches: number[]): Promise<ModelCacheBundle>;
     /**
      * Record the frame's bake: queue again what is held for the other side than it was baked for, free
-     * what was given back, classify what is admitted, take, evaluate and store up to `budget` bricks,
-     * place the cards of what turned resident and move placed layouts into their ranges. Then, with a
-     * `capture_budget`, capture up to that many pages of card sets. Records nothing when there is
-     * nothing to do.
+     * what was given back, classify what is admitted, and take, evaluate and store up to `budget`
+     * bricks. Then, with a `surface_budget`, bake up to that many bricks of surface caches. Records
+     * nothing when there is nothing to do.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.budget bricks evaluated at most, `mesh_sdf_bake_budget`
-     * @param {number} [options.capture_budget] card pages captured at most, `card_capture_budget`; 0
-     *        captures nothing
-     * @param {GPUResidentMaterialContext|null} [options.materials] what a traced capture shades with,
-     *        which makes what it traces resident; 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, materials, material_contexts }: {
+     * @param {number} [options.surface_budget] surface cache bricks baked at most,
+     *        `surface_bake_budget`; 0 bakes nothing
+     * @param {GPUResidentMaterialContext|null} [options.materials] what the surface bake shades with,
+     *        which makes what it traces resident; needed with a `surface_budget`
+     */
+    graph_bake({ graph, budget, surface_budget, materials }: {
         graph: FrameGraph;
         budget: number;
-        capture_budget?: number;
+        surface_budget?: number;
         materials?: GPUResidentMaterialContext | null;
-        material_contexts?: GPUMaterialManager | null;
     }): void;
     destroy(): void;
     #private;
@@ -258,7 +306,8 @@ export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/
 export type GPUGeometryManager = import("../GPUGeometryManager.js").GPUGeometryManager;
 export type GPUGeometryMetadata = import("../GPUGeometryMetadata.js").GPUGeometryMetadata;
 export type GPUResidentMaterialContext = import("../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext;
-export type GPUMaterialManager = import("../../material/GPUMaterialManager.js").GPUMaterialManager;
-import { GPUMeshCardSets } from "./cards/GPUMeshCardSets.js";
+export type ShadeMaterial = import("../../material/ShadeMaterial.js").ShadeMaterial;
+import { GPUMeshSurfaceCaches } from "./surface/GPUMeshSurfaceCaches.js";
 import { MeshSDFState } from "./MESH_SDF.js";
+import { ModelCacheBundle } from "./bundle/ModelCacheBundle.js";
 //# sourceMappingURL=GPUGeometrySDFManager.d.ts.map

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAuIA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAgDvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAyQI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IAxQD;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAE3B;;;;OAIG;IACH,iBAA2B;IAuP3B;;;;OAIG;IACH,6BAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAajB;IAiCD;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAiB7B;IAED;;;;;;;;;;;;OAYG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QAwD7B;IAcD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAaxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;QAEG,iBAAiB,GAAnD,kBAAkB,GAAC,IAAI;aAuEjC;IAojCD,gBAsBC;;CACJ;yBAziEY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;iCAC1F,OAAO,sCAAsC,EAAE,kBAAkB;gCAnBhB,4BAA4B;6BAQf,eAAe"}
+{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAmLA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAoEvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IA8QI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IA7QD;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAE3B;;;;OAIG;IACH,iBAA2B;IA4P3B;;;;;OAKG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAajB;IAiCD;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAiB7B;IAED;;;;;;;;;;;;OAYG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QAwD7B;IAcD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAcxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBANW,gBAAgB,WAChB,CAAC,mBAAmB,GAAC,IAAI,CAAC,EAAE,aAC5B,CAAC,aAAa,GAAC,IAAI,CAAC,EAAE,eACtB,OAAO,GACL,MAAM,CA2JlB;IA2CD;;;;;;;;OAQG;IACH,uBAJW,mBAAmB,EAAE,UACrB,MAAM,EAAE,GACN,QAAQ,gBAAgB,CAAC,CAqIrC;IAED;;;;;;;;;;;;;OAaG;IACH;QAP+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;aA+EzC;IAy+BD,gBAsCC;;CACJ;yBAj6EY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;4BAC1F,OAAO,iCAAiC,EAAE,aAAa;qCAnB/B,mCAAmC;6BAOjE,eAAe;iCATyD,8BAA8B"}