@woosh/meep-engine 3.11.1 → 3.11.3

package/src/shade/renderer/volumetrics/ParticipatingMediaVolume.d.ts

@@ -39,6 +39,11 @@ export class VolumetricsParticleSpec {
         radius: any;
         g?: number;
     }): void;
+    /**
+     * @param {VolumetricsParticleSpec} other
+     * @returns {boolean}
+     */
+    equals(other: VolumetricsParticleSpec): boolean;
 }
 export const VOLUMETRIC_PARTICLE_SPEC_FOG: Readonly<VolumetricsParticleSpec>;
 export class ParticipatingMediaVolume {

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

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAIA;IA2DI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,CAAC;QAAC,wBAAwB,CAAC;QAAC,MAAM,CAAC;QAAC,CAAC,CAAA;KAAC,GAC9D,uBAAuB,CAalC;IAED,oDAIC;IAhFD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aAmBC;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEM;IACxB,0BAA4B;IAC5B,uBAAyB;IAEzB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,uBAFU,MAAM,EAAE,CAEgB;IAElC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,mCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,WAFU,SAAS,CAES;;CAE/B;0BAvKyB,4CAA4C"}
+{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAKA;IA6EI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,CAAC;QAAC,wBAAwB,CAAC;QAAC,MAAM,CAAC;QAAC,CAAC,CAAA;KAAC,GAC9D,uBAAuB,CAalC;IAED,oDAIC;IAlGD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aA0BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAOnB;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEM;IACxB,0BAA4B;IAC5B,uBAAyB;IAEzB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,uBAFU,MAAM,EAAE,CAEgB;IAElC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,mCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,WAFU,SAAS,CAES;;CAE/B;0BAzLyB,4CAA4C"}

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
 import { rgb_to_luminance } from "../../../core/color/rgb_to_luminance.js";
 import { Transform } from "../../../engine/ecs/transform/Transform.js";
 
@@ -55,12 +56,30 @@ export class VolumetricsParticleSpec {
         assert.isNumber(g, 'g');
         assert.isFinite(g, 'g must be finite');
 
-        this.extinction = extinction;
-        this.scattering = scattering;
+        /*
+         Copied rather than referenced: the sources these arrive from are shared constants —
+         `VOLUMETRIC_PARTICLE_SPEC_FOG` and the generated `MIE_PARTICLES_STANDARD_PRECOMPUTED`
+         table — and `Object.freeze` on the object around them does not freeze the arrays inside.
+         Holding onto them would make every spec built from the same entry the same spec, so
+         tuning one volume would retune every other volume sharing its particle.
+        */
+        this.extinction = extinction.slice();
+        this.scattering = scattering.slice();
         this.radius = radius;
         this.g = g;
     }
 
+    /**
+     * @param {VolumetricsParticleSpec} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.radius === other.radius
+            && this.g === other.g
+            && isArrayEqualStrict(this.extinction, other.extinction)
+            && isArrayEqualStrict(this.scattering, other.scattering);
+    }
+
     /**
      *
      * @param {{cross_section_extinction, cross_section_scattering, radius, g}} particle_spec

package/src/shade/renderer/volumetrics/SceneVolumetrics.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Every participating medium in a scene, and a counter saying whether the GPU's copy is stale.
+ *
+ * **The version is the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
+ * entire table whenever the number moves and does nothing at all when it does not, so a volume
+ * changed without moving the counter renders with the values it was last uploaded with — the CPU
+ * object holds the new density, reads back correctly, and only the picture is stale. Anything that
+ * writes into a volume in place therefore has to say so; see {@link invalidate}.
+ *
+ * **Volumes are packed by array index**, so removing one renumbers the rest. That is free here
+ * because the upload is all-or-nothing, and it is the reason no volume carries a slot number.
+ */
 export class SceneVolumetrics {
     /**
      *
@@ -10,5 +22,19 @@ export class SceneVolumetrics {
      * @param {ParticipatingMediaVolume} volume
      */
     add(volume: ParticipatingMediaVolume): void;
+    /**
+     * Take a volume back out.
+     *
+     * @param {ParticipatingMediaVolume} volume
+     * @returns {boolean} true if it was there to be removed
+     */
+    remove(volume: ParticipatingMediaVolume): boolean;
+    /**
+     * Say that a volume already in the scene has been written into.
+     *
+     * Adding and removing move the version by themselves; changing a volume in place is invisible
+     * from here, and this is how such a change reaches the GPU.
+     */
+    invalidate(): void;
 }
 //# sourceMappingURL=SceneVolumetrics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"SceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/SceneVolumetrics.js"],"names":[],"mappings":"AAAA;IACI;;;OAGG;IACH,SAFU,0BAA0B,CAEvB;IAEb,gBAAY;IAEZ;;;OAGG;IACH,4CAMC;CACJ"}
+{"version":3,"file":"SceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/SceneVolumetrics.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;IACI;;;OAGG;IACH,SAFU,0BAA0B,CAEvB;IAEb,gBAAY;IAEZ;;;OAGG;IACH,4CAMC;IAED;;;;;OAKG;IACH,0CAFa,OAAO,CAenB;IAED;;;;;OAKG;IACH,mBAEC;CACJ"}

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

@@ -1,21 +1,64 @@
-export class SceneVolumetrics {
-    /**
-     *
-     * @type {ParticipatingMediaVolume[]}
-     */
-    volumes = [];
-
-    version = 0;
-
-    /**
-     *
-     * @param {ParticipatingMediaVolume} volume
-     */
-    add(volume) {
-
-        this.volumes.push(volume);
-
-        this.version++;
-
-    }
-}
+/**
+ * Every participating medium in a scene, and a counter saying whether the GPU's copy is stale.
+ *
+ * **The version is the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
+ * entire table whenever the number moves and does nothing at all when it does not, so a volume
+ * changed without moving the counter renders with the values it was last uploaded with — the CPU
+ * object holds the new density, reads back correctly, and only the picture is stale. Anything that
+ * writes into a volume in place therefore has to say so; see {@link invalidate}.
+ *
+ * **Volumes are packed by array index**, so removing one renumbers the rest. That is free here
+ * because the upload is all-or-nothing, and it is the reason no volume carries a slot number.
+ */
+export class SceneVolumetrics {
+    /**
+     *
+     * @type {ParticipatingMediaVolume[]}
+     */
+    volumes = [];
+
+    version = 0;
+
+    /**
+     *
+     * @param {ParticipatingMediaVolume} volume
+     */
+    add(volume) {
+
+        this.volumes.push(volume);
+
+        this.version++;
+
+    }
+
+    /**
+     * Take a volume back out.
+     *
+     * @param {ParticipatingMediaVolume} volume
+     * @returns {boolean} true if it was there to be removed
+     */
+    remove(volume) {
+
+        const index = this.volumes.indexOf(volume);
+
+        if (index === -1) {
+            return false;
+        }
+
+        this.volumes.splice(index, 1);
+
+        this.version++;
+
+        return true;
+    }
+
+    /**
+     * Say that a volume already in the scene has been written into.
+     *
+     * Adding and removing move the version by themselves; changing a volume in place is invisible
+     * from here, and this is how such a change reaches the GPU.
+     */
+    invalidate() {
+        this.version++;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"VOLUMETRICS_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_METADATA_STRUCT.js"],"names":[],"mappings":"AAIA,uDAwBG;6BA1B0B,gCAAgC"}
+{"version":3,"file":"VOLUMETRICS_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,uDA+EG;6BAlF0B,gCAAgC"}

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

@@ -1,29 +1,85 @@
-import { f32, u32, vec3f, vec3u, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-
-export const VOLUMETRICS_METADATA_STRUCT = WebGPUStruct.from({
-    resolution: vec3u,
-    // LUT / composite depth curve — covers the full logical range up to camera.far.
-    cluster_parameters: vec3f,
-    // Froxel-grid depth curve — covers [near, froxel_far]. Equals cluster_parameters when the grid
-    // spans the whole range (the no-op default). PM/lighting/TAA build the grid on THIS curve; the
-    // aerial pass uses it to map a LUT depth back to the grid slice it should sample.
-    froxel_cluster_parameters: vec3f,
-    volume_count: u32,
-    // World-space frustum planes with a FINITE far plane. The camera's own projection is
-    // infinite-far reverse-Z (its frustum far plane is zeroed), which frustum_slice can't slice;
-    // this is rebuilt at the logical far for the participating-media coverage test.
-    frustum: WebGPUArray.from(vec4f, 6),
-    // 1 when temporal-reprojection history is invalid (first frame, resolution change, camera
-    // teleport): the volumetric TAA then outputs the fresh sample instead of blending stale history.
-    history_reset: u32,
-    // View-space depth at which the froxel grid ends. The aerial pass samples the grid where
-    // depth <= froxel_far and ray-marches the scene volumes directly beyond it (RDR2-style far
-    // field, growing log steps). Defaults to camera.far -> the whole range is grid-sampled (no-op).
-    froxel_far: f32,
-    // Multiscatter tuning (calculate_multiscattering). Fewer octaves / higher decay -> less
-    // shadow fill -> stronger lit-rim-vs-core contrast (silver lining). Engine defaults: 6 / 0.5.
-    ms_octave_count: u32,
-    ms_extinction_decay: f32,
+import { f32, mat4x4f, u32, vec3f, vec3u, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+
+export const VOLUMETRICS_METADATA_STRUCT = WebGPUStruct.from({
+    resolution: vec3u,
+    // LUT / composite depth curve — covers the full logical range up to camera.far.
+    cluster_parameters: vec3f,
+    // Froxel-grid depth curve — covers [near, froxel_far]. Equals cluster_parameters when the grid
+    // spans the whole range (the no-op default). PM/lighting/TAA build the grid on THIS curve; the
+    // aerial pass uses it to map a LUT depth back to the grid slice it should sample.
+    froxel_cluster_parameters: vec3f,
+    volume_count: u32,
+    // World-space frustum planes with a FINITE far plane. The camera's own projection is
+    // infinite-far reverse-Z (its frustum far plane is zeroed), which frustum_slice can't slice;
+    // this is rebuilt at the logical far for the participating-media coverage test.
+    frustum: WebGPUArray.from(vec4f, 6),
+    // 1 when temporal-reprojection history is invalid (first frame, resolution change, camera
+    // teleport): the volumetric TAA then outputs the fresh sample instead of blending stale history.
+    history_reset: u32,
+    // View-space depth at which the froxel grid ends. The aerial pass samples the grid where
+    // depth <= froxel_far and ray-marches the scene volumes directly beyond it (RDR2-style far
+    // field, growing log steps). Defaults to camera.far -> the whole range is grid-sampled (no-op).
+    froxel_far: f32,
+    // Multiscatter tuning (calculate_multiscattering). Fewer octaves / higher decay -> less
+    // shadow fill -> stronger lit-rim-vs-core contrast (silver lining). Engine defaults: 6 / 0.5.
+    ms_octave_count: u32,
+    ms_extinction_decay: f32,
+
+    /**
+     * Q-04. World position -> [0,1]^3 inside one cascade of the sun's optical-depth volume, and its
+     * inverse, innermost cascade first.
+     *
+     * Each volume's third axis is the direction light travels, so a column of voxels is one sun ray
+     * and the value stored along it is the running integral of extinction — read back in a single
+     * fetch by `chunk_volumetrics_sun_optical_depth`, where the shipping path marches 16 steps per
+     * froxel. `build_volumetrics_sun_shadow_transform` places each box and explains why it is
+     * placed that way; the inverse is what `shader_volumetrics_build_sun_shadow_volume` walks.
+     */
+    sun_shadow_ws_to_uvw: WebGPUArray.from(mat4x4f, VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT),
+    sun_shadow_uvw_to_ws: WebGPUArray.from(mat4x4f, VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT),
+
+    /**
+     * World-space length of one voxel along the sun axis, per cascade — the scan's `dt`. Constant
+     * for the frame, because each box's extent comes from the projection rather than from where the
+     * camera happens to be pointing.
+     *
+     * A `vec4f` rather than an array because WGSL's uniform address space rounds an `array<f32, N>`
+     * element up to 16 bytes, so the packed vector is the same four values in a quarter of the
+     * space and with no stride to get wrong. It is also the reason the cascade count is capped at
+     * four.
+     */
+    sun_shadow_step_ws: vec4f,
+
+    /**
+     * View depth each cascade's box covers out to, innermost first — what the read side selects on.
+     *
+     * Selection is by depth rather than by testing containment in each box because the two agree
+     * (every box contains the sub-frustum out to this depth, by construction) and only the first
+     * gives a scalar to blend across. Unused lanes hold the outermost cascade's far, so a read that
+     * runs off the end of the ladder still lands on a real cascade.
+     */
+    sun_shadow_cascade_far: vec4f,
+
+    /**
+     * Q-04. Which slot of the `light_directional` table the cascades were built for, or
+     * `VOLUMETRICS_SUN_SHADOW_LIGHT_NONE` when they were not built at all.
+     *
+     * The lighting pass tests its loop index against this rather than assuming zero, so a second
+     * directional light degrades to the march instead of being shadowed by the first one's
+     * cascades — there is one ladder and it is aligned to one direction. The sentinel matches no
+     * index, so it degrades *every* directional light the same way, which is what the two cases
+     * that cannot place a box need: a scene with no directional light, and a camera with no field
+     * of view to derive a bounding sphere from.
+     *
+     * This carried a `sun_shadow_mode` word beside it while Q-04 was an A/B. That word is gone: the
+     * cascades are the only path for the sun now, and "not built this frame" is a property of the
+     * light rather than a mode to select.
+     *
+     * Point and spot lights always march. Their `tmax` is the distance to the light, so those rays
+     * are short and local and there is far less to amortize.
+     */
+    sun_shadow_light_index: u32,
 });

package/src/shade/renderer/volumetrics/VOLUMETRICS_SUN_SHADOW_RESOLUTION.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Sub-steps the build pass takes across one voxel of cascade `index`, along the sun.
+ *
+ * A voxel has to hold the medium's integral across its slab, and the rate that integral is sampled
+ * at is a separate knob from the rate it is stored at — only the first has to beat the medium's
+ * features. The outermost cascade has the largest voxel and needs the most; each cascade in from it
+ * has a voxel `RATIO` times smaller, so the same world-space sample spacing costs `RATIO` times
+ * fewer sub-steps. Holding the spacing constant across cascades rather than the count is what keeps
+ * the innermost cascade from spending its budget resolving a millimetre.
+ *
+ * **Always even, and never fewer than two.** The build stores its running integral when it reaches
+ * sub-step `count / 2`, which is the voxel's centre only when the halves are equal; an odd count
+ * stores the integral to `floor(count/2)/count` of the slab, and one sub-step stores it to the near
+ * face — a half-slab bias in the direction that makes the medium shadow too little, on the cascade
+ * that matters most.
+ *
+ * @param {number} index
+ * @returns {number}
+ */
+export function volumetrics_sun_shadow_sub_steps(index: number): number;
+/**
+ * Voxel counts of one cascade of the sun optical-depth volume, `[x, y, z]`, with `z` along the sun.
+ *
+ * Cubic, and that is a measured decision rather than a default. It is tempting to make the grid
+ * lateral-heavy: at the playground's 60 degree field of view the medium there is a horizontal slab
+ * three units thick crossed by a low sun, so its structure perpendicular to the sun is far finer
+ * than its structure along it, and as a single box `[256, 256, 32]` beats `[128, 128, 128]` by an
+ * order of magnitude at identical memory. That advantage belongs to *that* fog and *that* sun
+ * elevation. Against a converged reference at one viewpoint, as a single box:
+ *
+ * | field of view | `[128,128,128]` | `[256,256,32]` |
+ * |---|---|---|
+ * | 40 deg  | +6.4  | +28.1 |
+ * | 60 deg  | +37.7 | +2.5  |
+ * | 90 deg  | +1.4  | +39.0 |
+ * | 110 deg | +2.1  | +39.5 |
+ *
+ * Two axes, two Nyquist limits, and which one is starved depends on the camera. Cubic is the shape
+ * that does not assume. 96 puts one cascade at 7.1 MB, three at 21.2 MB.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_SUN_SHADOW_RESOLUTION: number[];
+/**
+ * How many cascades the structure carries.
+ *
+ * A single world-uniform box cannot be sized correctly, and that is arithmetic rather than tuning.
+ * The box has to contain the camera frustum under any rotation, so its side is proportional to
+ * `far` and to `tan(fov/2)`; the medium's features — a three-unit fog slab — are absolute. So the
+ * ratio between what the structure can resolve and what it has to resolve is a free parameter of
+ * the *camera*, and the table above is what that looks like: every single-box configuration
+ * measured has a field of view at which it is 28 to 50 mean luminance from the truth, and which
+ * one moves with the resolution. Three cascades of 96 are within 1.8 across the same range.
+ *
+ * Buying the near field's resolution uniformly instead is not an option: 0.28 unit voxels over a
+ * 283 unit box is 1024 per axis, i.e. 268 MB. Cascades buy it where the froxels are, which on a
+ * log-distributed grid over [0.1, 120] is two thirds of the slices inside 15 units — the innermost
+ * box here is 33 units across, so its voxel is 0.34 units for 7.1 MB.
+ *
+ * Three is what Frostbite ships for its extinction clipmap and what Enshrouded ships for this exact
+ * structure. Four is a constant away; the read side, the metadata and the build shaders are all
+ * generated from this.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT: number;
+/**
+ * Ratio between one cascade's far distance and the next one in.
+ *
+ * `far_i = far / RATIO^(count - 1 - i)`, the logarithmic split, so every cascade has the same
+ * voxel-size ratio to its neighbour and the *worst* case within a cascade — its near end — is a
+ * fixed factor. Three cascades at ratio 3 cover a 120 unit far plane as 13.3 / 40 / 120, giving
+ * 0.34 / 1.02 / 3.07 unit voxels at 96 per axis.
+ *
+ * Bounded by the metadata: the per-cascade scalars are packed into `vec4f`, so no more than four.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO: number;
+/**
+ * `sun_shadow_light_index` when no cascades were placed this frame, so no directional light matches
+ * it and every one of them falls back to the per-froxel march.
+ *
+ * Two situations reach it and neither is a switch: a scene with no directional light, and a camera
+ * with no field of view for {@link frustum_bounding_sphere} to work from. The build passes still
+ * run — collapsed to one voxel — because the lighting pass binds their outputs unconditionally and
+ * WebGPU has no optional bindings.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_LIGHT_NONE: number;
+/**
+ * Workgroup shape of the build pass. One invocation owns a whole column along the sun axis, so
+ * this is 2D and covers the volume's x/y.
+ * @type {number[]}
+ */
+export const VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION: number[];
+//# sourceMappingURL=VOLUMETRICS_SUN_SHADOW_RESOLUTION.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VOLUMETRICS_SUN_SHADOW_RESOLUTION.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_SUN_SHADOW_RESOLUTION.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDAHW,MAAM,GACJ,MAAM,CAWlB;AA1FD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gDAFU,MAAM,EAAE,CAE4C;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,mDAFU,MAAM,CAEsC;AAEtD;;;;;;;;;;;GAWG;AACH,mDAFU,MAAM,CAEsC;AAgCtD;;;;;;;;;;GAUG;AACH,gDAFU,MAAM,CAE4C;AAE5D;;;;GAIG;AACH,0DAFU,MAAM,EAAE,CAEgD"}

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

@@ -0,0 +1,111 @@
+/**
+ * Voxel counts of one cascade of the sun optical-depth volume, `[x, y, z]`, with `z` along the sun.
+ *
+ * Cubic, and that is a measured decision rather than a default. It is tempting to make the grid
+ * lateral-heavy: at the playground's 60 degree field of view the medium there is a horizontal slab
+ * three units thick crossed by a low sun, so its structure perpendicular to the sun is far finer
+ * than its structure along it, and as a single box `[256, 256, 32]` beats `[128, 128, 128]` by an
+ * order of magnitude at identical memory. That advantage belongs to *that* fog and *that* sun
+ * elevation. Against a converged reference at one viewpoint, as a single box:
+ *
+ * | field of view | `[128,128,128]` | `[256,256,32]` |
+ * |---|---|---|
+ * | 40 deg  | +6.4  | +28.1 |
+ * | 60 deg  | +37.7 | +2.5  |
+ * | 90 deg  | +1.4  | +39.0 |
+ * | 110 deg | +2.1  | +39.5 |
+ *
+ * Two axes, two Nyquist limits, and which one is starved depends on the camera. Cubic is the shape
+ * that does not assume. 96 puts one cascade at 7.1 MB, three at 21.2 MB.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_SUN_SHADOW_RESOLUTION = [96, 96, 96];
+
+/**
+ * How many cascades the structure carries.
+ *
+ * A single world-uniform box cannot be sized correctly, and that is arithmetic rather than tuning.
+ * The box has to contain the camera frustum under any rotation, so its side is proportional to
+ * `far` and to `tan(fov/2)`; the medium's features — a three-unit fog slab — are absolute. So the
+ * ratio between what the structure can resolve and what it has to resolve is a free parameter of
+ * the *camera*, and the table above is what that looks like: every single-box configuration
+ * measured has a field of view at which it is 28 to 50 mean luminance from the truth, and which
+ * one moves with the resolution. Three cascades of 96 are within 1.8 across the same range.
+ *
+ * Buying the near field's resolution uniformly instead is not an option: 0.28 unit voxels over a
+ * 283 unit box is 1024 per axis, i.e. 268 MB. Cascades buy it where the froxels are, which on a
+ * log-distributed grid over [0.1, 120] is two thirds of the slices inside 15 units — the innermost
+ * box here is 33 units across, so its voxel is 0.34 units for 7.1 MB.
+ *
+ * Three is what Frostbite ships for its extinction clipmap and what Enshrouded ships for this exact
+ * structure. Four is a constant away; the read side, the metadata and the build shaders are all
+ * generated from this.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT = 3;
+
+/**
+ * Ratio between one cascade's far distance and the next one in.
+ *
+ * `far_i = far / RATIO^(count - 1 - i)`, the logarithmic split, so every cascade has the same
+ * voxel-size ratio to its neighbour and the *worst* case within a cascade — its near end — is a
+ * fixed factor. Three cascades at ratio 3 cover a 120 unit far plane as 13.3 / 40 / 120, giving
+ * 0.34 / 1.02 / 3.07 unit voxels at 96 per axis.
+ *
+ * Bounded by the metadata: the per-cascade scalars are packed into `vec4f`, so no more than four.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO = 3;
+
+/**
+ * Sub-steps the build pass takes across one voxel of cascade `index`, along the sun.
+ *
+ * A voxel has to hold the medium's integral across its slab, and the rate that integral is sampled
+ * at is a separate knob from the rate it is stored at — only the first has to beat the medium's
+ * features. The outermost cascade has the largest voxel and needs the most; each cascade in from it
+ * has a voxel `RATIO` times smaller, so the same world-space sample spacing costs `RATIO` times
+ * fewer sub-steps. Holding the spacing constant across cascades rather than the count is what keeps
+ * the innermost cascade from spending its budget resolving a millimetre.
+ *
+ * **Always even, and never fewer than two.** The build stores its running integral when it reaches
+ * sub-step `count / 2`, which is the voxel's centre only when the halves are equal; an odd count
+ * stores the integral to `floor(count/2)/count` of the slab, and one sub-step stores it to the near
+ * face — a half-slab bias in the direction that makes the medium shadow too little, on the cascade
+ * that matters most.
+ *
+ * @param {number} index
+ * @returns {number}
+ */
+export function volumetrics_sun_shadow_sub_steps(index) {
+    const outermost = 4;
+
+    const halves = Math.max(
+        1,
+        Math.ceil(outermost / (2 * Math.pow(VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO, VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1 - index)))
+    );
+
+    return 2 * halves;
+}
+
+/**
+ * `sun_shadow_light_index` when no cascades were placed this frame, so no directional light matches
+ * it and every one of them falls back to the per-froxel march.
+ *
+ * Two situations reach it and neither is a switch: a scene with no directional light, and a camera
+ * with no field of view for {@link frustum_bounding_sphere} to work from. The build passes still
+ * run — collapsed to one voxel — because the lighting pass binds their outputs unconditionally and
+ * WebGPU has no optional bindings.
+ *
+ * @type {number}
+ */
+export const VOLUMETRICS_SUN_SHADOW_LIGHT_NONE = 0xFFFFFFFF;
+
+/**
+ * Workgroup shape of the build pass. One invocation owns a whole column along the sun axis, so
+ * this is 2D and covers the volume's x/y.
+ * @type {number[]}
+ */
+export const VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION = [8, 8];

package/src/shade/renderer/volumetrics/build_volumetrics_sun_shadow_transform.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Far distance of cascade `index`, i.e. the view depth its box has to cover.
+ *
+ * A logarithmic split, `far / ratio^(count - 1 - index)`. The choice is forced by what the cascades
+ * are for: every box is sized from the bounding sphere of the sub-frustum it covers, so its voxel is
+ * proportional to its far distance, and a constant ratio between far distances is a constant ratio
+ * between voxel sizes. Any other split leaves one cascade carrying a resolution jump the others do
+ * not.
+ *
+ * The innermost cascade still starts at the camera rather than at the previous cascade's far plane —
+ * cascades here nest rather than tile, because the box is sized from a *frustum's* bounding sphere
+ * and a shell would need a sphere around the shell, which is the outer sphere again.
+ *
+ * @param {number} far the full range the structure must cover
+ * @param {number} index
+ * @param {number} count
+ * @param {number} ratio
+ * @returns {number}
+ */
+export function volumetrics_sun_shadow_cascade_far(far: number, index: number, count: number, ratio: number): number;
+/**
+ * Radius of the smallest sphere containing a symmetric perspective frustum, and where its centre
+ * sits along the view axis.
+ *
+ * This is the quantity that makes the structure temporally stable, and the reason it is a sphere
+ * rather than a tight fit: it depends only on `fov`, `aspect`, `near` and `far`, so it does not
+ * change when the camera turns. A box sized from it therefore has a fixed extent, hence a fixed
+ * voxel size, hence a world-space voxel lattice that only ever translates.
+ *
+ * Both frustum corner rings are equidistant from the centre when
+ * `z = (far + near)(k^2 + 1) / 2` with `k^2 = tan^2(theta_x) + tan^2(theta_y)`. Past `z = far` that
+ * solution leaves the sphere behind the far plane, and the far ring alone bounds it.
+ *
+ * @param {number[]} out `[center_view_z, radius]`
+ * @param {number} fov_y vertical field of view, radians
+ * @param {number} aspect width / height
+ * @param {number} near
+ * @param {number} far
+ * @returns {number[]} out
+ */
+export function frustum_bounding_sphere(out: number[], fov_y: number, aspect: number, near: number, far: number): number[];
+/**
+ * Place the sun's optical-depth volume for this frame.
+ *
+ * The volume is a box aligned to the sun: its third axis is the direction light travels, so a
+ * column of voxels along that axis is a light ray, and the optical depth of every voxel in the
+ * column is one running sum away from its neighbour's. That is what
+ * `shader_volumetrics_build_sun_shadow_volume` computes and what
+ * `chunk_volumetrics_sun_optical_depth` reads back in a single fetch.
+ *
+ * Two properties matter and both are about time rather than space, because the froxel lighting this
+ * feeds goes through a 0.95-blend temporal filter that turns any instability into either ghosting
+ * or flicker:
+ *
+ *  - **The extent never changes with camera orientation.** It comes from the frustum's bounding
+ *    sphere, which is a function of the projection only. A tight fit of the frustum corners in sun
+ *    space — the obvious thing, and what this engine's CSM deliberately does for its cascades —
+ *    would breathe as the camera turned, moving every voxel centre continuously and making the
+ *    whole structure swim. The CSM can afford the tight fit because it is two orders of magnitude
+ *    denser and its consumer is a filtered depth comparison; this is neither.
+ *
+ *  - **The origin is snapped to a whole voxel.** With a fixed extent that makes the world-space
+ *    voxel lattice identical from frame to frame no matter how the camera moves: voxel centres land
+ *    on the same world positions, so the sampled medium is the same and the reconstruction is the
+ *    same function of world position. Only the indexing changes. The box shifts by whole voxels,
+ *    and the slab it gains or loses lies outside the frustum where the medium is zero, so even the
+ *    scan's starting value is unaffected.
+ *
+ * @param {Float32Array} ws_to_uvw 16 floats, column-major. World position -> [0,1]^3 volume coords.
+ * @param {Float32Array} uvw_to_ws 16 floats, column-major. Its inverse, for the build pass.
+ * @param {ArrayLike<number>} light_direction unit vector along which light TRAVELS (the
+ * `light_directional` table's `direction`, i.e. NOT the direction toward the light).
+ * @param {ArrayLike<number>} camera_position world space
+ * @param {ArrayLike<number>} camera_forward unit, world space
+ * @param {number} fov_y vertical field of view, radians
+ * @param {number} aspect width / height
+ * @param {number} near
+ * @param {number} far the depth the medium actually extends to — `min(froxel_far, camera.far)`,
+ * since the froxel grid is where the extinction is read from and it ends there.
+ * @param {ArrayLike<number>} resolution `[x, y, z]` voxel counts
+ * @returns {number} world-space length of one voxel along the sun axis, i.e. the scan's `dz`
+ */
+export function build_volumetrics_sun_shadow_transform({ ws_to_uvw, uvw_to_ws, light_direction, camera_position, camera_forward, fov_y, aspect, near, far, resolution, }: Float32Array): number;
+//# sourceMappingURL=build_volumetrics_sun_shadow_transform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build_volumetrics_sun_shadow_transform.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/build_volumetrics_sun_shadow_transform.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDANW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CAPW,MAAM,EAAE,SACR,MAAM,UACN,MAAM,QACN,MAAM,OACN,MAAM,GACJ,MAAM,EAAE,CAoBpB;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,0KAdW,YAAY,GAYV,MAAM,CA4ElB"}