@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/shadow/sdf/chunk_geometry_sdf_query_distance.js

@@ -1,54 +1,26 @@
-import { chunk_aabb3_distance_to_ray_v2 } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_distance_to_ray_v2.js";
-import {
-    chunk_aabb3_nearest_point_on_surface
-} from "../../shader/chunk/geometry/aabb3/chunk_aabb3_nearest_point_on_surface.js";
-import { chunk_array_to_aabb3 } from "../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
-import { chunk_sign_not_zero } from "../../shader/chunk/math/chunk_sign_not_zero.js";
-import {
-    chunk_sdf_texture_region_sample_linear_uv
-} from "../../shader/chunk/sdf/chunk_sdf_texture_region_sample_linear_uv.js";
+import { chunk_mesh_sdf_header, chunk_mesh_sdf_sample } from "../../geometry/sdf/chunk_mesh_sdf_sample.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { chunk_tile_atlas_slot_origin } from "../../texture/atlas/chunk_tile_atlas_slot_origin.js";
 
 
+/**
+ * The signed distance a geometry's sparse field gives at a point of its local space, at level 0: past
+ * the grid box, a lower bound (see `mesh_sdf_sample`). A skinned clone reads its source's field.
+ *
+ * Reads `mesh_sdf_headers`, `mesh_sdf_indirection`, `mesh_sdf_atlas` and `mesh_sdf_sampler`.
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_geometry_sdf_query_distance = CodeChunk.from(
     //language=WGSL
     `
-fn geometry_sdf_query_distance( geometry_id:u32, position_local: vec3<f32>) -> f32{
-
-        let geometry = geometries[geometry_id];
-        
-        var geometry_bounds = array_to_aabb3(geometry.bounding_box);
-                    
-        let geometry_bounds_span = geometry_bounds.max - geometry_bounds.min;
-        
-        // normalize position
-        
-        var sdf_uv = (position_local - geometry_bounds.min) / (geometry_bounds_span);
-        
-       
-        var uv_distance_to_box = vec3(0.0);
-        
-        let clamped = saturate(sdf_uv);
-        uv_distance_to_box = sdf_uv - clamped;
-        
-        sdf_uv = clamped;
-        
-        let offset = tile_atlas_slot_origin(geometry_id, settings.sdf_atlas_resolution.xy, vec3(settings.sdf_tile_resolution));
-        let geometry_distance = sdf_texture_region_sample_linear_uv(texture_sdf,  offset,  vec3(settings.sdf_tile_resolution), sdf_uv);
-                
-        return geometry_distance + sign_not_zero(geometry_distance) * length(geometry_bounds_span * uv_distance_to_box);
+fn geometry_sdf_query_distance(geometry_id: u32, position_local: vec3<f32>) -> f32 {
+    return mesh_sdf_sample(mesh_sdf_header(geometry_id), 0u, position_local);
 }
 `, [
-        chunk_array_to_aabb3,
-        chunk_tile_atlas_slot_origin,
-        chunk_sdf_texture_region_sample_linear_uv,
-        chunk_aabb3_nearest_point_on_surface,
-        chunk_aabb3_distance_to_ray_v2,
-        chunk_sign_not_zero
+        chunk_mesh_sdf_header,
+        chunk_mesh_sdf_sample,
     ]);
 
-
 /**
  * This is essentially the same as "normal", but since SDF can be sampled anywhere, this is actually gradient (partial derivative) at the given sample point
  * @see https://iquilezles.org/articles/normalsSDF/

package/src/shade/renderer/shadow/sdf/chunk_ray_query_sdf_raycast_traversal_count.js

@@ -13,7 +13,7 @@ import { chunk_ray_transform_m4 } from "../../shader/chunk/geometry/ray/chunk_ra
 import { RAY_STRUCT } from "../../shader/chunk/geometry/ray/RAY_STRUCT.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { chunk_sdf_mesh_raymarch } from "./chunk_sdf_mesh_raymarch.js";
-import { SDF_DRAW_SETTINGS_STRUCT } from "./SDF_DRAW_SETTINGS_STRUCT.js";
+import { MESH_SDF_STRUCT } from "../../geometry/sdf/MESH_SDF_STRUCT.js";
 
 /**
  * Debug tool
@@ -94,9 +94,10 @@ const chunk_shader_debug_traversal = CodeChunk.from(
     //language=WGSL
     `
 
-@group(0) @binding(0) var<uniform> settings: ${SDF_DRAW_SETTINGS_STRUCT.wgsl_ref};
-@group(0) @binding(1) var texture_sdf: texture_3d<f32>;
-@group(0) @binding(2) var texture_sdf_sampler: sampler;
+@group(0) @binding(0) var<storage> mesh_sdf_headers: array<${MESH_SDF_STRUCT.wgsl_ref}>;
+@group(0) @binding(1) var<storage> mesh_sdf_indirection: array<u32>;
+@group(0) @binding(2) var mesh_sdf_atlas: texture_3d<f32>;
+@group(0) @binding(3) var mesh_sdf_sampler: sampler;
 
 
 @group(1) @binding(0) var<storage> geometries:array<${GEOMETRY_METADATA_STRUCT.wgsl_ref}>;
@@ -125,7 +126,7 @@ fn main(
 `, [
             BVH_NULL_NODE_DEFINITION,
         GEOMETRY_METADATA_STRUCT.declaration_chunk,
-        SDF_DRAW_SETTINGS_STRUCT.declaration_chunk,
+        MESH_SDF_STRUCT.declaration_chunk,
         BVH_STRUCT.declaration_chunk,
         chunk_camera_ray_from_uv,
         chunk_sdf_mesh_raymarch,

package/src/shade/renderer/shadow/sdf/chunk_sdf_geometry_raymarch.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Where a ray in a geometry's local space first meets its sparse field at level 0: `vec4(point, 1)`,
+ * or `vec4(0)` for a miss.
+ *
+ * Reads `mesh_sdf_headers`, `mesh_sdf_indirection`, `mesh_sdf_atlas` and `mesh_sdf_sampler`.
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_sdf_geometry_raymarch: CodeChunk;
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_sdf_geometry_raymarch.d.ts.map

package/src/shade/renderer/shadow/sdf/chunk_sdf_geometry_raymarch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sdf_geometry_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_sdf_geometry_raymarch.js"],"names":[],"mappings":"AAYA,oDAwEE;0BA3EwB,oCAAoC"}
+{"version":3,"file":"chunk_sdf_geometry_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_sdf_geometry_raymarch.js"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,0CAFU,SAAS,CAoBjB;0BA5BwB,oCAAoC"}

package/src/shade/renderer/shadow/sdf/chunk_sdf_geometry_raymarch.js

@@ -1,85 +1,32 @@
-import { chunk_array_to_aabb3 } from "../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
-import { chunk_mat4_compose_transform } from "../../shader/chunk/geometry/mat4/chunk_mat4_compose_transform.js";
-import { MAT4_IDENTITY_DEFINITION } from "../../shader/chunk/geometry/mat4/MAT4_IDENTITY_DEFINITION.js";
-import { chunk_ray_transform_m4 } from "../../shader/chunk/geometry/ray/chunk_ray_transform_m4.js";
-import { RAY_HIT_INFO } from "../../shader/chunk/geometry/ray/RAY_HIT_INFO.js";
+import { chunk_mesh_sdf_raymarch } from "../../geometry/sdf/chunk_mesh_sdf_raymarch.js";
+import { chunk_mesh_sdf_header } from "../../geometry/sdf/chunk_mesh_sdf_sample.js";
 import { RAY_STRUCT } from "../../shader/chunk/geometry/ray/RAY_STRUCT.js";
-import { chunk_min_v3 } from "../../shader/chunk/geometry/vec3/chunk_min_v3.js";
-import { chunk_v3_matrix4_project } from "../../shader/chunk/geometry/vec3/chunk_v3_matrix4_project.js";
-import { chunk_sdf_texture_raycast } from "../../shader/chunk/sdf/chunk_sdf_texture_raycast.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { chunk_tile_atlas_slot_origin } from "../../texture/atlas/chunk_tile_atlas_slot_origin.js";
 
+/**
+ * Where a ray in a geometry's local space first meets its sparse field at level 0: `vec4(point, 1)`,
+ * or `vec4(0)` for a miss.
+ *
+ * Reads `mesh_sdf_headers`, `mesh_sdf_indirection`, `mesh_sdf_atlas` and `mesh_sdf_sampler`.
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_sdf_geometry_raymarch = CodeChunk.from(
     //language=WGSL
     `
-fn sdf_geometry_raymarch(ray:${RAY_STRUCT.wgsl_ref}, geometry_index: u32) -> vec4<f32> {
-    let geometry = geometries[geometry_index];
-    
-    let bounds = array_to_aabb3(geometry.bounding_box);
-    
-    let span = bounds.max - bounds.min;
-    let span_rcp = 1 / span;
-    
-    // transform ray to NDC 
-    let sdf_transform = mat4_compose_transform(bounds.min, vec4(0.0, 0.0, 0.0, 1.0), span);
-    let sdf_transform_inverse = mat4_compose_transform(- bounds.min * span_rcp, vec4(0.0, 0.0, 0.0, 1.0), span_rcp);
-    
-    var sdf_ray = ray_transform_m4(ray, sdf_transform_inverse);
-    
-    let offset = tile_atlas_slot_origin(geometry_index, settings.sdf_atlas_resolution.xy, vec3(settings.sdf_tile_resolution));
-        
-    const tolerance = 0.001;
-        
-    let ndc_ray_t = sdf_texture_raycast(sdf_ray, texture_sdf, offset, vec3(settings.sdf_tile_resolution), tolerance);
-    
-    const MAX_MARCHING_STEPS = 256;
-    
-    let box_intersection = aabb3_distance_to_ray(bounds.min, bounds.max, ray.origin, ray.direction);
-    
-    if(box_intersection.y <= 0.0){
-        // no collision with bounding box
-        return vec4(0);
-    }
-    
-    // start marchin from the boundary for faster convergence
-    var t = max(box_intersection.x, 0.0);
-    
-    for (var i = 0; i < MAX_MARCHING_STEPS; i++) {
-        let local_point = ray.origin + t * ray.direction;
-        
-        let uv = v3_matrix4_project( local_point, sdf_transform_inverse );
-        
-        if(any(uv < vec3(0.0)) || any(uv > vec3(1.0))){
-            // walked outside
-            break;
-        }
-        
-        let dist = sdf_texture_region_sample_linear_uv( texture_sdf, offset,  vec3(settings.sdf_tile_resolution), uv );
-        
-        if (dist < tolerance) {
-            // got a hit
-            return vec4(local_point, 1.0);
-        }
-        
-        t += dist;
+fn sdf_geometry_raymarch(ray: ${RAY_STRUCT.wgsl_ref}, geometry_index: u32) -> vec4<f32> {
+    let t = mesh_sdf_raymarch(mesh_sdf_header(geometry_index), 0u, ray);
+
+    if (t < 0.0) {
+        return vec4(0.0);
     }
-    
-    // outside of the limits
-    return vec4(0);
-    
+
+    return vec4(ray.origin + t * ray.direction, 1.0);
 }
     `,
     [
-        MAT4_IDENTITY_DEFINITION,
-        RAY_HIT_INFO.declaration_chunk,
         RAY_STRUCT.declaration_chunk,
-        chunk_tile_atlas_slot_origin,
-        chunk_sdf_texture_raycast,
-        chunk_mat4_compose_transform,
-        chunk_array_to_aabb3,
-        chunk_ray_transform_m4,
-        chunk_v3_matrix4_project,
-        chunk_min_v3,
+        chunk_mesh_sdf_header,
+        chunk_mesh_sdf_raymarch,
     ]
-);
+);

package/src/shade/renderer/shadow/sdf/chunk_sdf_mesh_raymarch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sdf_mesh_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_sdf_mesh_raymarch.js"],"names":[],"mappings":"AAMA,gDA6CE;0BAjDwB,oCAAoC"}
+{"version":3,"file":"chunk_sdf_mesh_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_sdf_mesh_raymarch.js"],"names":[],"mappings":"AAQA,gDA+CE;0BAnDwB,oCAAoC"}

package/src/shade/renderer/shadow/sdf/chunk_sdf_mesh_raymarch.js

@@ -1,3 +1,5 @@
+import { chunk_aabb3_distance_to_ray_v2 } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_distance_to_ray_v2.js";
+import { chunk_array_to_aabb3 } from "../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
 import { chunk_ray_transform_m4 } from "../../shader/chunk/geometry/ray/chunk_ray_transform_m4.js";
 import { RAY_STRUCT } from "../../shader/chunk/geometry/ray/RAY_STRUCT.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
@@ -45,6 +47,8 @@ fn sdf_mesh_raymarch( ray: ${RAY_STRUCT.wgsl_ref}, instance_index: u32) -> f32 {
 }
     `, [
         RAY_STRUCT.declaration_chunk,
+        chunk_array_to_aabb3,
+        chunk_aabb3_distance_to_ray_v2,
         chunk_sdf_geometry_raymarch,
         chunk_ray_transform_m4,
         chunk_mesh_sdf_query_distance

package/src/shade/renderer/shadow/sdf/graph_draw_sdf_shadows.d.ts

@@ -15,4 +15,6 @@ export function graph_draw_sdf_shadows({ graph, view, input_depth, input_normals
     input_normals: number;
     input_viz_mesh: number;
 }): number;
+export const shader_draw_sdf_shadows: ImageShader;
+import { ImageShader } from "../../shader/ImageShader.js";
 //# sourceMappingURL=graph_draw_sdf_shadows.d.ts.map

package/src/shade/renderer/shadow/sdf/graph_draw_sdf_shadows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_draw_sdf_shadows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/graph_draw_sdf_shadows.js"],"names":[],"mappings":"AA4GA;;;;;;;;;GASG;AACH;IAP+B,KAAK;IACD,IAAI;IACZ,WAAW,EAA3B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ,MAAM,CAgGlB"}
+{"version":3,"file":"graph_draw_sdf_shadows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/graph_draw_sdf_shadows.js"],"names":[],"mappings":"AAqHA;;;;;;;;;GASG;AACH;IAP+B,KAAK;IACD,IAAI;IACZ,WAAW,EAA3B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ,MAAM,CA6FlB;AAhHD,kDASG;4BA9FyB,6BAA6B"}

package/src/shade/renderer/shadow/sdf/graph_draw_sdf_shadows.js

@@ -3,6 +3,12 @@ import { current_time_in_seconds } from "../../../../core/time/current_time_in_s
 import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../../geometry/sdf/MESH_SDF_RESOURCES.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
 import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
@@ -24,7 +30,10 @@ const resources = new ShaderResourceSetDescriptor();
 // per-draw, 32 bytes, read-only: immediate data rather than a uniform buffer. camera stays bound.
 resources.setImmediate("settings", SDF_DRAW_SETTINGS_STRUCT);
 resources.createGroup()
-    .addTexture("texture_sdf", "unfilterable-float", "3d")
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
     .addTexture("gBufferDepth")
     .addTexture("gBufferNormals", "uint")
     .addTexture("vizBufferMesh", "uint")
@@ -95,7 +104,7 @@ fn main(
         chunk_sdf_hard_shadow,
     ]);
 
-const shader = new ImageShader({
+export const shader_draw_sdf_shadows = new ImageShader({
     descriptor: ShaderDescriptor.from({
         label: "SDF shadows",
         resources,
@@ -161,16 +170,13 @@ export function graph_draw_sdf_shadows({
         const viz_mesh = resources.get(data.viz_mesh);
 
         const buffer_settings = {
-            sdf_tile_resolution: sdf.tile_resolution,
-            sdf_atlas_resolution: sdf.atlas_resolution_in_tiles,
             slice: pingpong(current_time_in_seconds() / 5, 1),
         };
 
-        shader.draw({
+        shader_draw_sdf_shadows.draw({
             encoder,
-            bindings: {
+            bindings: sdf.write_bindings({
                 settings: buffer_settings,
-                texture_sdf: sdf.texture.obtainView(),
                 gBufferDepth: depth.obtainView(),
                 gBufferNormals: normals.obtainView(),
                 vizBufferMesh: viz_mesh.obtainView(),
@@ -182,7 +188,7 @@ export function graph_draw_sdf_shadows({
                 // debug
                 blas_data: geometries.blas.buffer_data,
                 blas_lookup: geometries.blas.buffer_metadata,
-            },
+            }),
             colorAttachments: [
                 {
                     loadOp: "clear",

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_LOW_LOAD_FACTOR.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default low-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` below
+ * which a virtual shadow map steps an active dynamic LOD bias back down toward zero.
+ *
+ * Must sit below {@link DEFAULT_VSM_MAX_LOAD_FACTOR} by at least a single bias step's 2-D area
+ * change (`4^(-step_up)`) so that coarsening a view settles inside `[low_load_factor, max_load_factor]`
+ * rather than immediately stepping back down and thrashing.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_LOW_LOAD_FACTOR: number;
+//# sourceMappingURL=DEFAULT_VSM_LOW_LOAD_FACTOR.d.ts.map

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_LOW_LOAD_FACTOR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DEFAULT_VSM_LOW_LOAD_FACTOR.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/DEFAULT_VSM_LOW_LOAD_FACTOR.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAEgC"}

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_LOW_LOAD_FACTOR.js

@@ -0,0 +1,11 @@
+/**
+ * Default low-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` below
+ * which a virtual shadow map steps an active dynamic LOD bias back down toward zero.
+ *
+ * Must sit below {@link DEFAULT_VSM_MAX_LOAD_FACTOR} by at least a single bias step's 2-D area
+ * change (`4^(-step_up)`) so that coarsening a view settles inside `[low_load_factor, max_load_factor]`
+ * rather than immediately stepping back down and thrashing.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_LOW_LOAD_FACTOR = 0.60;

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Default ceiling on the dynamic LOD bias a virtual shadow map may add under pool pressure (matches
+ * UE 5.4+'s `MaxResolutionLodBias = 2.0`, up to a 4× linear / 16× area reduction). Setting `0`
+ * disables dynamic resolution throttling.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS: number;
+//# sourceMappingURL=DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.d.ts.map

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,+CAFU,MAAM,CAEkC"}

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.js

@@ -0,0 +1,8 @@
+/**
+ * Default ceiling on the dynamic LOD bias a virtual shadow map may add under pool pressure (matches
+ * UE 5.4+'s `MaxResolutionLodBias = 2.0`, up to a 4× linear / 16× area reduction). Setting `0`
+ * disables dynamic resolution throttling.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS = 2;

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_LOAD_FACTOR.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default high-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above
+ * which a virtual shadow map steps its dynamic LOD bias up to coarsen requested pages and prevent
+ * hard page-pool overflow (matches UE 5.4+'s `MaxPagePoolLoadFactor = 0.85`).
+ *
+ * Paired with {@link DEFAULT_VSM_LOW_LOAD_FACTOR} to form a hysteresis deadband so demand hovering
+ * near capacity does not oscillate between adjacent clipmap levels. Setting `0` disables dynamic
+ * resolution throttling.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_MAX_LOAD_FACTOR: number;
+//# sourceMappingURL=DEFAULT_VSM_MAX_LOAD_FACTOR.d.ts.map

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_LOAD_FACTOR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DEFAULT_VSM_MAX_LOAD_FACTOR.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_LOAD_FACTOR.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,0CAFU,MAAM,CAEgC"}

package/src/shade/renderer/shadow/vsm/DEFAULT_VSM_MAX_LOAD_FACTOR.js

@@ -0,0 +1,12 @@
+/**
+ * Default high-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above
+ * which a virtual shadow map steps its dynamic LOD bias up to coarsen requested pages and prevent
+ * hard page-pool overflow (matches UE 5.4+'s `MaxPagePoolLoadFactor = 0.85`).
+ *
+ * Paired with {@link DEFAULT_VSM_LOW_LOAD_FACTOR} to form a hysteresis deadband so demand hovering
+ * near capacity does not oscillate between adjacent clipmap levels. Setting `0` disables dynamic
+ * resolution throttling.
+ *
+ * @type {number}
+ */
+export const DEFAULT_VSM_MAX_LOAD_FACTOR = 0.85;

