Add bounded local virtual shadows

Author: proggeramlug

examples/quality-stress/main.ts

@@ -12,7 +12,7 @@ import {
   genMeshCube, setAmbientLight, setDirectionalLight,
 } from "bloom/models";
 import {
-  enableShadows, addPointLight, createSceneNode, attachModelToNode,
+  enableShadows, addPointLight, addShadowedPointLight, createSceneNode, attachModelToNode,
   setSceneNodeTransform, setSceneNodeColor, setSceneNodePbr,
   setSceneNodeCastShadow, setSceneNodeReceiveShadow,
 } from "bloom/scene";
@@ -21,14 +21,19 @@ import { mat4Identity, mat4Translate, mat4Scale } from "bloom/math";
 const argv: string[] = getCommandLineArgs();
 const config = parseQualityRun(argv);
 let vsmGpuCasterFixture = false;
+let vsmLocalLightsFixture = false;
+let vsmLocalReferenceFixture = false;
 for (let i = 0; i < argv.length; i = i + 1) {
   if (argv[i] === "--vsm-gpu-casters") vsmGpuCasterFixture = true;
+  if (argv[i] === "--vsm-local-lights") vsmLocalLightsFixture = true;
+  if (argv[i] === "--vsm-local-reference") vsmLocalReferenceFixture = true;
 }
 
-const GRID_X = vsmGpuCasterFixture ? 32 : 128;
-const GRID_Z = vsmGpuCasterFixture ? 16 : 80;
+const localLightLayout = vsmLocalLightsFixture || vsmLocalReferenceFixture;
+const GRID_X = localLightLayout ? 16 : (vsmGpuCasterFixture ? 32 : 128);
+const GRID_Z = localLightLayout ? 16 : (vsmGpuCasterFixture ? 16 : 80);
 const DRAW_COUNT = GRID_X * GRID_Z;
-const LIGHT_COUNT = 192;
+const LIGHT_COUNT = localLightLayout ? 128 : 192;
 
 initWindow(1280, 720, "Bloom Quality: 10k Draws + Many Lights", 0);
 if (config !== null) resize(1280, 720, 1280, 720);
@@ -42,6 +47,18 @@ enableShadows();
 const quality: QualityRun | null = config !== null ? new QualityRun(config) : null;
 
 const cube = genMeshCube(1, 1, 1);
