@woosh/meep-engine 3.37.0 → 3.39.0

package/src/shade/renderer/medium/water/water_rgb_from_spectral.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Fit an RGB coefficient (1/m), in the engine's linear working space (Rec.709 primaries, D65
+ * white), to a spectral one, so that a white (D65) target seen through a path d of exp(-σ_c d) per
+ * channel looks as it does through exp(-σ(λ) d) per wavelength, over the given path lengths.
+ *
+ * **Target.** For each path d, D65 is attenuated wavelength by wavelength and integrated against the
+ * CIE 1931 2° colour matching functions (trapezoid rule over `wavelengths`), normalized so the
+ * unattenuated illuminant has Y = 1. The candidate is the illuminant's own RGB scaled per channel by
+ * exp(-σ_c d), taken back to XYZ. A wavelength-independent coefficient therefore fits exactly.
+ *
+ * **Error metric.** Least squares on CIELAB ΔE*ab (CIE 15:2004) between candidate and target, summed
+ * over the paths; ΔE*ab of about 1 is a just-noticeable difference. Comparing in Lab rather than in
+ * RGB matters for water: after a few metres the light left is a saturated blue-green outside the
+ * Rec.709 gamut (its red channel is negative), so an RGB target would first have to be clipped or
+ * desaturated, which is a choice about colour, not physics. Lab compares against the real colour and
+ * the part RGB cannot show stays in the residual. It also weighs each path by how visible its error
+ * is: linear transmittance would let the short paths decide everything (a factor of two in the few
+ * percent of green left after 50 m is invisible to a linear fit), and optical depth would let the
+ * longest paths decide everything, where nothing is left to see.
+ *
+ * **Why not a per-band mean.** Averaging σ(λ) over a channel's sensitivity, as one would a colour
+ * (and as `compute_mie_particle_properties_rgb` does for its coefficients), gives the channel's
+ * attenuation over vanishingly short paths only. Over a long path the wavelengths absorbed least are
+ * the ones left, so a channel's effective coefficient falls with distance (Akkaynak & Treibitz
+ * 2018, "A revised underwater image formation model", CVPR, show the same for camera bands).
+ * Measured on pure water (the spec pins these): weighted by luminance its mean absorption is
+ * 0.097 1/m, while the luminance left after 50 m has been attenuated at 0.047 1/m, a 2.1x
+ * overestimate. How large depends on how the band is cut: a 500–600 nm box gives 1.5x, the
+ * positive lobe of the sRGB green 1.3x, and an earlier figure of about 4x was not reproduced. With the
+ * signed sRGB sensitivities a band mean can even come out negative, as pure water's blue does
+ * (-0.0006 1/m), a channel that would brighten with distance. Over 0.1–50 m the band means' worst
+ * ΔE*ab is 16 for pure water and 19 for Jerlov II, against this fit's 11 and 12, nearly all of which
+ * is the Rec.709 gamut itself: the clipped target alone is 12 and 13 ΔE*ab from the real colour.
+ *
+ * **Solver.** A per-channel start from a coarse log scan with the other channels clear, then
+ * coordinate descent: each channel in turn is minimized with the others held (log scan within a
+ * factor of 8 around the current value, golden section, zero as a candidate), until a sweep moves no
+ * coefficient by more than 1e-10 relatively.
+ *
+ * @param {Object} options
+ * @param {ArrayLike<number>} options.wavelengths nm, strictly increasing, at least 2
+ * @param {ArrayLike<number>} options.coefficient σ(λ) at those wavelengths, 1/m, ≥ 0
+ * @param {ArrayLike<number>} options.path_lengths metres, > 0, at least 1
+ * @returns {{coefficient: number[], residual: number}} the RGB coefficient, 1/m, and the largest
+ * ΔE*ab over the path lengths between the fit and the spectral target
+ */
+export function water_rgb_from_spectral({ wavelengths, coefficient, path_lengths }: {
+    wavelengths: ArrayLike<number>;
+    coefficient: ArrayLike<number>;
+    path_lengths: ArrayLike<number>;
+}): {
+    coefficient: number[];
+    residual: number;
+};
+/**
+ * Everything the error of a candidate coefficient needs, computed once per fit.
+ */
+export type FitProblem = {
+    path_lengths: ArrayLike<number>;
+    /**
+     * RGB of the illuminant, whose XYZ has Y = 1
+     */
+    white_rgb: number[];
+    /**
+     * L*, a*, b* of the spectrally attenuated illuminant, per path
+     */
+    target_lab: Float64Array;
+};
+//# sourceMappingURL=water_rgb_from_spectral.d.ts.map