package/src/shade/renderer/shadow/vsm/PLAN.md

@@ -153,7 +153,9 @@ is untouched.
 **D6 Movers (GPU, scene-level, once a frame).**
 - The pass runs over every mesh-row slot, including slots in pages since freed. It uses the
   page-iterator dispatch and covers a high-water mark of rows.
-- It keeps a VSM-owned per-row buffer of the "bounds last seen".
+- It keeps a per-row buffer of the "bounds last seen". Since 2026-10-27 the scene owns the pass and
+  the buffer (`GPUSceneContext.graph_movers`, `scene/movers/`), and the maps' stale pass is one
+  reader of its list among others (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md D32).
 - A row is a mover when **any** of these holds:
   1. `global != prev_global` — every rigid change, AABB-invariant rotations included;
   2. its world box, geometry or material differs from the one last seen — appear, remove, mesh or

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts

@@ -42,8 +42,13 @@ export class VSMPageManager {
      * @param {number} options.pool_size texels on the pool's side
      * @param {number} options.request_capacity requests a reading holds at most
      * @param {number} options.protect_frames frames a touched page is safe from eviction for
+     * @param {number} [options.max_load_factor=DEFAULT_VSM_MAX_LOAD_FACTOR] high-watermark pool demand ratio in `[0, 1]`; `0` disables dynamic throttling
+     * @param {number} [options.low_load_factor=DEFAULT_VSM_LOW_LOAD_FACTOR] low-watermark pool demand ratio in `[0, 1]` below which dynamic LOD bias steps back down
+     * @param {number} [options.max_lod_bias=DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS] maximum dynamic LOD bias added under load; `0` disables dynamic throttling
+     * @param {number} [options.lod_bias_step_up=DEFAULT_VSM_LOD_BIAS_STEP_UP] minimum step added when demand exceeds `max_load_factor`
+     * @param {number} [options.lod_bias_step_down=DEFAULT_VSM_LOD_BIAS_STEP_DOWN] step subtracted when demand falls below `low_load_factor`
      */
-    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, }: {
+    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, max_load_factor, low_load_factor, max_lod_bias, lod_bias_step_up, lod_bias_step_down, }: {
         level_count: number;
         pages_per_level: number;
         first_texel_size: number;
@@ -52,6 +57,11 @@ export class VSMPageManager {
         pool_size: number;
         request_capacity: number;
         protect_frames: number;
+        max_load_factor?: number;
+        low_load_factor?: number;
+        max_lod_bias?: number;
+        lod_bias_step_up?: number;
+        lod_bias_step_down?: number;
     });
     /**
      * @type {number}
@@ -106,6 +116,10 @@ export class VSMPageManager {
     stats: {
         /** wants in the latest reading */
         wants: number;
