@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/renderer/rasterize/expand/pass0/pass_mesh_cull.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../../../core/assert.js";
 import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { shader_hzb_mesh_filter_2way } from "../../cull/hzb/shader_hzb_mesh_filter_2way.js"
 import { U32_CONTAINER_STRUCT } from "../../../shader/type/U32_CONTAINER_STRUCT.js";
@@ -44,6 +45,7 @@ export function pass_mesh_cull(data, resources, context) {
 
     const bucket_id = data.bucket_index;
 
+    assert.isNonNegativeInteger(bucket_id, 'bucket_id');
 
     build_indirect_compute_dispatch_command(
         COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
@@ -55,17 +57,15 @@ export function pass_mesh_cull(data, resources, context) {
         0
     );
 
-    const bucket_index = encoder.allocateTransientValueBuffer(
-        U32_CONTAINER_STRUCT,
-        {
-            value: bucket_id,
-        }
-    );
+    // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
+    const u_bucket_index = encoder.allocateTransientValueBuffer(U32_CONTAINER_STRUCT, {
+        value: bucket_id,
+    });
 
     shader_hzb_mesh_filter_2way.dispatchIndirect({
         encoder,
         bindings: {
-            bucket_index,
+            bucket_index: u_bucket_index,
             camera_previous: view_ctx.gpu_previous_camera_state.buffer,
             bucket_data,
             scene_database: gpu_scene.scene_database_buffer,

package/src/shade/renderer/rasterize/fast/graph_extract_meshes_from_bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_extract_meshes_from_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_extract_meshes_from_bucket.js"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH;IAN+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACU,SAAS,EAAzB,MAAM;IACuB,MAAM;IACjC,MAAM,CA2DlB"}
+{"version":3,"file":"graph_extract_meshes_from_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_extract_meshes_from_bucket.js"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH;IAN+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACU,SAAS,EAAzB,MAAM;IACuB,MAAM;IACjC,MAAM,CAgElB"}

package/src/shade/renderer/rasterize/fast/graph_extract_meshes_from_bucket.js

@@ -1,79 +1,84 @@
-import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
-import {
-    build_indirect_compute_dispatch_command,
-    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
-} from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
-import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
-import { shader_read_out_bucket } from "../bucket/shader_read_out_bucket.js";
-
-/**
- * Extract a single bucket's mesh indices out of a bucket-sorted mesh buffer.
- * Produces a flat {@link COLLECTION_U32_STRUCT_READ} buffer.
- *
- * @param {Object} options
- * @param {FrameGraph} options.graph
- * @param {number} options.buckets bucket-sorted meshes resource ID
- * @param {number} options.bucket_id
- * @param {GPUCollectionLimits} options.limits
- * @returns {number} resource ID of extracted mesh list
- */
-export function graph_extract_meshes_from_bucket({
-                                                     graph,
-                                                     buckets,
-                                                     bucket_id,
-                                                     limits,
-                                                 }) {
-
-    /**
-     *
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute(data, resources, context) {
-        const encoder = context.encoder;
-
-        const buckets = resources.get(data.buckets);
-        const output = resources.get(data.output);
-        const command = resources.get(data.command);
-
-        const bucket_id = data.bucket_id;
-
-        build_indirect_compute_dispatch_command(
-            COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
-            encoder,
-            buckets,
-            // the bucketed buffer header consists of pairs of u32 values (count,offset)
-            bucket_id * (u32.size * 2),
-            command,
-            0
-        );
-
-        shader_read_out_bucket.dispatchIndirect({
-            encoder,
-            command,
-            bindings: {
-                settings: { bucket_id },
-                input: buckets,
-                output,
-            }
-        });
-    }
-
-    const data = {};
-
-    const pass = graph.add("extract meshes from bucket", data, execute);
-
-    data.buckets = pass.read(buckets);
-    data.bucket_id = bucket_id;
-    data.command = pass.create("command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
-    data.output = pass.create("output", BufferResourceDescriptor.from(
-        limits.compute_buffer_size(RasterizationCollectionType.Meshes),
-        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-        0, 16 // clear count
-    ));
-
-    return data.output;
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import {
+    build_indirect_compute_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
+import { PUSH_CONSTANTS, shader_read_out_bucket } from "../bucket/shader_read_out_bucket.js";
+
+/**
+ * Extract a single bucket's mesh indices out of a bucket-sorted mesh buffer.
+ * Produces a flat {@link COLLECTION_U32_STRUCT_READ} buffer.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshes resource ID
+ * @param {number} options.bucket_id
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} resource ID of extracted mesh list
+ */
+export function graph_extract_meshes_from_bucket({
+                                                     graph,
+                                                     buckets,
+                                                     bucket_id,
+                                                     limits,
+                                                 }) {
+
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        const buckets = resources.get(data.buckets);
+        const output = resources.get(data.output);
+        const command = resources.get(data.command);
+
+        const bucket_id = data.bucket_id;
+
+        build_indirect_compute_dispatch_command(
+            COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
+            encoder,
+            buckets,
+            // the bucketed buffer header consists of pairs of u32 values (count,offset)
+            bucket_id * (u32.size * 2),
+            command,
+            0
+        );
+
+        // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
+        const u_settings = encoder.allocateTransientValueBuffer(PUSH_CONSTANTS, {
+            bucket_id,
+        });
+
+        shader_read_out_bucket.dispatchIndirect({
+            encoder,
+            command,
+            bindings: {
+                settings: u_settings,
+                input: buckets,
+                output,
+            }
+        });
+    }
+
+    const data = {};
+
+    const pass = graph.add("extract meshes from bucket", data, execute);
+
+    data.buckets = pass.read(buckets);
+    data.bucket_id = bucket_id;
+    data.command = pass.create("command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+    data.output = pass.create("output", BufferResourceDescriptor.from(
+        limits.compute_buffer_size(RasterizationCollectionType.Meshes),
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        0, 16 // clear count
+    ));
+
+    return data.output;
 }

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAwMjG"}
+{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA6MjG"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js

@@ -3,6 +3,7 @@ import { noop } from "../../../../core/function/noop.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { shader_hzb_mesh_filter_2way } from "../cull/hzb/shader_hzb_mesh_filter_2way.js";
+import { U32_CONTAINER_STRUCT } from "../../shader/type/U32_CONTAINER_STRUCT.js";
 import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
 import { TransparencyMode } from "../../material/TransparencyMode.js";
@@ -95,11 +96,16 @@ export function graph_rasterize_partial_opaque({
             0
         );
 
+        // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
+        const u_bucket_index = encoder.allocateTransientValueBuffer(U32_CONTAINER_STRUCT, {
+            value: bucket_index,
+        });
+
         // split 2 ways
         shader_hzb_mesh_filter_2way.dispatchIndirect({
             encoder,
             bindings: {
-                bucket_index: { value: bucket_index },
+                bucket_index: u_bucket_index,
                 camera_previous,
                 bucket_data: buckets,
                 scene_database: scene_ctx.scene_database_buffer,

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA4GlD"}
+{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AAgGA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA4GlD"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js

@@ -10,6 +10,7 @@ import { build_indirect_compute_dispatch_command } from "../../gpu_primitive/ind
 import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
 import { graph_sort_meshlets_by_bucket_id } from "../expand/bucket/meshlet/graph_sort_meshlets_by_bucket_id.js";
 import { shader_meshlets_extract_bucket } from "../expand/bucket/meshlet/shader_meshlets_extract_bucket.js";
+import { U32_CONTAINER_STRUCT } from "../../shader/type/U32_CONTAINER_STRUCT.js";
 import { graph_mesh_filter_one_way } from "../expand/graph_mesh_filter_one_way.js";
 import { graph_meshlets_filter_one_way } from "../expand/graph_meshlets_filter_one_way.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
@@ -58,11 +59,16 @@ function graph_extract_meshlets_from_bucket({
             0
         );
 
+        // TODO(chrome-153): transient uniform, not an immediate value — see the shader.
+        const u_bucket_index = encoder.allocateTransientValueBuffer(U32_CONTAINER_STRUCT, {
+            value: bucket_id,
+        });
+
         shader_meshlets_extract_bucket.dispatchIndirect({
             encoder,
             command,
             bindings: {
-                bucket_index: { value: bucket_id },
+                bucket_index: u_bucket_index,
                 bucket_data: buckets,
                 output: output,
             }

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

@@ -57,6 +57,14 @@ export class GPUSceneContext {
      * @returns {GPUVirtualGeometryRuntime|undefined}
      */
     get virtual_geometry(): GPUVirtualGeometryRuntime;
+    /**
+     * @returns {VGeoResidency|undefined}
+     */
+    get virtual_geometry_residency(): VGeoResidency;
+    /**
+     * @returns {VGeoFeedbackLoop|undefined}
+     */
+    get virtual_geometry_feedback(): VGeoFeedbackLoop;
     /**
      * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
      * draws.
@@ -65,11 +73,20 @@ export class GPUSceneContext {
      * 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.
      *
+     * And the residency and the feedback loop with it, so that an engine host gets the whole
+     * streaming loop by enabling virtual geometry rather than by wiring four objects itself
+     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, call
+     * {@link virtual_geometry_feedback}'s `read` once a frame after the last rasterization path,
+     * and every page after the root arrives because the cut asked for it.
+     *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
-     *     {@link GPUVirtualGeometryRuntime}
+     *     {@link GPUVirtualGeometryRuntime}, except for `residency`
+     * @param {VGeoResidencyOptions} [options.residency] every knob of both residency tiers
      * @returns {GPUVirtualGeometryRuntime}
      */
-    enable_virtual_geometry(options?: any): GPUVirtualGeometryRuntime;
+    enable_virtual_geometry(options?: {
+        residency?: VGeoResidencyOptions;
+    }): GPUVirtualGeometryRuntime;
     /**
      * @returns {GPUAnimationManager}
      */
@@ -183,6 +200,9 @@ 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 { VGeoResidency } from "../geometry/virtual/runtime/VGeoResidency.js";
+import { VGeoFeedbackLoop } from "../geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VGeoResidencyOptions } from "../geometry/virtual/runtime/VGeoResidencyOptions.js";
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";

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":"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"}
+{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AAmEA;;;;;;;;;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;IAoHD;;OAEG;IACH,kDAEC;IAED;;OAEG;IACH,gDAEC;IAED;;OAEG;IACH,kDAEC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAH0C,SAAS,GAAxC,oBAAoB;QAClB,yBAAyB,CAmCrC;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;8BA1pBY,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;0CAfhD,0DAA0D;8BAItE,8CAA8C;iCAF3C,iDAAiD;qCAG7C,qDAAqD;oCAGtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;6BAM3D,wBAAwB;wCADb,mCAAmC;uCAdpC,wCAAwC"}

package/src/shade/renderer/scene/GPUSceneContext.js

@@ -1,5 +1,10 @@
 import { GPUVirtualGeometryPool } from "../geometry/virtual/runtime/GPUVirtualGeometryPool.js";
 import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
+import { make_vgeo_page_worker } from "../geometry/virtual/runtime/make_vgeo_page_worker.js";
+import { VGeoFeedbackLoop } from "../geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VGeoPageFetcher } from "../geometry/virtual/runtime/VGeoPageFetcher.js";
+import { VGeoResidency } from "../geometry/virtual/runtime/VGeoResidency.js";
+import { VGeoResidencyOptions } from "../geometry/virtual/runtime/VGeoResidencyOptions.js";
 import { assert } from "../../../core/assert.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
@@ -258,6 +263,20 @@ export class GPUSceneContext {
      */
     #virtual_geometry;
 
+    /**
+     * Both tiers of virtual-geometry residency, once {@link enable_virtual_geometry} has run.
+     * @type {VGeoResidency|undefined}
+     */
+    #virtual_geometry_residency;
+
+    /**
+     * The feedback loop that carries the cut's readings into the residency, once
+     * {@link enable_virtual_geometry} has run. A host calls its `read` once a frame after every
+     * rasterization path has cut.
+     * @type {VGeoFeedbackLoop|undefined}
+     */
+    #virtual_geometry_feedback;
+
     /**
      * @returns {GPUVirtualGeometryRuntime|undefined}
      */
@@ -265,6 +284,20 @@ export class GPUSceneContext {
         return this.#virtual_geometry;
     }
 
+    /**
+     * @returns {VGeoResidency|undefined}
+     */
+    get virtual_geometry_residency() {
+        return this.#virtual_geometry_residency;
+    }
+
+    /**
+     * @returns {VGeoFeedbackLoop|undefined}
+     */
+    get virtual_geometry_feedback() {
+        return this.#virtual_geometry_feedback;
+    }
+
     /**
      * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
      * draws.
@@ -273,8 +306,15 @@ export class GPUSceneContext {
      * 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.
      *
+     * And the residency and the feedback loop with it, so that an engine host gets the whole
+     * streaming loop by enabling virtual geometry rather than by wiring four objects itself
+     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, call
+     * {@link virtual_geometry_feedback}'s `read` once a frame after the last rasterization path,
+     * and every page after the root arrives because the cut asked for it.
+     *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
-     *     {@link GPUVirtualGeometryRuntime}
+     *     {@link GPUVirtualGeometryRuntime}, except for `residency`
+     * @param {VGeoResidencyOptions} [options.residency] every knob of both residency tiers
      * @returns {GPUVirtualGeometryRuntime}
      */
     enable_virtual_geometry(options = {}) {
@@ -282,16 +322,31 @@ export class GPUSceneContext {
             return this.#virtual_geometry;
         }
 
+        const { residency = new VGeoResidencyOptions(), ...rest } = options;
+
         const pool = new GPUVirtualGeometryPool({
             device: this.#device,
             meshlets: this.geometries.meshlets,
-            ...options,
+            ...rest,
         });
 
         this.#virtual_geometry = new GPUVirtualGeometryRuntime({
             pool,
-            device: this.#device,
-            ...options,
+            ...rest,
+        });
+
+        // pages are fetched, verified and decoded on workers, spawned on first use; a host with no
+        // Worker gets the same fetch in-process
+        const fetcher = new VGeoPageFetcher({
+            worker_count: residency.worker_count,
+            make_worker: typeof Worker === 'undefined' ? undefined : make_vgeo_page_worker,
+        });
+
+        this.#virtual_geometry_residency = new VGeoResidency({ pool, options: residency, fetcher });
+
+        this.#virtual_geometry_feedback = new VGeoFeedbackLoop({
+            runtime: this.#virtual_geometry,
+            residency: this.#virtual_geometry_residency,
         });
 
         return this.#virtual_geometry;

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AAsIA;IAoBI;;OAEG;IACH;cAFoB,MAAM;cAAQ,UAAU;MAI3C;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,SACN,UAAU,GAAC,MAAM,GAEf,IAAI,CA6ChB;IAED;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,sBAHW,MAAM,GACJ,OAAO,CAInB;IAED,+FAYC;IAED;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACW,KAAK,GAAtB,MAAM;QACJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAiBpC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAwGpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAHW,YAAY,GACV,OAAO,CA0CnB;;CACJ;;eAKS,SAAS,2BAA2B,CAAC;;2BA/jBlC,OAAO,yCAAyC,EAAE,YAAY;qCAC9D,OAAO,2CAA2C,EAAE,sBAAsB;yBAC1E,OAAO,uBAAuB,EAAE,UAAU;8CALT,oCAAoC;yCAXzC,0DAA0D;0BAIzE,0BAA0B"}
+{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AAuIA;IAoBI;;OAEG;IACH;cAFoB,MAAM;cAAQ,UAAU;MAI3C;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,SACN,UAAU,GAAC,MAAM,GAEf,IAAI,CAoDhB;IAED;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,sBAHW,MAAM,GACJ,OAAO,CAInB;IAED,+FAYC;IAED;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACW,KAAK,GAAtB,MAAM;QACJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAiBpC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAwGpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAHW,YAAY,GACV,OAAO,CAwFnB;;CACJ;;eA2BS,SAAS,2BAA2B,CAAC;;2BA1oBlC,OAAO,yCAAyC,EAAE,YAAY;qCAC9D,OAAO,2CAA2C,EAAE,sBAAsB;yBAC1E,OAAO,uBAAuB,EAAE,UAAU;8CALT,oCAAoC;yCAZzC,0DAA0D;0BAIzE,0BAA0B"}

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js

@@ -11,6 +11,7 @@ import { CodeChunk } from "../compiler/CodeChunk.js";
 import { parse_wgsl_type } from "../type/parse_wgsl_type.js";
 import { type_has_arrays } from "../type/type_has_arrays.js";
 import { type_has_atomics } from "../type/type_has_atomics.js";
+import { WebGPUStruct } from "../type/WebGPUStruct.js";
 import { write_wgsl_type_value } from "../type/serde/write_gpu_typed_buffer.js";
 import { IMMEDIATE_ADDRESS_SPACE_EXTENSION, IMMEDIATE_SIZE_FLOOR } from "./IMMEDIATE_DATA.js";
 import { ResourceType } from "./ResourceType.js";
@@ -226,7 +227,14 @@ export class ShaderResourceSetDescriptor {
             );
         }
 
-        this.#immediate = { name, type };
+        // The top-level member names, kept so that `writeImmediate` can tell a value of this type
+        // from something that merely happens to be an object. `undefined` for a scalar, vector or
+        // matrix immediate, which has no members to name.
+        const field_names = type instanceof WebGPUStruct
+            ? type.fields.map(field => field.name)
+            : undefined;
+
+        this.#immediate = { name, type, field_names };
 
         return this;
     }
@@ -561,27 +569,73 @@ export class ShaderResourceSetDescriptor {
             );
         }
 
+        // Refuse a value of the wrong shape rather than serialise what it does not contain.
+        //
+        // The whole declared range travels every dispatch, and the zeroes this method clears it to are
+        // indistinguishable from deliberate ones: every slot ends up *set*, so WebGPU's immediate
+        // validation — and the software device's copy of it — has nothing to report. A wrong-shaped
+        // value therefore reaches the shader as zeroes, silently, and the only symptom is wrong
+        // output. That is what a call site left behind by the uniform -> immediate migration does: it
+        // keeps handing over the transient GPUBuffer the uniform needed, `generateBindings` ignores
+        // the extra key so the buffer is never bound, and nothing on a GPUBuffer matches the type.
+        //
+        // A value that names *some* of the members is left alone. Structs carry explicit padding
+        // members the CPU side has no value for, and skipping absent fields is load-bearing anyway
+        // (GPUTypedTable#set_range writes one member of a record through the same serialiser). Only a
+        // value that could not have populated the type at all is an unambiguous mistake.
+        const field_names = immediate.field_names;
+
+        if (field_names === undefined) {
+            // Scalar, vector or matrix: the serialiser reads the value as a number or indexes it.
+            const usable = typeof value === "number"
+                || typeof value === "boolean"
+                || typeof value[0] === "number";
+
+            if (!usable) {
+                throw new Error(
+                    `Immediate data '${immediate.name}' of type '${immediate.type}' was given a value the`
+                    + ` serialiser cannot read as a number: '${value}'. An immediate takes the plain value,`
+                    + ` not something bindable — a GPUBuffer is what a *uniform* binding wants, and one`
+                    + ` passed here is ignored by generateBindings and would serialise as zeroes.`
+                );
+            }
+        } else if (!value_names_a_member(value, field_names)) {
+            // Note: no `${immediate.type}` in the message. Interpolating a struct type runs its whole
+            // WGSL declaration through the code generator, and the member list is the actionable half
+            // of that anyway.
+            throw new Error(
+                `Immediate data '${immediate.name}' was given a value naming none of its members`
+                + ` (${field_names.join(', ')}), so the dispatch would have read zeroes. An immediate`
+                + ` takes the plain value — '{ ${field_names[0]}: ... }' — not`
+                + ` something bindable: a GPUBuffer is what a *uniform* binding wants, and one passed`
+                + ` here is ignored by generateBindings and serialises to nothing.`
+            );
+        }
+
         const start = buffer.position;
         const size = this.immediateSize;
 
         buffer.ensureCapacity(start + size);
 
-        write_wgsl_type_value(value, buffer, immediate.type);
-
-        // Zero-fill out to the declared size rather than stopping where the last member ended.
+        // Clear the whole declared range up front, rather than filling in from wherever the
+        // serialiser's cursor stopped.
         //
-        // The serialiser stops after the final member, so a struct with trailing padding — say
-        // `{vec4f, u32}`, 20 bytes written of a 32-byte type — leaves a tail. That tail is padding,
-        // WebGPU's AccessibleSlots excludes padding, and a short write would in fact validate. It
-        // would also mean the bytes handed to `setImmediates` are shorter than the `immediateSize`
-        // the pipeline layout declares, which is true-but-subtle in a way that only holds as long as
-        // nobody changes how either number is derived. Writing the full declared size costs at most
-        // 64 bytes of memset and makes the two trivially equal.
-        const written = buffer.position - start;
-
-        for (let i = written; i < size; i++) {
-            buffer.raw_bytes[start + i] = 0;
-        }
+        // Two reasons, and the second is the one that bites. The first: the serialiser stops after the
+        // final member, so a struct with trailing padding — say `{vec4f, u32}`, 20 bytes written of a
+        // 32-byte type — leaves a tail. That tail is padding, WebGPU's AccessibleSlots excludes
+        // padding, and a short write would in fact validate; it would also make the bytes handed to
+        // `setImmediates` shorter than the `immediateSize` the pipeline layout declares, true-but-subtle
+        // in a way that only holds as long as nobody changes how either number is derived.
+        //
+        // The second: this buffer is one scratch region reused by every dispatch of a context, and it
+        // is only ever written over, never cleared. A member the value did not name is skipped, and a
+        // skipped member before the final one is not in the tail — filling from the cursor left it
+        // holding the bytes the *previous* dispatch put at that offset. A partial value is legal (see
+        // above), so that made one dispatch's immediate data a function of the one before it. Clearing
+        // first closes the holes and the tail together, and costs at most 64 bytes of memset.
+        buffer.raw_bytes.fill(0, start, start + size);
+
+        write_wgsl_type_value(value, buffer, immediate.type);
 
         buffer.position = start + size;
 
@@ -589,6 +643,28 @@ export class ShaderResourceSetDescriptor {
     }
 }
 
+/**
+ * Whether `value` carries at least one of `field_names`.
+ *
+ * A plain loop, and a free function rather than a closure over `value`, because
+ * {@link ShaderResourceSetDescriptor#writeImmediate} runs once per dispatch and allocates nothing.
+ *
+ * @param {Object} value
+ * @param {string[]} field_names
+ * @returns {boolean}
+ */
+function value_names_a_member(value, field_names) {
+    const count = field_names.length;
+
+    for (let i = 0; i < count; i++) {
+        if (value[field_names[i]] !== undefined) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 /**
  * Special immutable empty set
  * @readonly

package/src/shade/renderer/view/GPUViewContext.d.ts

@@ -90,6 +90,10 @@ export class GPUViewContext {
      * @returns {GPUCameraContext}
      */
     get gpu_previous_camera_state(): GPUCameraContext;
+    /**
+     * @return {VGeoViewCut}
+     */
+    get virtual_geometry_cut(): VGeoViewCut;
     /**
      *
      * @return {GPUCameraContext}
@@ -136,4 +140,5 @@ import { HierarchicalZBuffer } from "../hiz/HierarchicalZBuffer.js";
 import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
 import { GPUViewVolumetrics } from "../volumetrics/GPUViewVolumetrics.js";
 import { GPUCameraContext } from "../camera/GPUCameraContext.js";
+import { VGeoViewCut } from "../geometry/virtual/runtime/VGeoViewCut.js";
 //# sourceMappingURL=GPUViewContext.d.ts.map

package/src/shade/renderer/view/GPUViewContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUViewContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/GPUViewContext.js"],"names":[],"mappings":";;;;;;;;AA+BA;;GAEG;AACH;IAiOI;;;;;OAKG;IACH,sBAJW,eAAe,SACf,eAAe,UACf,gBAAgB,EAuB1B;IA1PD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAuBX;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;OAIG;IACH,aAHW,MAAM,KACN,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,KACN,MAAM,QAOhB;IAED,wEAAwE;IACxE,2BAAqC;IAErC,6BAA6B;IAC7B,8BAEC;IAQD;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAUhB;IAgBD;;;OAGG;IACH,kDAEC;IAdD;;;OAGG;IACH,iDAEC;IAgBD;;;OAGG;IACH,qCAEC;IAQD;;;OAGG;IACH,sCAEC;IA4BD;;;OAGG;IACH,mDAEC;IAdD;;;OAGG;IACH,kDAEC;IAgBD;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,mEAEC;IA+BD;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED,wBA6BC;IAGD;;;OAGG;IACH,YAFW,eAAe,QAWzB;IAED;;OAEG;IACH,0BAFW,sBAAsB,QAShC;IAED,gBAgBC;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;;CANxC;qCAtXY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;oCAP9B,+BAA+B;+BAFpC,6BAA6B;mCAGzB,sCAAsC;iCAFxC,+BAA+B"}
+{"version":3,"file":"GPUViewContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/GPUViewContext.js"],"names":[],"mappings":";;;;;;;;AAgCA;;GAEG;AACH;IAiPI;;;;;OAKG;IACH,sBAJW,eAAe,SACf,eAAe,UACf,gBAAgB,EAyB1B;IA5QD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAuBX;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;OAIG;IACH,aAHW,MAAM,KACN,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,KACN,MAAM,QAOhB;IAED,wEAAwE;IACxE,2BAAqC;IAErC,6BAA6B;IAC7B,8BAEC;IAQD;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAUhB;IAgBD;;;OAGG;IACH,kDAEC;IAdD;;;OAGG;IACH,iDAEC;IAgBD;;;OAGG;IACH,qCAEC;IAQD;;;OAGG;IACH,sCAEC;IA4BD;;;OAGG;IACH,mDAEC;IAdD;;;OAGG;IACH,kDAEC;IAyBD;;OAEG;IACH,wCAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,mEAEC;IAiCD;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED,wBA6BC;IAGD;;;OAGG;IACH,YAFW,eAAe,QAWzB;IAED;;OAEG;IACH,0BAFW,sBAAsB,QAShC;IAED,gBAkBC;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;;CANxC;qCA1YY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;oCAP9B,+BAA+B;+BAHpC,6BAA6B;mCAIzB,sCAAsC;iCAHxC,+BAA+B;4BACpC,4CAA4C"}