package/src/shade/renderer/medium/water/water_rgb_from_spectral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"water_rgb_from_spectral.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_rgb_from_spectral.js"],"names":[],"mappings":"AA8IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IANsC,WAAW,EAAtC,UAAU,MAAM,CAAC;IACU,WAAW,EAAtC,UAAU,MAAM,CAAC;IACU,YAAY,EAAvC,UAAU,MAAM,CAAC;IACf;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CA2JrD;;;;;kBA3Ta,UAAU,MAAM,CAAC;;;;eACjB,MAAM,EAAE;;;;gBACR,YAAY"}

package/src/shade/renderer/medium/water/water_rgb_from_spectral.js

@@ -0,0 +1,341 @@
+import { assert } from "../../../../core/assert.js";
+import { D65_spd_tabulated } from "../../../../core/color/illuminant/D65_spd_tabulated.js";
+import { xyz_to_lab } from "../../../../core/color/lab/xyz_to_lab.js";
+import { rgb_to_xyz } from "../../../../core/color/xyz/rgb_to_xyz.js";
+import { xyz_cmf_tabulated } from "../../../../core/color/xyz/xyz_cmf_tabulated.js";
+import { xyz_to_rgb } from "../../../../core/color/xyz/xyz_to_rgb.js";
+
+/**
+ * Bounds of the coefficient search, 1/m. 1e-7 is far below pure water's weakest scattering (0.0006
+ * 1/m at 780 nm); 1e4 extinguishes a channel within 0.1 mm.
+ */
+const SIGMA_MIN = 1e-7;
+const SIGMA_MAX = 1e4;
+
+const INITIAL_SCAN_STEPS = 240;
+const LOCAL_SCAN_STEPS = 48;
+const LOCAL_SCAN_FACTOR = 8;
+const GOLDEN_ITERATIONS = 60;
+const SWEEP_LIMIT = 60;
+const SWEEP_TOLERANCE = 1e-10;
+
+/**
+ * Everything the error of a candidate coefficient needs, computed once per fit.
+ *
+ * @typedef {Object} FitProblem
+ * @property {ArrayLike<number>} path_lengths
+ * @property {number[]} white_rgb RGB of the illuminant, whose XYZ has Y = 1
+ * @property {Float64Array} target_lab L*, a*, b* of the spectrally attenuated illuminant, per path
+ */
+
+/**
+ * Summed squared CIELAB ΔE*ab, over the paths, between the illuminant attenuated by the RGB
+ * coefficient and the spectral target.
+ *
+ * @param {FitProblem} problem
+ * @param {number[]} sigma
+ * @param {number[]} scratch_rgb
+ * @param {number[]} scratch_xyz
+ * @param {number[]} scratch_lab
+ * @returns {number}
+ */
+function fit_error(problem, sigma, scratch_rgb, scratch_xyz, scratch_lab) {
+    const { path_lengths, white_rgb, target_lab } = problem;
+
+    let sum = 0;
+
+    for (let p = 0; p < path_lengths.length; p++) {
+        const d = path_lengths[p];
+
+        for (let c = 0; c < 3; c++) {
+            scratch_rgb[c] = white_rgb[c] * Math.exp(-sigma[c] * d);
+        }
+
+        rgb_to_xyz(scratch_xyz, 0, scratch_rgb, 0);
+        xyz_to_lab(scratch_lab, 0, scratch_xyz, 0);
+
+        const dl = scratch_lab[0] - target_lab[p * 3];
+        const da = scratch_lab[1] - target_lab[p * 3 + 1];
+        const db = scratch_lab[2] - target_lab[p * 3 + 2];
+
+        sum += dl * dl + da * da + db * db;
+    }
+
+    return sum;
+}
+
+/**
+ * Minimize the error over one channel's coefficient with the other two held: a log-spaced scan of
+ * [lo, hi] for the basin, golden-section refinement inside it, and zero as a candidate of its own.
+ *
+ * @param {FitProblem} problem
+ * @param {number[]} sigma updated in place
+ * @param {number} channel
+ * @param {number} lo
+ * @param {number} hi
+ * @param {number} steps
+ * @param {number[][]} scratch
+ */
+function minimize_channel(problem, sigma, channel, lo, hi, steps, scratch) {
+    const [scratch_rgb, scratch_xyz, scratch_lab] = scratch;
+
+    /**
+     * @param {number} log_sigma
+     * @returns {number}
+     */
+    const error_at = (log_sigma) => {
+        sigma[channel] = Math.exp(log_sigma);
+        return fit_error(problem, sigma, scratch_rgb, scratch_xyz, scratch_lab);
+    };
+
+    const log_lo = Math.log(lo);
+    const log_step = (Math.log(hi) - log_lo) / steps;
+
+    let best_index = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i <= steps; i++) {
+        const error = error_at(log_lo + i * log_step);
+
+        if (error < best_error) {
+            best_error = error;
+            best_index = i;
+        }
+    }
+
+    let a = log_lo + Math.max(best_index - 1, 0) * log_step;
+    let b = log_lo + Math.min(best_index + 1, steps) * log_step;
+
+    const golden = (Math.sqrt(5) - 1) / 2;
+
+    let x1 = b - golden * (b - a);
+    let x2 = a + golden * (b - a);
+    let f1 = error_at(x1);
+    let f2 = error_at(x2);
+
+    for (let i = 0; i < GOLDEN_ITERATIONS; i++) {
+        if (f1 < f2) {
+            b = x2;
+            x2 = x1;
+            f2 = f1;
+            x1 = b - golden * (b - a);
+            f1 = error_at(x1);
+        } else {
+            a = x1;
+            x1 = x2;
+            f1 = f2;
+            x2 = a + golden * (b - a);
+            f2 = error_at(x2);
+        }
+    }
+
+    const refined = Math.exp((a + b) / 2);
+
+    sigma[channel] = refined;
+    const refined_error = fit_error(problem, sigma, scratch_rgb, scratch_xyz, scratch_lab);
+
+    sigma[channel] = 0;
+    const zero_error = fit_error(problem, sigma, scratch_rgb, scratch_xyz, scratch_lab);
+
+    sigma[channel] = zero_error <= refined_error ? 0 : refined;
+}
+
+/**
+ * Fit an RGB coefficient (1/m), in the engine's linear working space (Rec.709 primaries, D65
+ * white), to a spectral one, so that a white (D65) target seen through a path d of exp(-σ_c d) per
+ * channel looks as it does through exp(-σ(λ) d) per wavelength, over the given path lengths.
+ *
+ * **Target.** For each path d, D65 is attenuated wavelength by wavelength and integrated against the
+ * CIE 1931 2° colour matching functions (trapezoid rule over `wavelengths`), normalized so the
+ * unattenuated illuminant has Y = 1. The candidate is the illuminant's own RGB scaled per channel by
+ * exp(-σ_c d), taken back to XYZ. A wavelength-independent coefficient therefore fits exactly.
+ *
+ * **Error metric.** Least squares on CIELAB ΔE*ab (CIE 15:2004) between candidate and target, summed
+ * over the paths; ΔE*ab of about 1 is a just-noticeable difference. Comparing in Lab rather than in
+ * RGB matters for water: after a few metres the light left is a saturated blue-green outside the
+ * Rec.709 gamut (its red channel is negative), so an RGB target would first have to be clipped or
+ * desaturated, which is a choice about colour, not physics. Lab compares against the real colour and
+ * the part RGB cannot show stays in the residual. It also weighs each path by how visible its error
+ * is: linear transmittance would let the short paths decide everything (a factor of two in the few
+ * percent of green left after 50 m is invisible to a linear fit), and optical depth would let the
+ * longest paths decide everything, where nothing is left to see.
+ *
+ * **Why not a per-band mean.** Averaging σ(λ) over a channel's sensitivity, as one would a colour
+ * (and as `compute_mie_particle_properties_rgb` does for its coefficients), gives the channel's
+ * attenuation over vanishingly short paths only. Over a long path the wavelengths absorbed least are
+ * the ones left, so a channel's effective coefficient falls with distance (Akkaynak & Treibitz
+ * 2018, "A revised underwater image formation model", CVPR, show the same for camera bands).
+ * Measured on pure water (the spec pins these): weighted by luminance its mean absorption is
+ * 0.097 1/m, while the luminance left after 50 m has been attenuated at 0.047 1/m, a 2.1x
+ * overestimate. How large depends on how the band is cut: a 500–600 nm box gives 1.5x, the
+ * positive lobe of the sRGB green 1.3x, and an earlier figure of about 4x was not reproduced. With the
+ * signed sRGB sensitivities a band mean can even come out negative, as pure water's blue does
+ * (-0.0006 1/m), a channel that would brighten with distance. Over 0.1–50 m the band means' worst
+ * ΔE*ab is 16 for pure water and 19 for Jerlov II, against this fit's 11 and 12, nearly all of which
+ * is the Rec.709 gamut itself: the clipped target alone is 12 and 13 ΔE*ab from the real colour.
+ *
+ * **Solver.** A per-channel start from a coarse log scan with the other channels clear, then
+ * coordinate descent: each channel in turn is minimized with the others held (log scan within a
+ * factor of 8 around the current value, golden section, zero as a candidate), until a sweep moves no
+ * coefficient by more than 1e-10 relatively.
+ *
+ * @param {Object} options
+ * @param {ArrayLike<number>} options.wavelengths nm, strictly increasing, at least 2
+ * @param {ArrayLike<number>} options.coefficient σ(λ) at those wavelengths, 1/m, ≥ 0
+ * @param {ArrayLike<number>} options.path_lengths metres, > 0, at least 1
+ * @returns {{coefficient: number[], residual: number}} the RGB coefficient, 1/m, and the largest
+ * ΔE*ab over the path lengths between the fit and the spectral target
+ */
+export function water_rgb_from_spectral({ wavelengths, coefficient, path_lengths }) {
+    assert.isArrayLike(wavelengths, 'wavelengths');
+    assert.isArrayLike(coefficient, 'coefficient');
+    assert.isArrayLike(path_lengths, 'path_lengths');
+
+    const wavelength_count = wavelengths.length;
+    const path_count = path_lengths.length;
+
+    assert.greaterThanOrEqual(wavelength_count, 2, 'wavelengths.length');
+    assert.equal(coefficient.length, wavelength_count, 'coefficient.length !== wavelengths.length');
+    assert.greaterThanOrEqual(path_count, 1, 'path_lengths.length');
+
+    for (let i = 0; i < wavelength_count; i++) {
+        assert.isFinite(wavelengths[i], `wavelengths[${i}]`);
+        assert.isFinite(coefficient[i], `coefficient[${i}]`);
+        assert.greaterThanOrEqual(coefficient[i], 0, `coefficient[${i}]`);
+
+        if (i > 0) {
+            assert.greaterThan(wavelengths[i], wavelengths[i - 1], `wavelengths[${i}]`);
+        }
+    }
+
+    for (let i = 0; i < path_count; i++) {
+        assert.isFinite(path_lengths[i], `path_lengths[${i}]`);
+        assert.greaterThan(path_lengths[i], 0, `path_lengths[${i}]`);
+    }
+
+    // trapezoid weights of D65 x CMF
+    const weight_x = new Float64Array(wavelength_count);
+    const weight_y = new Float64Array(wavelength_count);
+    const weight_z = new Float64Array(wavelength_count);
+
+    const cmf = [0, 0, 0];
+
+    let white_y = 0;
+
+    for (let i = 0; i < wavelength_count; i++) {
+        const left = i > 0 ? wavelengths[i] - wavelengths[i - 1] : 0;
+        const right = i < wavelength_count - 1 ? wavelengths[i + 1] - wavelengths[i] : 0;
+        const width = (left + right) / 2;
+
+        xyz_cmf_tabulated(cmf, wavelengths[i]);
+        const e = D65_spd_tabulated(wavelengths[i]) * width;
+
+        weight_x[i] = cmf[0] * e;
+        weight_y[i] = cmf[1] * e;
+        weight_z[i] = cmf[2] * e;
+
+        white_y += weight_y[i];
+    }
+
+    assert.greaterThan(white_y, 0, 'the wavelengths carry no luminance');
+
+    const xyz = [0, 0, 0];
+
+    for (let i = 0; i < wavelength_count; i++) {
+        xyz[0] += weight_x[i] / white_y;
+        xyz[1] += weight_y[i] / white_y;
+        xyz[2] += weight_z[i] / white_y;
+    }
+
+    const white_rgb = [0, 0, 0];
+    xyz_to_rgb(white_rgb, 0, xyz, 0);
+
+    const target_lab = new Float64Array(path_count * 3);
+
+    for (let p = 0; p < path_count; p++) {
+        const d = path_lengths[p];
+
+        xyz[0] = 0;
+        xyz[1] = 0;
+        xyz[2] = 0;
+
+        for (let i = 0; i < wavelength_count; i++) {
+            const t = Math.exp(-coefficient[i] * d) / white_y;
+
+            xyz[0] += weight_x[i] * t;
+            xyz[1] += weight_y[i] * t;
+            xyz[2] += weight_z[i] * t;
+        }
+
+        xyz_to_lab(target_lab, p * 3, xyz, 0);
+    }
+
+    /** @type {FitProblem} */
+    const problem = { path_lengths, white_rgb, target_lab };
+    const scratch = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+
+    // start: each channel alone, the others clear
+    const sigma = [0, 0, 0];
+    const start = [0, 0, 0];
+
+    for (let c = 0; c < 3; c++) {
+        minimize_channel(problem, sigma, c, SIGMA_MIN, SIGMA_MAX, INITIAL_SCAN_STEPS, scratch);
+        start[c] = sigma[c];
+        sigma[c] = 0;
+    }
+
+    sigma[0] = start[0];
+    sigma[1] = start[1];
+    sigma[2] = start[2];
+
+    for (let sweep = 0; sweep < SWEEP_LIMIT; sweep++) {
+        let largest_change = 0;
+
+        for (let c = 0; c < 3; c++) {
+            const previous = sigma[c];
+
+            if (previous > 0) {
+                const lo = Math.max(previous / LOCAL_SCAN_FACTOR, SIGMA_MIN);
+                const hi = Math.min(previous * LOCAL_SCAN_FACTOR, SIGMA_MAX);
+
+                minimize_channel(problem, sigma, c, lo, hi, LOCAL_SCAN_STEPS, scratch);
+            } else {
+                // a clear channel may need to leave zero once the others have moved
+                minimize_channel(problem, sigma, c, SIGMA_MIN, SIGMA_MAX, INITIAL_SCAN_STEPS, scratch);
+            }
+
+            const scale = Math.max(Math.abs(previous), Math.abs(sigma[c]), SIGMA_MIN);
+            largest_change = Math.max(largest_change, Math.abs(sigma[c] - previous) / scale);
+        }
+
+        if (largest_change < SWEEP_TOLERANCE) {
+            break;
+        }
+    }
+
+    // residual: the worst path
+    const [scratch_rgb, scratch_xyz, scratch_lab] = scratch;
+    let residual = 0;
+
+    for (let p = 0; p < path_count; p++) {
+        const d = path_lengths[p];
+
+        for (let c = 0; c < 3; c++) {
+            scratch_rgb[c] = white_rgb[c] * Math.exp(-sigma[c] * d);
+        }
+
+        rgb_to_xyz(scratch_xyz, 0, scratch_rgb, 0);
+        xyz_to_lab(scratch_lab, 0, scratch_xyz, 0);
+
+        const dl = scratch_lab[0] - target_lab[p * 3];
+        const da = scratch_lab[1] - target_lab[p * 3 + 1];
+        const db = scratch_lab[2] - target_lab[p * 3 + 2];
+
+        residual = Math.max(residual, Math.sqrt(dl * dl + da * da + db * db));
+    }
+
+    return {
+        coefficient: sigma.slice(),
+        residual,
+    };
+}

