@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/scene/GPUSceneContext.d.ts

@@ -1,5 +1,12 @@
 /**
- * Abstraction on the context of a scene, there are no hierarchies, just a collection of meshes and a geometry context
+ * The GPU side of one {@link Scene}: its database — the `transforms` and `meshes` tables, one row
+ * per entity that is drawn or posed, at `entity + 1` — and what is built over that database each
+ * frame: the lights' records, the probe volume, the volumetrics, the animation, the TLAS.
+ *
+ * Nothing here holds a hierarchy of its own. An entity's row names its parent's row and the GPU
+ * composes the chain each frame, derives every mesh row's bounds under the composed matrix and
+ * builds the tree over them — see {@link tick}. What the CPU writes is what it owns: an entity's
+ * local TRS and the row of its parent, through {@link rows}.
  */
 export class GPUSceneContext {
     /**
@@ -47,21 +54,22 @@ export class GPUSceneContext {
      */
     get tlas(): GPUInstancesAccelerationStructure;
     /**
-     * Mesh → instance index. Rebuilt each frame in {@link build}. The
-     * Lookup from a node's stable JS-side {@link Node3D.id} to its row
-     * in the scene database's `transforms` table. Built during
-     * {@link build} as each node is allocated via
-     * {@link GPUTypedTable.add}; the table itself owns the row
-     * allocation, this map just bridges between Node3D handles and the
-     * GPU rows they live at.
+     * @returns {GPUVirtualGeometryRuntime|undefined}
+     */
+    get virtual_geometry(): GPUVirtualGeometryRuntime;
+    /**
+     * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
+     * draws.
      *
-     * Public so external code can do partial updates: looking up a
-     * single node's row lets a system patch one `transforms_table`
-     * entry instead of re-uploading the whole scene.
+     * Sharing the pool is the whole seam on this side: a cut emits `MESHLET_DEFINITION_STRUCT`
+     * records naming rows of the same metadata buffer a static mesh's meshlets live in, so nothing
+     * downstream of the expansion has to know which kind of geometry it is looking at.
      *
-     * @type {Map<number, number>}
+     * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
+     *     {@link GPUVirtualGeometryRuntime}
+     * @returns {GPUVirtualGeometryRuntime}
      */
-    id_mapping: Map<number, number>;
+    enable_virtual_geometry(options?: any): GPUVirtualGeometryRuntime;
     /**
      * @returns {GPUAnimationManager}
      */
@@ -79,10 +87,9 @@ export class GPUSceneContext {
      */
     get scene_database_buffer(): GPUBuffer;
     /**
-     * Per-scene skinning subsystem. Routes {@link SkinnedMesh}
-     * instances through per-instance geometry clones; later phases
-     * grow Skin-binding management and the per-frame skinning compute
-     * onto it.
+     * Per-scene skinning subsystem. Routes skinned rows through
+     * per-instance geometry clones; later phases grow Skin-binding
+     * management and the per-frame skinning compute onto it.
      *
      * Lazy because it depends on {@link geometries}, which is assigned
      * externally after this object's constructor returns
@@ -94,32 +101,37 @@ export class GPUSceneContext {
     get skinning(): GPUMeshSkinningContext;
     get gpu_memory_usage(): number;
     /**
-     * Which row of the `meshes` table a node occupies — **the value the visibility buffer writes
-     * for every pixel that node covers**, which is what makes it worth reading from outside.
+     * Entities as rows of the scene database, at `entity + 1` in both tables.
      *
-     * `id_mapping` is not this. That map goes from a node's id to its row in the `transforms`
-     * table, which is a different table with different rows; a caller that used it to index the
-     * visibility buffer would be reading somebody else's mesh.
+     * A system that places an entity acquires its row here and marks it on the dataset's change
+     * events; a scene with no systems places through `prefab_place` and `place_primitive`, which
+     * do the same by hand; and {@link build} flushes what was marked. The scene has to name its
+     * dataset ({@link Scene.dataset}) before this is first asked for, because the rows are written
+     * from that dataset's components.
      *
-     * @param {Node3D} node
-     * @returns {number} the row, or `-1` for a node that is not in this scene or carries no geometry
+     * @returns {GPUSceneRows}
      */
-    mesh_row_of(node: Node3D): number;
+    get rows(): GPUSceneRows;
     /**
-     * Bumped every time the `meshes` table gains or loses a row. **Rows are reused** — the table
-     * hands out the lowest free one — so a row read through {@link mesh_row_of} and kept is only
-     * valid while this number is unchanged. Anything holding one compares against its own copy and
-     * re-reads when they differ.
+     * An entity's world bounds as the GPU holds them, read back — what a consumer that wants the
+     * box that is drawn asks, a frame or two behind the device. Built on demand, over the rows.
      *
-     * @returns {number}
+     * @returns {GPUEntityBoundsReadback}
      */
-    get mesh_rows_version(): number;
+    get bounds(): GPUEntityBoundsReadback;
     /**
-     * Bring the GPU scene database in line with the scene, writing only the rows that changed.
+     * Every material something in the scene draws with, each once — the rows' own list, kept
+     * current as meshes attach and detach. What the rasterizers iterate to decide which buckets
+     * and pipelines a frame needs. The array is reused until the set changes; a scene with no
+     * rows draws with nothing.
      *
-     * Membership is reconciled when the batch says it moved; transforms are checked every frame,
-     * because a node moving does not touch the batch. Both walk the scene once and write nothing
-     * for a node that has not changed.
+     * @returns {ShadeMaterial[]}
+     */
+    get drawn_materials(): import("../material/ShadeMaterial.js").ShadeMaterial[];
+    /**
+     * Bring the GPU scene database in line with the scene, writing only the rows that changed:
+     * the scene root's, once; a light's, as it arrives; and every entity's row that a system
+     * marked since the last build. Nothing is walked — the rows keep what was marked.
      */
     build(): void;
     /**
@@ -128,15 +140,24 @@ export class GPUSceneContext {
      */
     update(ctx: GraphicsContext): void;
     /**
-     * Per-frame animation tick — drains pending registrations,
-     * advances `clip.time` on the GPU, runs apply → resolve →
-     * hierarchy propagate → skin-matrix prep → skinning. Thin
-     * passthrough to {@link GPUAnimationManager#tick}; lives here
-     * so the renderer can call it on every scene it renders without
-     * reaching past `GPUSceneContext` for an internal manager.
+     * Per-frame GPU-side scene update, once per scene per frame, after every view's {@link update}
+     * has flushed what the CPU changed:
+     *
+     * 1. the animation tick — pending registrations drained, `clip.time` advanced, apply → resolve
+     *    → hierarchy propagate → skin-matrix prep → skinning, through {@link GPUAnimationManager#tick};
+     * 2. render bounds — every mesh row's world box and sphere, derived from its geometry under
+     *    the `global` the hierarchy pass just composed, because the CPU does not hold that matrix
+     *    for a subtree the GPU drives;
+     * 3. light poses — every light record's position and direction, from its entity's row, for
+     *    the same reason;
+     * 4. the TLAS — rebuilt from those bounds when anything moved, on either side.
+     *
+     * All four into `cmd_ctx`, in that order, so the tree the frame's ray passes traverse is built
+     * over this frame's bounds rather than last frame's, and what lights the frame is where it is
+     * this frame.
      *
-     * `dt_seconds` is wall-clock seconds since the last call (the
-     * renderer's `time_delta_seconds` argument to `render()`).
+     * `dt_seconds` is wall-clock seconds since the last call (the renderer's `time_delta_seconds`
+     * argument to `render()`).
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      * @param {number} dt_seconds wall-clock seconds since last call
@@ -153,15 +174,19 @@ export class GPUSceneContext {
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
 export type GPUGeometryManager = import("../geometry/GPUGeometryManager.js").GPUGeometryManager;
 export type GPUMaterialManager = import("../material/GPUMaterialManager.js").GPUMaterialManager;
-export type Node3D = import("./Node3D.js").Node3D;
+export type ShadeMaterial = import("../material/ShadeMaterial.js").ShadeMaterial;
+export type GPURecordWriter = import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter;
 import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
 import { Scene } from "./Scene.js";
 import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
 import { GPULightCollection } from "../light/GPULightCollection.js";
 import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
 import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
+import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
+import { GPUSceneRows } from "./rows/GPUSceneRows.js";
+import { GPUEntityBoundsReadback } from "./rows/GPUEntityBoundsReadback.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 //# sourceMappingURL=GPUSceneContext.d.ts.map

package/src/shade/renderer/scene/GPUSceneContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AAmEA;;GAEG;AACH;IAkJI;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IApLD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAmBD;;;;;;;;;;;;;;OAcG;IACH,YAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAEN;IAgEvB;;OAEG;IACH,6CAEC;IAeD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;;OAYG;IACH,uCAUC;IAED,+BAUC;IAkKD;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;OAOG;IACH,gCAEC;IAuRD;;;;;;OAMG;IACH,cA4DC;IAED;;;OAGG;IACH,YAFW,eAAe,QAyBzB;IAED;;;;;;;;;;;;;OAaG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAIhB;IAED,gBAQC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BAv4BY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;qBAC9D,OAAO,aAAa,EAAE,MAAM;+BAhBV,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;oCAPtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;uCATjD,wCAAwC"}
+{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AA8DA;;;;;;;;;GASG;AACH;IA0II;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IA5KD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAsGD;;OAEG;IACH,kDAEC;IAED;;;;;;;;;;;OAWG;IACH,wCAFa,yBAAyB,CAoBrC;IAED;;OAEG;IACH,6CAEC;IAYD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;OAWG;IACH,uCAUC;IAED,+BAUC;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,sCAMC;IAOD;;;;;;;OAOG;IACH,8EAEC;IA0BD;;;;OAIG;IACH,cAqEC;IAED;;;OAGG;IACH,YAFW,eAAe,QA0BzB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAuBhB;IAoCD,gBAYC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BAxmBY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;4BAC9D,OAAO,8BAA8B,EAAE,aAAa;8BACpD,OAAO,iDAAiD,EAAE,eAAe;+BAtBvD,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;0CAVhD,0DAA0D;oCAGhE,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;6BAM3D,wBAAwB;wCADb,mCAAmC;uCAdpC,wCAAwC"}