+        /** pool demand ratio in the latest reading: `(wants + requests_dropped) / slots.capacity` */
+        load: number;
+        /** dynamic LOD bias currently added to coarsen requested pages under pool pressure */
+        dynamic_lod_bias: number;
         /** wants the latest {@link select} found with nothing resident to stand in for them */
         uncovered: number;
         /** candidates the latest {@link select} left for later frames, those it found no slot for included */
@@ -126,6 +140,66 @@ export class VSMPageManager {
         invalidations: number;
         re_rendered: number;
     };
+    /**
+     * @param {number} v in `[0, 1]`; `0` disables dynamic throttling
+     */
+    set max_load_factor(v: number);
+    /**
+     * High-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above which
+     * {@link dynamic_lod_bias} steps up to coarsen requested pages (UE 5.4+ `MaxPagePoolLoadFactor`).
+     * `0` disables dynamic resolution throttling.
+     * @returns {number}
+     */
+    get max_load_factor(): number;
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set low_load_factor(v: number);
+    /**
+     * Low-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` below which
+     * an active {@link dynamic_lod_bias} steps back down toward zero.
+     * @returns {number}
+     */
+    get low_load_factor(): number;
+    /**
+     * @param {number} v non-negative; `0` disables dynamic throttling
+     */
+    set max_lod_bias(v: number);
+    /**
+     * Ceiling on {@link dynamic_lod_bias} (UE 5.4+ `MaxResolutionLodBias`). `0` disables dynamic
+     * resolution throttling.
+     * @returns {number}
+     */
+    get max_lod_bias(): number;
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_up(v: number);
+    /**
+     * Minimum LOD bias step added when pool demand exceeds {@link max_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_up(): number;
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_down(v: number);
+    /**
+     * LOD bias step subtracted when pool demand falls below {@link low_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_down(): number;
+    /**
+     * Pool demand ratio from the latest applied reading: `(wants + requests_dropped) / slots.capacity`.
+     * @returns {number}
+     */
+    get load(): number;
+    /**
+     * Dynamic LOD bias in `[0, max_lod_bias]` added on top of the user LOD bias to keep pool
+     * demand within capacity.
+     * @returns {number}
+     */
+    get dynamic_lod_bias(): number;
     /**
      * Cells of every level: the length of the page table.
      * @returns {number}
@@ -194,6 +268,11 @@ export class VSMPageManager {
      * @returns {boolean} whether the pages were invalidated
      */
     set_light_space(view: ArrayLike<number>, near: number, far: number, frame: number): boolean;
+    /**
+     * Give back every resident page: what a light-space change does, and what the shadow context
+     * does when the atlas the pool lives in is replaced by a larger one, whose texels hold nothing.
+     */
+    evict_all(): void;
     /**
      * Take a frame's feedback: the pages wanted, which become the want set, and the slots a mover
      * crossed. A reading recorded under a light space that has since been replaced has its wants

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VSMPageManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMPageManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"VSMPageManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMPageManager.js"],"names":[],"mappings":"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"}