package/src/shade/renderer/particles/DESIGN.md

@@ -544,9 +544,11 @@ contribution at the three points where the meshlet buckets have just made theirs
 2. **splat** (`shader_particle_avboit_splat`): the billboard quads rasterized at the volume's
    resolution, coverage from the atlas alpha, extinction through `avboit_splat_slice` — the same
    write path as a surface. Additive particles write nothing. A soft-depth particle is faded here
-   against the same scene depth the draw fades it against, one sample per voxel: what the volume
+   against the same scene depth the draw fades it against, averaged over the voxel's footprint at the
+   four standard 4× multisample positions (`chunk_particle_avboit_voxel_fade`): what the volume
    records has to be the coverage the accumulators are weighted by, or a card that fades out where
-   it meets the floor goes on darkening the floor through itself.
+   it meets the floor goes on darkening the floor through itself. (One read at the voxel's corner
+   recorded up to 2.4× the coverage on a floor seen at a distance; AVBOIT ledger entry 26.)
 3. **draw** (`shader_particle_avboit_draw`): the quads at internal resolution, depth-tested read-only
    against the scene (which lets the soft fade read the same depth), fog composited, transmittance
    from the integral. Which of the two it is, is decided by coverage rather than by the blend enum,

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.d.ts

@@ -13,7 +13,7 @@
  *
  * ## Why f32 in the buffer, and not an order-preserving encoding
  *
