@woosh/meep-engine 3.11.1 → 3.11.3

package/src/shade/renderer/volumetrics/shader_volumetrics_build_lighting.js

@@ -34,12 +34,35 @@ import { chunk_calculate_multiscattering } from "./chunk_calculate_multiscatteri
 import { chunk_camera_ray_planar_depth_scale } from "./chunk_camera_ray_planar_depth_scale.js";
 import { chunk_volumetrics_froxel_content_offset } from "./chunk_volumetrics_froxel_content_offset.js";
 import { chunk_integrate_optical_depth } from "./chunk_integrate_optical_depth.js";
+import {
+    chunk_volumetrics_sun_optical_depth,
+    volumetrics_sun_shadow_texture_name
+} from "./chunk_volumetrics_sun_optical_depth.js";
+import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
 import { chunk_volumetrics_column_jitter } from "./chunk_volumetrics_column_jitter.js";
+import { chunk_volumetrics_local_light_shadow } from "./chunk_volumetrics_local_light_shadow.js";
 import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
 
+/**
+ * Workgroup shape of this pass, `[x, y, z]` in froxels, read by both the `@workgroup_size` below
+ * and the dispatch in `graph_build_volumetrics` so the two cannot drift.
+ *
+ * Flat in z. Lights are binned into 3D clusters and the largest distance between neighbouring
+ * clusters is along depth, so a group spanning z is the one spanning the most unrelated light
+ * lists.
+ *
+ * 64 invocations — one wave64, two warps — is a deliberate trade: 16x16x1 measures faster on the
+ * RTX 4090 this was benchmarked on, and is kept off because that part's register file is unusually
+ * large and the result is not expected to generalize (AMD favours smaller groups). NOTES.md carries
+ * the numbers and the reasoning.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION = [8, 8, 1];
+
 const resources = new ShaderResourceSetDescriptor();
 
-resources.createGroup()
+const primary_group = resources.createGroup()
     .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)
     .addUniform("view", VIEW_UNIFORM_STRUCT)
@@ -48,8 +71,16 @@ resources.createGroup()
     .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
     .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
     .addTexture("tParticipatingMedia0", "float", "3d")
-    .addTexture("tParticipatingMedia1", "float", "3d")
-    .addStorageTexture("tLighting", "rgba16float", "3d", "write-only")
+    .addTexture("tParticipatingMedia1", "float", "3d");
+
+// Q-04: the sun's optical depth, pre-integrated along the light axis by
+// shader_volumetrics_build_sun_shadow_volume, one cascade per texture and innermost first.
+// Sampled, not marched.
+for (let cascade = 0; cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT; cascade++) {
+    primary_group.addTexture(volumetrics_sun_shadow_texture_name(cascade), "float", "3d");
+}
+
+primary_group.addStorageTexture("tLighting", "rgba16float", "3d", "write-only")
 
 // Lighting information
 resources.createGroup()
@@ -66,7 +97,7 @@ resources.createGroup()
 const body = CodeChunk.from(
     //language=WGSL
     `
-@compute @workgroup_size(16,16)
+@compute @workgroup_size(${VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION.join(",")})
 fn main(
     @builtin(global_invocation_id) voxel_coord : vec3<u32>
 ){
@@ -199,7 +230,7 @@ fn main(
 
             let sun = get_directional_light_info_by_index(&light_data, directional_index);
 
-            let sun_lut_uv = sky_lut_compute_uv(position_ws, sun.direction);
+            let sun_lut_uv = sky_lut_compute_uv(position_ws, sun.direction, vec2<f32>(textureDimensions(tSunTransmittance)));
 
             let shadow_term = shadowmap_get_directional_light_visibility(
                 &light_data,
@@ -222,14 +253,37 @@ fn main(
                 sun_lut_uv, 0.0
             ).rgb;
 
-            // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
-            let shadow_ray = ${RAY_STRUCT.make({
-                origin: "position_ws",
-                direction: "sun.direction",
-                tmax: "sun.distance",
-            })};
-
-            let optical_depth = integrate_optical_depth(shadow_ray);
+            // Q-04. Every froxel on this sun ray is asking for the same integral, one increment
+            // apart, and the march recomputes all of it from scratch for each: O(froxels * steps)
+            // to produce O(froxels) of information. The sun is where that is worst, because its
+            // tmax is the distance to the sun clipped to the frustum, so the march spans the whole
+            // grid rather than the few metres a lamp's does.
+            //
+            // So read the answer out of the cascades built once this frame with their axis on the
+            // sun, where the increment relation IS the storage — see
+            // shader_volumetrics_build_sun_shadow_volume. Same quantity, same units, one fetch.
+            //
+            // The march below is not an alternative to it, it is what is left for the lights the
+            // cascades do not cover: a second directional light, since there is one ladder and it
+            // is aligned to one direction, and the two cases that cannot place a box at all, which
+            // sun_shadow_light_index reports by holding a value no light index can equal.
+            var optical_depth: vec3<f32>;
+
+            if (directional_index == volumetrics_metadata.sun_shadow_light_index) {
+
+                optical_depth = volumetrics_sun_optical_depth(position_ws);
+
+            } else {
+
+                // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
+                let shadow_ray = ${RAY_STRUCT.make({
+                    origin: "position_ws",
+                    direction: "sun.direction",
+                    tmax: "sun.distance",
+                })};
+
+                optical_depth = integrate_optical_depth(shadow_ray);
+            }
 
             let ms = calculate_multiscattering(
                 optical_depth,
@@ -284,7 +338,16 @@ fn main(
                 volumetrics_metadata.ms_extinction_decay
             );
 
-            inScatteringSum += ms * direct_light.color;
+            // Before this, integrate_optical_depth was the ONLY thing occluding a local light:
+            // the medium shadowed itself and geometry did not shadow it at all, so a torch behind a
+            // wall lit the fog through the wall and a light through a window cast no shaft. The
+            // directional loop above has always multiplied its shadow map in; this is the same
+            // operation for the clustered lights, which is what Frostbite and UE both do in the
+            // froxel pass. One nearest atlas tap rather than the deferred path's filter kernel —
+            // see the chunk for why that is not a compromise here.
+            let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
+
+            inScatteringSum += shadow_term * ms * direct_light.color;
         }
 
         for (var k = 0u; k < spot_count; k++) {
@@ -316,7 +379,10 @@ fn main(
                 volumetrics_metadata.ms_extinction_decay
             );
 
-            inScatteringSum += ms * direct_light.color;
+            // see the point loop above
+            let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
+
+            inScatteringSum += shadow_term * ms * direct_light.color;
         }
     }
 
@@ -350,10 +416,12 @@ fn main(
         chunk_get_point_light_info_by_index,
         chunk_get_spot_light_info_by_index,
         chunk_shadowmap_get_light_visibility,
+        chunk_volumetrics_local_light_shadow,
         chunk_sky_lut_compute_uv,
 
         RAY_STRUCT.declaration_chunk,
         chunk_integrate_optical_depth,
+        chunk_volumetrics_sun_optical_depth,
         chunk_calculate_multiscattering,
         chunk_rgb_to_luminance,
         chunk_volumetrics_column_jitter,

package/src/shade/renderer/volumetrics/shader_volumetrics_build_participating_media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_build_participating_media.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_participating_media.js"],"names":[],"mappings":"AA2LA,yEAIE;8BA5K4B,4BAA4B"}
+{"version":3,"file":"shader_volumetrics_build_participating_media.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_participating_media.js"],"names":[],"mappings":"AAsMA,yEAIE;8BArL4B,4BAA4B"}

package/src/shade/renderer/volumetrics/shader_volumetrics_build_participating_media.js

@@ -12,7 +12,9 @@ import { chunk_rgb_to_luminance } from "../shader/chunk/color/chunk_rgb_to_lumin
 import { AABB3_STRUCT } from "../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
 import { chunk_aabb3_intersects_frustum } from "../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
 import { chunk_frustum_slice } from "../shader/chunk/geometry/frustum/chunk_frustum_slice.js";
-import { chunk_frustum_transform_m4 } from "../shader/chunk/geometry/frustum/chunk_frustum_transform_m4.js";
+import {
+    chunk_frustum_transform_plane_matrix
+} from "../shader/chunk/geometry/frustum/chunk_frustum_transform_plane_matrix.js";
 import { chunk_mat4_extract_scale } from "../shader/chunk/geometry/mat4/chunk_mat4_extract_scale.js";
 import { chunk_random } from "../shader/chunk/random/chunk_random.js";
 import { chunk_random_initialize } from "../shader/chunk/random/chunk_random_initialize.js";
@@ -101,44 +103,53 @@ fn main(
     var particle_diameter = 0.0;
     var scattering_luma_sum = 0.0;
     var anisotropic_g = 0.0;
-            
+
     for(var i=0u; i < scene_volumetrics_metadata.instance_count; i++){
-        
+
         let volume = scene_volumes[i];
-        
-        // transform froxel into volume's coordinate space
-        let local_frustum = frustum_transform_m4(froxel_frustum, volume.transform_inverse);
-                
+
+        // Transform froxel into volume's coordinate space. Points go world -> local through
+        // transform_inverse, so planes go by the transpose of *its* inverse, which is just
+        // transpose(transform) — already resident, where deriving it costs a generic 4x4 inverse.
+        // Full 4x4 rather than a 3x3 basis: the last row carries the translation, and that is what
+        // supplies each transformed plane's distance term.
+        let local_frustum = frustum_transform_plane_matrix(froxel_frustum, transpose(volume.transform));
+
         const unit_bounds = ${AABB3_STRUCT.make({
             min: "vec3(-0.5)",
             max: "vec3(0.5)",
         })};
-        
-        // TODO we can check intersection degree, if froxel is 100% inside the volume - we can skip costly coverage computation.
-        
+
         let aabb_intersects = aabb3_intersects_frustum(unit_bounds, local_frustum);
-        
+
         if(!aabb_intersects){
              // skip
              continue;
         }
-        
+
+        // A froxel proved to lie entirely inside the volume has a coverage of exactly 1.0 and, deep
+        // enough in, a fade of exactly 1.0 — both skippable. It is not done here because it does not
+        // pay: proving it needs the froxel's 8 vertices, which cost the same 8 three-plane
+        // intersections the coverage estimator spends, and only 7 to 33 percent of froxels qualify.
+        // NOTES.md has the measured hit rates and the arithmetic, and
+        // volumetrics_froxel_containment.spec.js keeps the geometry proven if the balance changes.
+
         // estimate volume coverage to avoid aliasing and get a better overlap test
         var volume_coverage = frustum_unit_box_coverage(local_frustum);
-                        
+
         if(volume_coverage == 0.0){
             // skip
             continue;
         }
-        
+
         let world_scale = mat4_extract_scale(volume.transform);
-        
+
         let edge_fade_factor = compute_volume_fade_factor(
             local_frustum,
             world_scale,
-            volume.fade_distance    
+            volume.fade_distance
         );
-                        
+
         let weight = volume.density * volume_coverage * edge_fade_factor;
         
         let volume_scattering = volume.particle_spec.scattering * weight;
@@ -172,7 +183,7 @@ fn main(
         chunk_density_mie,
         chunk_cluster_depth_from_z_slice,
         chunk_frustum_slice,
-        chunk_frustum_transform_m4,
+        chunk_frustum_transform_plane_matrix,
         chunk_aabb3_intersects_frustum,
         chunk_compute_near_far_from_projection,
         chunk_random_initialize,