+if (localLightLayout) {
+  const floor = createSceneNode();
+  attachModelToNode(floor, cube.handle, 0);
+  let floorTransform = mat4Identity();
+  floorTransform = mat4Translate(floorTransform, { x: 0, y: -0.15, z: 0 });
+  floorTransform = mat4Scale(floorTransform, { x: 14, y: 0.2, z: 10 });
+  setSceneNodeTransform(floor, floorTransform);
+  setSceneNodeColor(floor, 125, 130, 138);
+  setSceneNodePbr(floor, 0.72, 0.0);
+  setSceneNodeCastShadow(floor, false);
+  setSceneNodeReceiveShadow(floor, true);
+}
 for (let i = 0; i < DRAW_COUNT; i = i + 1) {
   const xIndex = i % GRID_X;
   const zIndex = Math.floor(i / GRID_X);
@@ -63,7 +80,7 @@ for (let i = 0; i < DRAW_COUNT; i = i + 1) {
   setSceneNodePbr(node, 0.22 + (xIndex % 6) * 0.12, (zIndex % 9 === 0) ? 0.8 : 0.05);
   // The ordinary 10k case stays focused on main-view submission. The opt-in
   // 512-node VSM oracle stays below the per-page compatibility cap.
-  setSceneNodeCastShadow(node, vsmGpuCasterFixture);
+  setSceneNodeCastShadow(node, vsmGpuCasterFixture || localLightLayout);
   setSceneNodeReceiveShadow(node, true);
 }
 
@@ -72,31 +89,50 @@ while (!windowShouldClose()) {
   const capture = quality !== null ? quality.beginFrame() : false;
   fixtureFrame = fixtureFrame + 1;
   beginDrawing();
-  setAmbientLight({ r: 105, g: 115, b: 135, a: 255 }, 0.25);
+  setAmbientLight(
+    { r: 105, g: 115, b: 135, a: 255 },
+    localLightLayout ? 0.08 : 0.25,
+  );
   setDirectionalLight(
     vsmGpuCasterFixture && Math.floor(fixtureFrame / 30) % 2 !== 0
       ? { x: -0.28, y: 0.90, z: 0.34 }
       : { x: -0.4, y: 0.85, z: 0.3 },
     { r: 255, g: 244, b: 228, a: 255 },
-    1.4,
+    localLightLayout ? 0.15 : 1.4,
   );
   for (let i = 0; i < LIGHT_COUNT; i = i + 1) {
-    const col = i % 24;
-    const row = Math.floor(i / 24);
+    const columns = localLightLayout ? 16 : 24;
+    const col = i % columns;
+    const row = Math.floor(i / columns);
     const hue = i % 3;
-    addPointLight(
-      (col - 11.5) * 3.3,
-      2.0 + (i % 4) * 0.6,
-      (row - 3.5) * 6.0,
-      5.5,
+    const priorityLocalLight = localLightLayout && i < 5;
+    const args = [
+      priorityLocalLight ? 0.0
+        : (localLightLayout ? (col - 7.5) * 1.0 : (col - 11.5) * 3.3),
+      priorityLocalLight ? 6.0 : 2.0 + (i % 4) * 0.6,
+      priorityLocalLight ? 4.0
+        : (localLightLayout ? (row - 3.5) * 1.8 : (row - 3.5) * 6.0),
+      priorityLocalLight ? 15.0 : (localLightLayout ? 4.5 : 5.5),
       hue === 0 ? 1.0 : 0.2,
       hue === 1 ? 1.0 : 0.25,
       hue === 2 ? 1.0 : 0.2,
-      3.0,
-    );
+      priorityLocalLight ? 2.0 : (localLightLayout ? 8.0 : 3.0),
+    ] as const;
+    if (vsmLocalLightsFixture) {
+      if (!addShadowedPointLight(...args) && fixtureFrame === 1) {
+        throw new Error(`shadowed point-light request ${i} was rejected`);
+      }
+    } else if (
+      !vsmLocalReferenceFixture
+      || i < 5
+    ) {
+      addPointLight(...args);
+    }
   }
   beginMode3D({
-    position: { x: 0, y: 38, z: 52 },
+    position: localLightLayout
+      ? { x: 0, y: 9, z: 17 }
+      : { x: 0, y: 38, z: 52 },
     target: { x: 0, y: 0, z: 0 },
     up: { x: 0, y: 1, z: 0 },
     fovy: 58,

native/shared/shaders/virtual_shadows/material_bindings.wgsl

@@ -1,9 +1,13 @@
+struct LocalVsmSamplingSlot {
+    face_vps: array<mat4x4<f32>, 6>,
+    face_pages_0_3: vec4<u32>,
+    face_pages_4_5: vec4<u32>,
+};
 struct DirectionalVsmParams {
     level_vps: array<mat4x4<f32>, 3>,
-    enabled: u32,
-    virtual_pages_per_axis: u32,
-    page_interior: u32,
-    page_border: u32,
+    words: vec4<u32>,
+    local_light_meta: array<vec4<u32>, 256>,
+    local_slots: array<LocalVsmSamplingSlot, 5>,
 };
 @group(1) @binding(10) var vsm_page_table: texture_2d_array<u32>;
 @group(1) @binding(11) var vsm_physical_pages: texture_depth_2d_array;

native/shared/shaders/virtual_shadows/material_helper.wgsl

@@ -2,7 +2,7 @@ fn sample_shadow_cascade(
     cascade_idx: u32,
     world_pos: vec3<f32>,
 ) -> f32 {
-    if (vsm_params.enabled == 0u) {
+    if (vsm_params.words.x == 0u) {
         return sample_shadow_cascade_csm(cascade_idx, world_pos);
     }
     let light_clip = vsm_params.level_vps[cascade_idx]
@@ -17,7 +17,7 @@ fn sample_shadow_cascade(
         1.0 - (light_ndc.y * 0.5 + 0.5),
     );
     let depth_ref = light_ndc.z - 0.001;
-    let axis = vsm_params.virtual_pages_per_axis;
+    let axis = vsm_params.words.y;
     let scaled_uv = shadow_uv * f32(axis);
     let page_xy = min(vec2<u32>(scaled_uv), vec2<u32>(axis - 1u));
     let encoded = textureLoad(
@@ -30,8 +30,8 @@ fn sample_shadow_cascade(
         return sample_shadow_cascade_csm(cascade_idx, world_pos);
     }
     let physical_layer = i32((encoded & 0xffffu) - 1u);
-    let interior = f32(vsm_params.page_interior);
-    let border = f32(vsm_params.page_border);
+    let interior = f32(vsm_params.words.z);
+    let border = f32(vsm_params.words.w);
     let physical_size = interior + 2.0 * border;
     let local_uv = clamp(
         scaled_uv - vec2<f32>(page_xy),

native/shared/shaders/virtual_shadows/scene_bindings.wgsl

@@ -1,9 +1,13 @@
+struct LocalVsmSamplingSlot {
+    face_vps: array<mat4x4<f32>, 6>,
+    face_pages_0_3: vec4<u32>,
+    face_pages_4_5: vec4<u32>,
+};
 struct DirectionalVsmParams {
     level_vps: array<mat4x4<f32>, 3>,
-    enabled: u32,
-    virtual_pages_per_axis: u32,
-    page_interior: u32,
-    page_border: u32,
+    words: vec4<u32>,
+    local_light_meta: array<vec4<u32>, 256>,
+    local_slots: array<LocalVsmSamplingSlot, 5>,
 };
 @group(1) @binding(13) var vsm_page_table: texture_2d_array<u32>;
 @group(1) @binding(14) var vsm_physical_pages: texture_depth_2d_array;

native/shared/shaders/virtual_shadows/scene_helper.wgsl

@@ -4,7 +4,7 @@ fn sample_virtual_shadow(
     csm_uv: vec2<f32>,
     csm_depth_ref: f32,
 ) -> f32 {
-    if (vsm_params.enabled == 0u) {
+    if (vsm_params.words.x == 0u) {
         return sample_cascade(cascade, csm_uv, csm_depth_ref);
     }
     let light_clip = vsm_params.level_vps[cascade] * vec4<f32>(world_pos, 1.0);
@@ -18,7 +18,7 @@ fn sample_virtual_shadow(
         return sample_cascade(cascade, csm_uv, csm_depth_ref);
     }
     let depth_ref = light_ndc.z - 0.001;
-    let axis = vsm_params.virtual_pages_per_axis;
+    let axis = vsm_params.words.y;
     let scaled_uv = shadow_uv * f32(axis);
     let page_xy = min(vec2<u32>(scaled_uv), vec2<u32>(axis - 1u));
     let encoded = textureLoad(
@@ -32,8 +32,8 @@ fn sample_virtual_shadow(
     }
 
     let physical_layer = i32((encoded & 0xffffu) - 1u);
-    let interior = f32(vsm_params.page_interior);
-    let border = f32(vsm_params.page_border);
+    let interior = f32(vsm_params.words.z);
+    let border = f32(vsm_params.words.w);
     let physical_size = interior + 2.0 * border;
     let local_uv = clamp(
         scaled_uv - vec2<f32>(page_xy),
@@ -69,3 +69,79 @@ fn sample_virtual_shadow(
     }
     return virtual_value;
 }
+
+fn local_shadow_face(direction: vec3<f32>) -> u32 {
+    let absolute = abs(direction);
+    if (absolute.x >= absolute.y && absolute.x >= absolute.z) {
+        return select(1u, 0u, direction.x >= 0.0);
+    }
+    if (absolute.y >= absolute.z) {
+        return select(3u, 2u, direction.y >= 0.0);
+    }
+    return select(5u, 4u, direction.z >= 0.0);
+}
+
+fn local_shadow_page(slot: LocalVsmSamplingSlot, face: u32) -> u32 {
+    if (face < 4u) {
+        return slot.face_pages_0_3[face];
+    }
+    return slot.face_pages_4_5[face - 4u];
+}
+
+// Metadata states are deliberately fail-closed:
+//   0 = ordinary point light (unshadowed),
+//   1 = shadow requested but not fully resident (suppress contribution),
+//   2..6 = fully resident local slot + 2.
+fn sample_local_shadow(light_index: u32, world_pos: vec3<f32>) -> f32 {
+    let state = vsm_params.local_light_meta[light_index].x;
+    if (state == 0u) {
+        return 1.0;
+    }
+    if (state == 1u) {
+        return 0.0;
+    }
+    let slot = vsm_params.local_slots[state - 2u];
+    let direction = world_pos - lighting.point_lights[light_index].position.xyz;
+    let face = local_shadow_face(direction);
+    let encoded = local_shadow_page(slot, face);
+    if (encoded == 0u) {
+        return 0.0;
+    }
+    let light_clip = slot.face_vps[face] * vec4<f32>(world_pos, 1.0);
+    let light_ndc = light_clip.xyz / light_clip.w;
+    if (abs(light_ndc.x) > 1.0 || abs(light_ndc.y) > 1.0
+        || light_ndc.z < 0.0 || light_ndc.z > 1.0) {
+        return 0.0;
+    }
+    let shadow_uv = vec2<f32>(
+        light_ndc.x * 0.5 + 0.5,
+        1.0 - (light_ndc.y * 0.5 + 0.5),
+    );
+    let interior = f32(vsm_params.words.z);
+    let border = f32(vsm_params.words.w);
+    let physical_size = interior + 2.0 * border;
+    let page_uv = (vec2<f32>(border) + shadow_uv * interior) / physical_size;
+    let texel = vec2<f32>(1.0 / physical_size);
+    let offsets = array<vec2<f32>, 4>(
+        vec2<f32>(-0.5, -0.5),
+        vec2<f32>( 0.5, -0.5),
+        vec2<f32>(-0.5,  0.5),
+        vec2<f32>( 0.5,  0.5),
+    );
+    let physical_layer = i32((encoded & 0xffffu) - 1u);
+    let depth_bias = max(0.0005, 0.002 * (1.0 - light_ndc.z));
+    var shadow_value = 0.0;
+    for (var tap = 0; tap < 4; tap = tap + 1) {
+        shadow_value += textureSampleCompareLevel(
+            vsm_physical_pages,
+            shadow_samp,
+            page_uv + offsets[tap] * texel,
+            physical_layer,
+            light_ndc.z - depth_bias,
+        );
+    }
+    shadow_value *= 0.25;
+    // New pages fade in from the fail-closed state, never from an
+    // unshadowed local light.
+    return shadow_value * min(f32(encoded >> 16u) / 8.0, 1.0);
+}

native/shared/src/ffi_core/visual.rs

@@ -820,6 +820,32 @@ macro_rules! __bloom_ffi_visual {
             })
         }
 
+        // bloom_add_shadowed_point_light  [issue #132 local VSM]
+        #[no_mangle]
+        pub extern "C" fn bloom_add_shadowed_point_light(
+            x: f64,
+            y: f64,
+            z: f64,
+            range: f64,
+            r: f64,
+            g: f64,
+            b: f64,
+            intensity: f64,
+        ) -> f64 {
+            $crate::ffi::guard("bloom_add_shadowed_point_light", move || {
+                f64::from(engine().renderer.add_shadowed_point_light(
+                    x as f32,
+                    y as f32,
+                    z as f32,
+                    range as f32,
+                    r as f32,
+                    g as f32,
+                    b as f32,
+                    intensity as f32,
+                ))
+            })
+        }
+
         // bloom_set_cursor_shape  [source: macos]
         #[no_mangle]
         pub extern "C" fn bloom_set_cursor_shape(shape: f64) {

native/shared/src/renderer/froxel.rs

@@ -157,7 +157,8 @@ const CLUSTERED_LOOP: &str = "
     let cl_count = cluster_counts[cluster];
     let cl_base = cluster * 256u;
     for (var ci = 0u; ci < cl_count; ci++) {
-        let pl = lighting.point_lights[cluster_indices[cl_base + ci]];
+        let light_index = cluster_indices[cl_base + ci];
+        let pl = lighting.point_lights[light_index];
         let to_light = pl.position.xyz - in.world_pos;
         let dist = length(to_light);
         let range = pl.position.w;
@@ -413,6 +414,21 @@ impl FroxelPass {
 }
 
 impl super::Renderer {
+    /// Replace the already-queued froxel light snapshot after local-shadow
+    /// admission compacts suppressed requests out of the live lighting list.
+    pub(super) fn refresh_froxel_lights(&self) {
+        let Some(froxel) = &self.froxel else { return };
+        let n = (self.lighting_uniforms.point_light_count[0] as u32).min(MAX_LIGHTS_PER_CLUSTER);
+        let count = [n as f32, 0.0, 0.0, 0.0_f32];
+        self.queue
+            .write_buffer(&froxel.lights_buffer, 0, bytemuck::bytes_of(&count));
+        self.queue.write_buffer(
+            &froxel.lights_buffer,
+            16,
+            bytemuck::cast_slice(&self.lighting_uniforms.point_lights),
+        );
+    }
+
     /// Upload froxel params + the compact light list and dispatch the
     /// assignment pass. Runs every 3D frame on supported devices —
     /// even with zero lights, so `cluster_counts` never carries stale
@@ -451,14 +467,7 @@ impl super::Renderer {
         };
         self.queue
             .write_buffer(&froxel.params_buffer, 0, bytemuck::bytes_of(&params));
-        let count = [n as f32, 0.0, 0.0, 0.0_f32];
-        self.queue
-            .write_buffer(&froxel.lights_buffer, 0, bytemuck::bytes_of(&count));
-        self.queue.write_buffer(
-            &froxel.lights_buffer,
-            16,
-            bytemuck::cast_slice(&self.lighting_uniforms.point_lights),
-        );
+        self.refresh_froxel_lights();
         froxel.record(encoder);
     }
 }