@woosh/meep-engine 3.61.2 → 3.62.0

package/src/shade/renderer/geometry/sdf/surface/GPUMeshSurfaceCaches.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Model Surface Caches: one (geometry, material) pair's surface material (`SURFACE_MATERIAL.js`) on its
+ * geometry's field, by cache id, the storage of which {@link GPUGeometrySDFManager} keeps beside the
+ * fields.
+ *
+ * - **Blocks.** A field's bricks are surveyed once (`MESH_SURFACE_BAKE.js`): a brick keeps each of its
+ *   eight 4³ blocks (`MESH_SURFACE_BLOCK.js`) some texel of which can hold surface, numbered in the
+ *   geometry's block table, a word a brick, and the count read back. Every cache of the geometry keeps
+ *   its blocks by those numbers.
+ * - **What a cache keeps** follows its material and its geometry (`mesh_surface_channels`): each plane
+ *   that varies over the surface keeps its blocks, coded, and each other plane only its code in the
+ *   record, the value every texel takes. A cache that keeps any plane keeps a block of presence for each
+ *   block: which texels a bake found surface under. A cache that keeps no plane is never baked.
+ * - **Storage** is one buffer of words, `mesh_surface_data`, for the tables and for each cache's run of
+ *   blocks in its presence and each plane it keeps, each run its own allocation. The record
+ *   (`MESH_SURFACE_STRUCT`) is written when the runs are given.
+ *
+ * **Lifetime.** {@link acquire} makes a cache for a pair and {@link release} gives it back; the caller
+ * keeps one per pair. A cache of an aliased geometry ({@link alias}) is its source's, baked from the
+ * source's triangles. A cache waits until its geometry's field is resident ({@link set_layout}) and,
+ * when it keeps a plane, surveyed ({@link set_blocks}); it is then baked, and turns resident on the frame
+ * its last brick is recorded: the bake's writes come before any later pass reads it. Every bake recorded
+ * in full sends {@link onBaked}, the first and each one after. A field that goes ({@link drop_layout})
+ * withdraws its caches ({@link onWithdrawn}) back to waiting.
+ *
+ * **A frame** ({@link graph_bake}) takes at most `budget` bricks: surveys first, then first bakes in the
+ * order they were asked for, then bakes again in the order queued. A bake is a thread a texel of each
+ * brick, then a workgroup a texel that holds surface, then a workgroup a block. A survey's or a bake's
+ * bricks may span frames. {@link recapture} takes a cache's material as it is now: a resident cache
+ * keeping the same planes is queued again and reads its last bake until the new one is done, a cache
+ * whose bake is under way starts it again, and one keeping other planes than before is withdrawn and
+ * laid out anew. The rays read the geometry's BLAS and the material's resident row: what reads a cache
+ * needs neither.
+ */
+export class GPUMeshSurfaceCaches {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * Sent with a cache id each time a bake of it is recorded in full, its first and each one after:
+     * what was taken from its last one is to be taken again.
+     * @type {Signal<number>}
+     */
+    onBaked: any;
+    /**
+     * Sent with a resident cache's id when what it holds goes: its field went, or its material now
+     * varies in other planes. It is baked again.
+     * @type {Signal<number>}
+     */
+    onWithdrawn: any;
+    /**
+     * Caches given out: acquired and not yet released.
+     * @returns {number}
+     */
+    get count(): number;
+    /**
+     * Caches readers may use.
+     * @returns {number}
+     */
+    get resident_count(): number;
+    /**
+     * Bricks baked since this was made, every bake's.
+     * @returns {number}
+     */
+    get bricks_baked(): number;
+    /**
+     * Whether a frame has anything to do: bricks to survey or bake, or caches turned resident with
+     * nothing to bake, still to be announced.
+     * @returns {boolean}
+     */
+    get has_pending_bake(): boolean;
+    /**
+     * Whether readers may use the cache: baked at least once, and its field still there.
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    is_resident(id: number): boolean;
+    /**
+     * The cache's geometry id: the source's, for an aliased geometry.
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    geometry_of(id: number): number;
+    /**
+     * The material the cache was acquired for: what a bundle exported with it names it by, to offer it
+     * back (`GPUGeometrySDFManager.upload_bundle`).
+     *
+     * @param {number} id
+     * @returns {ShadeMaterial}
+     */
+    material_of(id: number): ShadeMaterial;
+    /**
+     * The blocks a surveyed field's bricks keep, or undefined before its survey is read back.
+     *
+     * @param {number} geometry
+     * @returns {number|undefined}
+     */
+    blocks_of(geometry: number): number | undefined;
+    /**
+     * Every cache's record, by id. Replaced when it grows; take it each frame.
+     * @returns {GPUBuffer}
+     */
+    get records(): GPUBuffer;
+    /**
+     * The caches' words: the block tables and the caches' blocks. Replaced when it grows; take it each
+     * frame.
+     * @returns {GPUBuffer}
+     */
+    get data(): GPUBuffer;
+    /**
+     * Put what the caches' readers (`chunk_mesh_surface_sample`) take into their bindings, under the
+     * names they take. The records and the words are replaced as they grow: take them each frame.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_bindings(bindings: any): any;
+    /**
+     * A cache for a pair. The caller keeps one per pair.
+     *
+     * @param {number} geometry the geometry id the pair draws; an aliased one's cache is its source's ({@link alias})
+     * @param {ShadeMaterial} material
+     * @returns {number} cache id
+     */
+    acquire(geometry: number, material: ShadeMaterial): number;
+    /**
+     * @param {number} id
+     */
+    release(id: number): void;
+    /**
+     * The cache's material has changed (its version moved): take it as it is now. A cache that keeps the
+     * same planes as before is baked again, and a resident one reads its last bake until the new one is
+     * done; one that keeps none has its record's codes rewritten and is announced at once. A cache that
+     * keeps other planes than before is withdrawn and laid out anew.
+     *
+     * @param {number} id
+     */
+    recapture(id: number): void;
+    /**
+     * A geometry's field is resident, having stored `stored` bricks: its caches that keep no plane are
+     * laid out at once, and the first that keeps one has its bricks queued to be surveyed.
+     *
+     * @param {number} geometry
+     * @param {number} stored
+     * @param {boolean} colored whether the geometry has vertices of a color other than white, which the
+     *        diffuse albedo varies with (`meshlet_batch_colored`)
+     */
+    set_layout(geometry: number, stored: number, colored: boolean): void;
+    /**
+     * A geometry's field is resident, taken from a bundle (`ModelCacheBundle`) with the survey its
+     * caches were laid out by: `blocks` blocks numbered in `table`, a word a stored brick, or no table
+     * when no cache of it kept a plane, which leaves a cache that keeps one to have the field surveyed.
+     * Each of `provisions` offers a cache of the bundle to the geometry's cache of its material, for as
+     * long as this field is the geometry's: a cache whose material makes it keep the planes the bundle's
+     * did, with the same codes, takes the bundle's blocks and is resident without a bake; any other is
+     * baked as `set_layout` would have it.
+     *
+     * @param {number} geometry
+     * @param {number} stored
+     * @param {boolean} colored whether the geometry has vertices of a color other than white
+     * @param {number} blocks
+     * @param {Uint32Array} table `stored` words, or none
+     * @param {{material: ShadeMaterial, cache: ModelCacheBundleCache}[]} provisions
+     */
+    adopt_layout(geometry: number, stored: number, colored: boolean, blocks: number, table: Uint32Array, provisions: {
+        material: ShadeMaterial;
+        cache: ModelCacheBundleCache;
+    }[]): void;
+    /**
+     * The block table of a geometry's field as the storage holds it, read back whole as `words`: its
+     * blocks and words, or 0 and none before a survey.
+     *
+     * @param {number} geometry
+     * @param {Uint32Array} words `data` read back
+     * @returns {{blocks: number, table: Uint32Array}}
+     */
+    export_table(geometry: number, words: Uint32Array): {
+        blocks: number;
+        table: Uint32Array;
+    };
+    /**
+     * A resident cache as a bundle's cache laid out by bundle field `field`, its blocks as the storage
+     * holds them, read back whole as `words`.
+     *
+     * @param {number} id
+     * @param {number} field
+     * @param {Uint32Array} words `data` read back
+     * @param {ModelCacheBundleCache} out
+     * @returns {ModelCacheBundleCache} out
+     */
+    export_cache(id: number, field: number, words: Uint32Array, out: ModelCacheBundleCache): ModelCacheBundleCache;
+    /**
+     * A geometry's survey is read back: its field's bricks keep `blocks` blocks, numbered in its table.
+     * Its caches that keep a plane are laid out.
+     *
+     * @param {number} geometry
+     * @param {number} blocks
+     */
+    set_blocks(geometry: number, blocks: number): void;
+    /**
+     * A geometry's field is gone: its caches wait for the next.
+     *
+     * @param {number} geometry
+     */
+    drop_layout(geometry: number): void;
+    /**
+     * The geometry `clone` is drawn as `source` from here on: its caches, and those acquired for it after,
+     * follow `source`'s field and are baked from `source`'s triangles, the two being in one local space.
+     * A cache of `clone` waits for `source`'s field, as one acquired for `source` does.
+     *
+     * @param {number} clone
+     * @param {number} source
+     */
+    alias(clone: number, source: number): void;
+    /**
+     * `clone` is no longer aliased: caches acquired for it from here on follow its own field. Those it has
+     * keep following its source's until they are given back.
+     *
+     * @param {number} clone
+     */
+    unalias(clone: number): void;
+    /**
+     * Record the frame's surveys and bake: at most `budget` bricks. Records nothing when nothing waits.
+     * Caches whose bake this completes are announced through {@link onBaked}, resident from here; the
+     * surveys it completes are read back.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.budget bricks surveyed and baked at most, `surface_bake_budget`: a frame
+     *        lists every texel of its bricks in one storage binding
+     * @param {number} options.arena graph handle of the fields' indirection, as the frame's bake left it
+     * @param {GPUBuffer} options.headers the fields' headers
+     * @param {GPUTextureView} options.field_atlas the fields' atlas
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each baked
+     *        material is made resident, and the rows committed, before the trace is recorded
+     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads
+     */
+    graph_bake({ graph, budget, arena, headers, field_atlas, materials, blas }: {
+        graph: FrameGraph;
+        budget: number;
+        arena: number;
+        headers: GPUBuffer;
+        field_atlas: GPUTextureView;
+        materials: GPUResidentMaterialContext;
+        blas: any;
+    }): void;
+    /**
+     * @returns {number} bytes
+     */
+    get gpu_memory_usage(): number;
+    destroy(): void;
+    #private;
+}
+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 Allocation = import("../../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
+export type ModelCacheBundleCache = import("../bundle/ModelCacheBundle.js").ModelCacheBundleCache;
+//# sourceMappingURL=GPUMeshSurfaceCaches.d.ts.map

package/src/shade/renderer/geometry/sdf/surface/GPUMeshSurfaceCaches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUMeshSurfaceCaches.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/surface/GPUMeshSurfaceCaches.js"],"names":[],"mappings":"AAuHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAkNI;;OAEG;IACH,+BAIC;IAlND;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAwM3B;;;OAGG;IACH,oBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,gCAKC;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,aAAa,CAIzB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,yBAIC;IAED;;;;OAIG;IACH,sBAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CAkClB;IAED;;OAEG;IACH,YAFW,MAAM,QA4BhB;IAED;;;;;;;OAOG;IACH,cAFW,MAAM,QAiDhB;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,UACN,MAAM,WACN,OAAO,QAuBjB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAPW,MAAM,UACN,MAAM,WACN,OAAO,UACP,MAAM,SACN,WAAW,cACX;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAA;KAAC,EAAE,QA+BnE;IA2CD;;;;;;;OAOG;IACH,uBAJW,MAAM,SACN,WAAW,GACT;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAC,CAWhD;IAED;;;;;;;;;OASG;IACH,iBANW,MAAM,SACN,MAAM,SACN,WAAW,OACX,qBAAqB,GACnB,qBAAqB,CAqBjC;IA6BD;;;;;;OAMG;IACH,qBAHW,MAAM,UACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA0ChB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,UACN,MAAM,QAoChB;IAED;;;;;OAKG;IACH,eAFW,MAAM,QAIhB;IA8bD;;;;;;;;;;;;;;;OAeG;IACH;QAV+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QAEU,KAAK,EAArB,MAAM;QACa,OAAO;QACF,WAAW;QACC,SAAS,EAA7C,0BAA0B;QAEV,IAAI;aAiE9B;IA6UD;;OAEG;IACH,+BAUC;IAED,gBAgBC;;CACJ;yBApvDY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;yBAC7F,OAAO,yDAAyD,EAAE,UAAU;oCAC5E,OAAO,+BAA+B,EAAE,qBAAqB"}