- * `aabb_atomic_min_f32` / `aabb_atomic_max_f32` are the engine's, shared with the skinned-mesh
+ * `atomic_min_f32_storage` / `atomic_max_f32_storage` are the engine's, shared with the skinned-mesh
  * bounds refresh, and they CAS-spin over the plain float so the words are readable as floats at
  * every moment of the frame. The sign-flip encoding that would let `atomicMin` do it in one
  * instruction leaves the buffer in a form only a decoder understands, and the publish pass reads

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/chunk_particle_bounds.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,0CAFU,SAAS,CAwEyC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CA4CsC;0BApL/B,oCAAoC"}
+{"version":3,"file":"chunk_particle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/chunk_particle_bounds.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,0CAFU,SAAS,CAwE8E;AAEjG;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CA4CsC;0BArL/B,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_avboit_voxel_fade.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The soft fade a soft-depth particle's splat fragment records into the voxel volume, for the
+ * low-resolution fragment at `voxel_position` (its `@builtin(position).xy`) of a volume
+ * `voxel_resolution` voxels wide, over the full-resolution `scene_depth`.
+ *
+ * The draw fades every full-resolution pixel against the scene behind it; one voxel covers 8×8 of
+ * them, so what the volume can hold is the fade averaged over that footprint. This takes the average
+ * of four reads at WebGPU's standard 4× multisample positions — a rotated grid, so the four fall on
+ * four different rows and four different columns and follow a floor or a wall across the voxel; the
+ * points the dynamic-mesh splat averages its coverage over, too — through the exact low-to-full
+ * mapping, `scene size / voxel_resolution`, so a frame the volume does not divide evenly is read
+ * where its voxels really lie.
+ *
+ * It used to read one texel at `8 × voxel`, the voxel's top-left corner. On a floor seen at a distance
+ * the row four pixels up is farther away by a good part of the fade range (a quarter of a metre at
+ * 10 m, a metre at 20 m, at 1080p from 1.7 m up), so the volume recorded a smoke card standing on the
+ * floor at up to 2.4× the coverage the draw gave it there: an invisible card occluding what lies
+ * behind it, the seam ledger entry 20 had removed (AVBOIT ledger entry 26). Over fifteen modelled
+ * floor contacts the corner read was off the voxel's average by 0.27 on average and 0.55 at worst; a
+ * 2×2 grid by 0.05 and 0.12; these four by 0.05 and 0.08.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_voxel_fade: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_avboit_voxel_fade.d.ts.map

package/src/shade/renderer/particles/shaders/chunk_particle_avboit_voxel_fade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_avboit_voxel_fade.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_avboit_voxel_fade.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAFU,SAAS,CA2CjB;0BArEwB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_avboit_voxel_fade.js

@@ -0,0 +1,71 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
+import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
+import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
+
+/**
+ * The soft fade a soft-depth particle's splat fragment records into the voxel volume, for the
+ * low-resolution fragment at `voxel_position` (its `@builtin(position).xy`) of a volume
+ * `voxel_resolution` voxels wide, over the full-resolution `scene_depth`.
+ *
+ * The draw fades every full-resolution pixel against the scene behind it; one voxel covers 8×8 of
+ * them, so what the volume can hold is the fade averaged over that footprint. This takes the average
+ * of four reads at WebGPU's standard 4× multisample positions — a rotated grid, so the four fall on
+ * four different rows and four different columns and follow a floor or a wall across the voxel; the
+ * points the dynamic-mesh splat averages its coverage over, too — through the exact low-to-full
+ * mapping, `scene size / voxel_resolution`, so a frame the volume does not divide evenly is read
+ * where its voxels really lie.
+ *
+ * It used to read one texel at `8 × voxel`, the voxel's top-left corner. On a floor seen at a distance
+ * the row four pixels up is farther away by a good part of the fade range (a quarter of a metre at
+ * 10 m, a metre at 20 m, at 1080p from 1.7 m up), so the volume recorded a smoke card standing on the
+ * floor at up to 2.4× the coverage the draw gave it there: an invisible card occluding what lies
+ * behind it, the seam ledger entry 20 had removed (AVBOIT ledger entry 26). Over fifteen modelled
+ * floor contacts the corner read was off the voxel's average by 0.27 on average and 0.55 at worst; a
+ * 2×2 grid by 0.05 and 0.12; these four by 0.05 and 0.08.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_voxel_fade = CodeChunk.from(
+    //language=WGSL
+    `
+fn particle_avboit_voxel_fade_at(
+    scene_depth: texture_2d<f32>,
+    point: vec2<f32>,
+    scene_size: vec2<f32>,
+    particle_view_depth: f32,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+) -> f32 {
+    let texel = vec2<i32>(clamp(point, vec2<f32>(0.0), scene_size - 1.0));
+    let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, texel, 0).r, camera);
+
+    return particle_soft_fade(scene_vd, particle_view_depth, ${PARTICLE_SOFT_FADE_RANGE});
+}
+
+fn particle_avboit_voxel_fade(
+    scene_depth: texture_2d<f32>,
+    voxel_position: vec2<f32>,
+    voxel_resolution: vec2<u32>,
+    particle_view_depth: f32,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+) -> f32 {
+    let scene_size = vec2<f32>(textureDimensions(scene_depth, 0));
+    let scale = scene_size / vec2<f32>(max(voxel_resolution, vec2<u32>(1u)));
+
+    // the voxel's top-left corner; voxel_position is its centre
+    let corner = voxel_position - 0.5;
+
+    let a = particle_avboit_voxel_fade_at(scene_depth, (corner + vec2<f32>(0.375, 0.125)) * scale, scene_size, particle_view_depth, camera);
+    let b = particle_avboit_voxel_fade_at(scene_depth, (corner + vec2<f32>(0.875, 0.375)) * scale, scene_size, particle_view_depth, camera);
+    let c = particle_avboit_voxel_fade_at(scene_depth, (corner + vec2<f32>(0.125, 0.625)) * scale, scene_size, particle_view_depth, camera);
+    let d = particle_avboit_voxel_fade_at(scene_depth, (corner + vec2<f32>(0.625, 0.875)) * scale, scene_size, particle_view_depth, camera);
+
+    return (a + b + c + d) * 0.25;
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+        chunk_particle_scene_view_depth,
+        chunk_particle_render_math,
+    ]
+);

package/src/shade/renderer/particles/shaders/shader_particle_avboit_draw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_avboit_draw.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js"],"names":[],"mappings":"AAqLA,2EAAsI;AACtI,8EAA2I;AAC3I,6EAA8I;AAE9I,mEAAmE;AACnE,yEAAwD;AAExD,mDAAmD;AACnD,2DAAsD;yCA7Lb,iEAAiE;4CAW9D,sDAAsD;iCAFjE,kCAAkC"}
+{"version":3,"file":"shader_particle_avboit_draw.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js"],"names":[],"mappings":"AAoMA,2EAAsI;AACtI,8EAA2I;AAC3I,6EAA8I;AAE9I,mEAAmE;AACnE,yEAAwD;AAExD,mDAAmD;AACnD,2DAAsD;yCA5Mb,iEAAiE;4CAa9D,sDAAsD;iCAFjE,kCAAkC"}

package/src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js

@@ -6,6 +6,8 @@ import { chunk_sample_volumetrics } from "../../deferred/chunk_sample_volumetric
 import { AVBOIT_EXTINCT_TRANSMITTANCE } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
 import { AVBOIT_WARP_STRUCT } from "../../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
 import { AVBOIT_DRAW_TARGETS } from "../../rasterize/native/avboit/avboit_draw_fragment_body.js";
+import { chunk_avboit_view_depth_to_virtual } from "../../rasterize/native/avboit/chunk_avboit_view_depth_to_virtual.js";
+import { chunk_avboit_footprint_bias } from "../../rasterize/native/avboit/chunk_avboit_footprint_bias.js";
 import { chunk_avboit_sample_transmittance } from "../../rasterize/native/avboit/chunk_avboit_sample_transmittance.js";
 import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
@@ -110,7 +112,18 @@ fn vs_general(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32
 fn fs_main(in : ParticleVertexOut) -> ParticleAVBOITDrawOutput {
     let screen_uv = in.clip.xy / vec2<f32>(f32(view.width), f32(view.height));
 
-    let transmittance = avboit_sample_transmittance(&warp, tIntegral, sLinear, screen_uv, in.view_depth);
+    // a billboard, stretched or not, is built from the camera's right and up and lies in the view plane,
+    // so its footprint is zero; a horizontal, vertical or world-facing quad seen at an angle runs
+    // through depth across a voxel (avboit_footprint_bias). An additive particle writes nothing into
+    // the volume, so nothing of its own is there to occlude it, and takes none. The derivative is
+    // taken here, in uniform control flow, whatever the blend
+    let footprint = select(
+        avboit_footprint_bias(&warp, fwidth(avboit_view_depth_to_virtual(&warp, in.view_depth))),
+        0.0,
+        in.blend == PARTICLE_BLEND_ADDITIVE,
+    );
+
+    let transmittance = avboit_sample_transmittance(&warp, tIntegral, sLinear, screen_uv, in.view_depth, footprint);
 
     if (all(transmittance <= vec3<f32>(${AVBOIT_EXTINCT_TRANSMITTANCE}))) {
         // nothing this fragment contributes survives what is in front of it; skip the shading
@@ -151,6 +164,8 @@ fn fs_main(in : ParticleVertexOut) -> ParticleAVBOITDrawOutput {
     chunk_particle_billboard_vertex,
     chunk_particle_lighting,
     chunk_sample_volumetrics,
+    chunk_avboit_view_depth_to_virtual,
+    chunk_avboit_footprint_bias,
     chunk_avboit_sample_transmittance,
 ]);
 

package/src/shade/renderer/particles/shaders/shader_particle_avboit_splat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAwGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCApJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}
+{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAmGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCA7Id,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}

package/src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js

@@ -12,11 +12,9 @@ import { AVBOIT_SPLAT_DUMMY_FORMAT } from "../../rasterize/native/avboit/shader_
 import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
 import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
-import { AVBOIT_VOXEL_DOWNSCALE } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { chunk_particle_avboit_voxel_fade } from "./chunk_particle_avboit_voxel_fade.js";
 import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
-import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
 
 /**
  * Bind group of the volume atomics; group 0 is everything the billboard vertex stage and the atlas
@@ -73,15 +71,10 @@ fn fs_main(in : ParticleVertexOut) {
     var alpha = premultiplied.a;
 
     if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
-        /*
-         The same fade the draw applies to the same fragment, so the volume records the coverage the
-         accumulators are weighted by. Sampled once per voxel: this pass rasterizes at the volume's
-         resolution, so the scene texel under the fragment is the downscale factor times out.
-        */
-        let scene_texel = vec2<i32>(in.clip.xy) * ${AVBOIT_VOXEL_DOWNSCALE};
-        let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, scene_texel, 0).r, camera);
-
-        alpha = alpha * particle_soft_fade(scene_vd, in.view_depth, ${PARTICLE_SOFT_FADE_RANGE});
+        // the fade the draw applies to the same fragment, so the volume records the coverage the
+        // accumulators are weighted by
+        let voxel_resolution = vec2<u32>(warp.voxel_width, warp.voxel_height);
+        alpha = alpha * particle_avboit_voxel_fade(scene_depth, in.clip.xy, voxel_resolution, in.view_depth, camera);
     }
 
     // the coverage the draw weights this fragment by, through the same function
@@ -110,7 +103,7 @@ fn fs_main(in : ParticleVertexOut) {
 }
 `, [
     chunk_particle_billboard_vertex,
-    chunk_particle_scene_view_depth,
+    chunk_particle_avboit_voxel_fade,
     chunk_avboit_coverage,
     chunk_avboit_transmittance_to_extinction,
     chunk_avboit_view_depth_to_physical,