@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/renderer/atmosphere/chunk_sample_transmittance_lut.js

@@ -1,33 +1,69 @@
-import {
-    chunk_texture_sample_bilinear_uv
-} from "../shader/chunk/texture/sample/chunk_texture_sample_bilinear_uv.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { chunk_sky_lut_compute_uv } from "./chunk_sky_lut_compute_uv.js";
-
-/**
- * Assumes following in the context:
- *      tSkyLutTransmittance: texture_2d<f32>
- *
- * see {@link shader_transmittance_lut}
- * @type {CodeChunk}
- */
-export const chunk_sample_transmittance_lut = CodeChunk.from(
-//language=WGSL
-    `
-fn sample_transmittance_lut(
-    pos: vec3<f32>,
-    sunDir: vec3<f32>
-) -> vec3<f32>{
-
-    let uv = sky_lut_compute_uv(pos, sunDir);
-        
-    return texture_sample_bilinear_uv(tSkyLutTransmittance, uv, 0).rgb;
-
-}    
-    `,
-    [
-        chunk_texture_sample_bilinear_uv,
-        chunk_sky_lut_compute_uv,
-    ]
-);
-
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_sky_lut_params } from "./chunk_sky_lut_params.js";
+import { chunk_sky_lut_uv } from "./chunk_sky_lut_uv.js";
+
+/**
+ * Assumes following in the context:
+ *      tSkyLutTransmittance: texture_2d<f32>   (sample type "float", i.e. filterable)
+ *      sSkyLut: sampler                        (see {@link SAMPLER_SKY_LUT})
+ *
+ * The LUT is rgba16float, which is filterable in core WebGPU -- only the 32-bit float
+ * formats need the `float32-filterable` feature -- so this goes through the texture unit
+ * rather than the 4-tap `texture_sample_bilinear_uv`. Clamp-to-edge on the sampler
+ * reproduces that function's per-corner clamping.
+ *
+ * The half-texel inset {@link chunk_sky_lut_uv} applies needs the LUT's resolution, which is
+ * read from the binding rather than passed in: the texture is the authority on its own size,
+ * and a caller cannot get it wrong.
+ *
+ * see {@link shader_transmittance_lut}
+ * @type {CodeChunk}
+ */
+export const chunk_sample_transmittance_lut_params = CodeChunk.from(
+//language=WGSL
+    `
+fn sample_transmittance_lut_params(
+    height: f32,
+    sun_cos_zenith_angle: f32
+) -> vec3<f32>{
+
+    let uv = sky_lut_uv(
+        height,
+        sun_cos_zenith_angle,
+        vec2<f32>(textureDimensions(tSkyLutTransmittance))
+    );
+
+    return textureSampleLevel(tSkyLutTransmittance, sSkyLut, uv, 0.0).rgb;
+
+}
+    `, [
+        chunk_sky_lut_uv,
+    ]
+);
+
+/**
+ * {@link chunk_sample_transmittance_lut_params} from a world-space position. A ray-march that
+ * already knows the altitude and the local up vector should build the pair itself and call
+ * the primitive, rather than have this recover them with another square root.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sample_transmittance_lut = CodeChunk.from(
+//language=WGSL
+    `
+fn sample_transmittance_lut(
+    pos: vec3<f32>,
+    sunDir: vec3<f32>
+) -> vec3<f32>{
+
+    let params = sky_lut_params(pos, sunDir);
+
+    return sample_transmittance_lut_params(params.x, params.y);
+
+}    
+    `,
+    [
+        chunk_sample_transmittance_lut_params,
+        chunk_sky_lut_params,
+    ]
+);

package/src/shade/renderer/atmosphere/chunk_sky_lut_compute_uv.d.ts

@@ -1,3 +1,16 @@
+/**
+ * {@link chunk_sky_lut_uv} straight from a world-space position, for a shader that samples a
+ * sky LUT through its own binding rather than through the `sample_*_lut_params` chunks --
+ * the volumetrics passes, which bind the same transmittance LUT under a name of their own.
+ *
+ * `resolution` is the LUT's, and it matters: the half-texel inset is what makes a lookup at
+ * either end of the range read a value that was computed there. Pass
+ * `vec2<f32>(textureDimensions(...))` of the texture being sampled, not of some other one --
+ * the transmittance and multiple-scattering LUTs are different sizes, so one uv cannot serve
+ * both.
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_sky_lut_compute_uv: CodeChunk;
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_sky_lut_compute_uv.d.ts.map

package/src/shade/renderer/atmosphere/chunk_sky_lut_compute_uv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sky_lut_compute_uv.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_sky_lut_compute_uv.js"],"names":[],"mappings":"AAOA,iDA2BC;0BA7ByB,iCAAiC"}
+{"version":3,"file":"chunk_sky_lut_compute_uv.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_sky_lut_compute_uv.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,uCAFU,SAAS,CAmBlB;0BAlCyB,iCAAiC"}

package/src/shade/renderer/atmosphere/chunk_sky_lut_compute_uv.js

@@ -1,35 +1,35 @@
-import { ATMOSPHERE_HEIGHT_DECLARATION } from "../shader/chunk/atmosphere/ATMOSPHERE_HEIGHT_DECLARATION.js";
-import { chunk_atmosphere_height } from "../shader/chunk/atmosphere/chunk_atmosphere_height.js";
-import {
-    chunk_position_relative_to_planet_center
-} from "../shader/chunk/atmosphere/chunk_position_relative_to_planet_center.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-
-export const chunk_sky_lut_compute_uv = CodeChunk.from(
-    //language=WGSL
-    `
-fn sky_lut_compute_uv(
-    pos: vec3<f32>,
-    sunDir: vec3<f32>
-) -> vec2<f32> {
-    let height = atmosphere_height(pos);
-    
-    let up = normalize(
-        position_relative_to_planet_center(pos)
-    );
-    
-    let sunCosZenithAngle = dot(sunDir, up);
-    
-    let uv = vec2(
-        saturate(0.5 + 0.5*sunCosZenithAngle),
-        saturate(height/ATMOSPHERE_HEIGHT)
-    );
-    
-    return uv;
-}
-    `, [
-        chunk_atmosphere_height,
-        ATMOSPHERE_HEIGHT_DECLARATION,
-        chunk_position_relative_to_planet_center,
-    ]
-)
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_sky_lut_params } from "./chunk_sky_lut_params.js";
+import { chunk_sky_lut_uv } from "./chunk_sky_lut_uv.js";
+
+/**
+ * {@link chunk_sky_lut_uv} straight from a world-space position, for a shader that samples a
+ * sky LUT through its own binding rather than through the `sample_*_lut_params` chunks --
+ * the volumetrics passes, which bind the same transmittance LUT under a name of their own.
+ *
+ * `resolution` is the LUT's, and it matters: the half-texel inset is what makes a lookup at
+ * either end of the range read a value that was computed there. Pass
+ * `vec2<f32>(textureDimensions(...))` of the texture being sampled, not of some other one --
+ * the transmittance and multiple-scattering LUTs are different sizes, so one uv cannot serve
+ * both.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_compute_uv = CodeChunk.from(
+    //language=WGSL
+    `
+fn sky_lut_compute_uv(
+    pos: vec3<f32>,
+    sunDir: vec3<f32>,
+    resolution: vec2<f32>
+) -> vec2<f32> {
+
+    let params = sky_lut_params(pos, sunDir);
+
+    return sky_lut_uv(params.x, params.y, resolution);
+}
+    `, [
+        chunk_sky_lut_params,
+        chunk_sky_lut_uv,
+    ]
+)

package/src/shade/renderer/atmosphere/chunk_sky_lut_params.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The pair every sky LUT is addressed by — altitude in `x`, cosine of the sun's zenith angle
+ * in `y` — recovered from a world-space position.
+ *
+ * Costs the square root a ray-march step has usually already paid for: a march that is
+ * stepping a planet-relative position should build the pair itself and call the
+ * `sample_*_lut_params` primitives directly rather than come through here.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_params: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sky_lut_params.d.ts.map

package/src/shade/renderer/atmosphere/chunk_sky_lut_params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sky_lut_params.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_sky_lut_params.js"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,mCAFU,SAAS,CAuBjB;0BAjCwB,iCAAiC"}

package/src/shade/renderer/atmosphere/chunk_sky_lut_params.js

@@ -0,0 +1,38 @@
+import { ATMOSPHERE_RADII_DECLARATION } from "../shader/chunk/atmosphere/ATMOSPHERE_RADII_DECLARATION.js";
+import {
+    chunk_position_relative_to_planet_center
+} from "../shader/chunk/atmosphere/chunk_position_relative_to_planet_center.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * The pair every sky LUT is addressed by — altitude in `x`, cosine of the sun's zenith angle
+ * in `y` — recovered from a world-space position.
+ *
+ * Costs the square root a ray-march step has usually already paid for: a march that is
+ * stepping a planet-relative position should build the pair itself and call the
+ * `sample_*_lut_params` primitives directly rather than come through here.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_params = CodeChunk.from(
+    //language=WGSL
+    `
+fn sky_lut_params(
+    pos: vec3<f32>,
+    sunDir: vec3<f32>
+) -> vec2<f32> {
+
+    let rel = position_relative_to_planet_center(pos);
+
+    let radius = length(rel);
+
+    return vec2(
+        radius - ATMOSPHERE_GROUND_RADIUS,
+        dot(sunDir, rel / radius)
+    );
+}
+    `, [
+        chunk_position_relative_to_planet_center,
+        ATMOSPHERE_RADII_DECLARATION,
+    ]
+);

package/src/shade/renderer/atmosphere/chunk_sky_lut_texel_to_unit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which point of the parameter range a sky LUT texel stands for: the generator's half of the
+ * mapping {@link chunk_sky_lut_uv} inverts. Texel 0 carries the bottom of the range and the
+ * last texel the top, so a lookup at either end reads a value that was actually computed
+ * there rather than one from half a texel inside.
+ *
+ * `texel` is the integer index, not a texel centre — pass the invocation's own coordinate,
+ * not `coord.xy` from a fragment shader.
+ *
+ * Both components come back in [0,1]; the caller maps them onto the physical ranges (the sun
+ * zenith cosine and the altitude).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_texel_to_unit: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sky_lut_texel_to_unit.d.ts.map

package/src/shade/renderer/atmosphere/chunk_sky_lut_texel_to_unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sky_lut_texel_to_unit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_sky_lut_texel_to_unit.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,0CAFU,SAAS,CAcjB;0BA5BwB,iCAAiC"}

package/src/shade/renderer/atmosphere/chunk_sky_lut_texel_to_unit.js

@@ -0,0 +1,29 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Which point of the parameter range a sky LUT texel stands for: the generator's half of the
+ * mapping {@link chunk_sky_lut_uv} inverts. Texel 0 carries the bottom of the range and the
+ * last texel the top, so a lookup at either end reads a value that was actually computed
+ * there rather than one from half a texel inside.
+ *
+ * `texel` is the integer index, not a texel centre — pass the invocation's own coordinate,
+ * not `coord.xy` from a fragment shader.
+ *
+ * Both components come back in [0,1]; the caller maps them onto the physical ranges (the sun
+ * zenith cosine and the altitude).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_texel_to_unit = CodeChunk.from(
+    //language=WGSL
+    `
+fn sky_lut_texel_to_unit(
+    texel: vec2<f32>,
+    resolution: vec2<f32>
+) -> vec2<f32> {
+
+    // a one-texel axis has no range to spread: it stands for the bottom of it
+    return texel / max(resolution - 1.0, vec2(1.0));
+}
+    `
+);

package/src/shade/renderer/atmosphere/chunk_sky_lut_uv.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parameterisation shared by the transmittance and multiple-scattering LUTs: `x` is the
+ * cosine of the sun's zenith angle remapped to [0,1], `y` is the altitude as a fraction of
+ * the atmosphere's thickness.
+ *
+ * The result is a texture coordinate, not the raw parameter pair. A LUT of N texels can only
+ * store N samples of a continuous range, and the two ends of that range have to land on the
+ * two end texels: without the half-texel inset here, a lookup at altitude zero addresses the
+ * texel a generator wrote for the centre of the first row -- 780 m up in the 64-row
+ * transmittance LUT, which is a tenth of a Rayleigh scale height. Hillaire spends
+ * `fromUnitToSubUvs` / `fromSubUvsToUnit` on the same problem.
+ *
+ * {@link chunk_sky_lut_texel_to_unit} is the other half, and the two have to agree — a
+ * generator that does not use it writes a LUT this addresses wrongly. `sky_lut_uv.spec.js`
+ * round-trips them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_uv: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sky_lut_uv.d.ts.map

package/src/shade/renderer/atmosphere/chunk_sky_lut_uv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sky_lut_uv.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/chunk_sky_lut_uv.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,+BAFU,SAAS,CAsBjB;0BAxCwB,iCAAiC"}

package/src/shade/renderer/atmosphere/chunk_sky_lut_uv.js

@@ -0,0 +1,42 @@
+import { ATMOSPHERE_HEIGHT_DECLARATION } from "../shader/chunk/atmosphere/ATMOSPHERE_HEIGHT_DECLARATION.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Parameterisation shared by the transmittance and multiple-scattering LUTs: `x` is the
+ * cosine of the sun's zenith angle remapped to [0,1], `y` is the altitude as a fraction of
+ * the atmosphere's thickness.
+ *
+ * The result is a texture coordinate, not the raw parameter pair. A LUT of N texels can only
+ * store N samples of a continuous range, and the two ends of that range have to land on the
+ * two end texels: without the half-texel inset here, a lookup at altitude zero addresses the
+ * texel a generator wrote for the centre of the first row -- 780 m up in the 64-row
+ * transmittance LUT, which is a tenth of a Rayleigh scale height. Hillaire spends
+ * `fromUnitToSubUvs` / `fromSubUvsToUnit` on the same problem.
+ *
+ * {@link chunk_sky_lut_texel_to_unit} is the other half, and the two have to agree — a
+ * generator that does not use it writes a LUT this addresses wrongly. `sky_lut_uv.spec.js`
+ * round-trips them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sky_lut_uv = CodeChunk.from(
+    //language=WGSL
+    `
+fn sky_lut_uv(
+    height: f32,
+    sun_cos_zenith_angle: f32,
+    resolution: vec2<f32>
+) -> vec2<f32> {
+
+    let unit = vec2(
+        saturate(0.5 + 0.5 * sun_cos_zenith_angle),
+        saturate(height / ATMOSPHERE_HEIGHT)
+    );
+
+    // unit 0 lands on the centre of texel 0, unit 1 on the centre of the last one
+    return (unit * (resolution - 1.0) + 0.5) / resolution;
+}
+    `, [
+        ATMOSPHERE_HEIGHT_DECLARATION,
+    ]
+);

package/src/shade/renderer/atmosphere/shader_multiscatter_lut.d.ts

@@ -1,3 +1,3 @@
-export const shader_multiscatter_lut: ImageShader;
-import { ImageShader } from "../shader/ImageShader.js";
+export const shader_multiscatter_lut: ComputeShader;
+import { ComputeShader } from "../shader/ComputeShader.js";
 //# sourceMappingURL=shader_multiscatter_lut.d.ts.map

package/src/shade/renderer/atmosphere/shader_multiscatter_lut.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_multiscatter_lut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/shader_multiscatter_lut.js"],"names":[],"mappings":"AAwEA,kDAWG;4BA9EyB,0BAA0B"}
+{"version":3,"file":"shader_multiscatter_lut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/shader_multiscatter_lut.js"],"names":[],"mappings":"AA+JA,oDAIG;8BA/J2B,4BAA4B"}

package/src/shade/renderer/atmosphere/shader_multiscatter_lut.js

@@ -1,84 +1,164 @@
-import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-import { ATMOSPHERE_HEIGHT_DECLARATION } from "../shader/chunk/atmosphere/ATMOSPHERE_HEIGHT_DECLARATION.js";
-import { chunk_safe_acos } from "../shader/chunk/math/chunk_safe_acos.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ImageShader } from "../shader/ImageShader.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { chunk_get_multiscatter_values } from "./chunk_get_multiscatter_values.js";
-
-const SETTINGS_STRUCT = WebGPUStruct.from({
-    // how many ray-marching steps to take per pixel of LUT, more steps = higher accuracy but lower performance
-    steps: u32,
-    sqrt_samples: u32,
-});
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("settings", SETTINGS_STRUCT)
-    .addTexture("tSkyLutTransmittance")
-;
-
-
-/**
- * the multiple-scattering LUT. Each pixel coordinate corresponds to a height and sun zenith angle, and
- * the value is the multiple scattering approximation (Psi_ms from the paper, Eq. 10).
- *
- * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
- * @see https://www.shadertoy.com/view/slSXRW
- * @type {CodeChunk}
- */
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@fragment
-fn main(
-    @builtin(position) coord: vec4<f32>,
-    @location(0) uv: vec2<f32>,
-) -> @location(0) vec4<f32> {
-        
-    
-    let sunCosTheta = 2.0*uv.x - 1.0;
-    let sunTheta = safe_acos(sunCosTheta);
-    
-    let height = ATMOSPHERE_HEIGHT*uv.y;
-    
-    let pos = vec3(0.0, height, 0.0); 
-    let sunDir = normalize(vec3(0.0, sunCosTheta, -sin(sunTheta)));
-    
-    var lum:vec3<f32>;
-    var f_ms:vec3<f32>;
-    
-    get_multiscatter_values(
-        pos,
-        sunDir,
-        f32(settings.steps),
-        settings.sqrt_samples,
-        &lum, &f_ms
-    );
-    
-    // Equation 10 from the paper.
-    let psi = lum  / (1.0 - f_ms); 
-    
-    return vec4(psi, 1.0);
-}
-    `, [
-        chunk_safe_acos,
-        ATMOSPHERE_HEIGHT_DECLARATION,
-        chunk_get_multiscatter_values,
-    ]
-)
-
-export const shader_multiscatter_lut = new ImageShader({
-    descriptor: ShaderDescriptor.from({
-        label: "Sky / multi-scatter LUT",
-        body,
-        resources,
-    }),
-    targets: [
-        {
-            format: "rgba16float"
-        }
-    ]
-});
+import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
+import { ATMOSPHERE_HEIGHT_DECLARATION } from "../shader/chunk/atmosphere/ATMOSPHERE_HEIGHT_DECLARATION.js";
+import { chunk_safe_acos } from "../shader/chunk/math/chunk_safe_acos.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_get_multiscatter_values } from "./chunk_get_multiscatter_values.js";
+import { chunk_multiscatter_sample_direction } from "./chunk_multiscatter_sample_direction.js";
+import { chunk_sky_lut_texel_to_unit } from "./chunk_sky_lut_texel_to_unit.js";
+import {
+    MULTISCATTER_LUT_DIRECTION_COUNT,
+    MULTISCATTER_LUT_MAX_SUBGROUP_PARTIALS
+} from "./MULTISCATTER_LUT_CONFIG.js";
+import { SAMPLER_SKY_LUT } from "./SAMPLER_SKY_LUT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    // "float" rather than the default "unfilterable-float": rgba16float is filterable in
+    // core WebGPU, so the LUT goes through the texture unit instead of a 4-tap manual
+    // bilinear.
+    .addTexture("tSkyLutTransmittance", "float")
+    .addSampler("sSkyLut", "filtering", SAMPLER_SKY_LUT)
+    .addStorageTexture("tSkyLutMultiscatterOut", "rgba16float")
+;
+
+
+/**
+ * the multiple-scattering LUT. Each pixel coordinate corresponds to a height and sun zenith angle, and
+ * the value is the multiple scattering approximation (Psi_ms from the paper, Eq. 10).
+ *
+ * One workgroup per LUT texel, one thread per direction, mirroring Hillaire's
+ * `[numthreads(1,1,64)]` `NewMultiScattCS`. The 64 directions used to be a serial loop
+ * inside a fragment shader, which left the whole pass with 32*32 = 1024 threads of
+ * parallelism -- a few dozen waves, one per scheduler at best, with nothing to hide the
+ * latency of the transmittance fetches. Per-thread it is now a single direction's 20-step
+ * march.
+ *
+ * The per-direction results are summed with `subgroupAdd` and then across subgroups through
+ * workgroup memory; Hillaire uses a six-step groupshared log-reduction, which the subgroup
+ * op collapses into one instruction plus a handful of partials.
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
+ * @see https://www.shadertoy.com/view/slSXRW
+ * @type {CodeChunk}
+ */
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const MULTISCATTER_DIRECTION_COUNT = ${MULTISCATTER_LUT_DIRECTION_COUNT}u;
+const MULTISCATTER_MAX_SUBGROUP_PARTIALS = ${MULTISCATTER_LUT_MAX_SUBGROUP_PARTIALS}u;
+
+var<workgroup> wg_partial_count: atomic<u32>;
+var<workgroup> wg_lum: array<vec3<f32>, MULTISCATTER_MAX_SUBGROUP_PARTIALS>;
+var<workgroup> wg_fms: array<vec3<f32>, MULTISCATTER_MAX_SUBGROUP_PARTIALS>;
+
+@compute @workgroup_size(${MULTISCATTER_LUT_DIRECTION_COUNT}, 1, 1)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) thread_index: u32,
+) {
+
+    if (thread_index == 0u) {
+        atomicStore(&wg_partial_count, 0u);
+    }
+
+    // Every thread is here together anyway, so the counter's initialisation costs nothing
+    // beyond the barrier itself. WGSL does not promise workgroup variables start zeroed.
+    workgroupBarrier();
+
+    // one workgroup per texel; the dispatch is sized from the texture, so this is in range
+    let texel = workgroup_id.xy;
+
+    let lut_size = vec2<f32>(textureDimensions(tSkyLutMultiscatterOut));
+
+    // The point of each range this texel stands for: texel 0 carries the bottom and the last
+    // texel the top, which is what lets a lookup at either end read a value computed there
+    // rather than one from half a texel inside. sky_lut_uv is the other half of this.
+    let unit = sky_lut_texel_to_unit(vec2<f32>(texel), lut_size);
+
+    let sunCosTheta = 2.0*unit.x - 1.0;
+    let sunTheta = safe_acos(sunCosTheta);
+
+    let height = ATMOSPHERE_HEIGHT*unit.y;
+
+    let pos = vec3(0.0, height, 0.0);
+    let sunDir = normalize(vec3(0.0, sunCosTheta, -sin(sunTheta)));
+
+    // pos on the +y axis and sunDir with a zero x component are exactly the preconditions
+    // multiscatter_sample_direction's half-azimuth sample set needs
+    let rayDir = multiscatter_sample_direction(thread_index);
+
+    var lum:vec3<f32>;
+    var f_ms:vec3<f32>;
+
+    get_multiscatter_values(pos, sunDir, rayDir, &lum, &f_ms);
+
+    // Uniform control flow up to here, so every one of the workgroup's threads is an active
+    // lane and the subgroup sum covers all of them.
+    let lum_subgroup = subgroupAdd(lum);
+    let fms_subgroup = subgroupAdd(f_ms);
+
+    // subgroupElect picks exactly one active invocation per subgroup, and the slot it claims
+    // is whichever the counter hands out. Deriving the slot from local_invocation_index /
+    // subgroup_size instead would assume invocations are packed into subgroups in contiguous
+    // index order, which WGSL leaves unspecified: a mapping that is not contiguous blocks
+    // would collide two subgroups onto one slot and silently drop a partial sum. Which slot
+    // a subgroup lands in does not matter, only that it gets its own.
+    //
+    // Every lane holds the same subgroup sum, so letting them all store it would be a data
+    // race on one address even though the values agree.
+    if (subgroupElect()) {
+        let slot = atomicAdd(&wg_partial_count, 1u);
+
+        wg_lum[slot] = lum_subgroup;
+        wg_fms[slot] = fms_subgroup;
+    }
+
+    workgroupBarrier();
+
+    if (thread_index != 0u) {
+        return;
+    }
+
+    // WGSL pins the subgroup size to a power of two in [4, 128], so the workgroup cannot hold
+    // more subgroups than the partials array has room for. The clamp keeps a driver that
+    // broke that promise reading initialised slots rather than garbage.
+    let partial_count = min(atomicLoad(&wg_partial_count), MULTISCATTER_MAX_SUBGROUP_PARTIALS);
+
+    var lum_total = vec3(0.0);
+    var fms_total = vec3(0.0);
+
+    for (var i = 0u; i < partial_count; i++) {
+        lum_total += wg_lum[i];
+        fms_total += wg_fms[i];
+    }
+
+    // The directions carry equal solid angle, so the mean over them is the spherical average
+    // the paper's uniform phase reduces to.
+    let inv_samples = 1.0 / f32(MULTISCATTER_DIRECTION_COUNT);
+
+    lum_total *= inv_samples;
+    fms_total *= inv_samples;
+
+    // Equation 10 from the paper.
+    let psi = lum_total / (1.0 - fms_total);
+
+    textureStore(tSkyLutMultiscatterOut, texel, vec4(psi, 1.0));
+}
+    `, [
+        chunk_safe_acos,
+        ATMOSPHERE_HEIGHT_DECLARATION,
+        chunk_multiscatter_sample_direction,
+        chunk_sky_lut_texel_to_unit,
+        chunk_get_multiscatter_values,
+    ]
+);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+export const shader_multiscatter_lut = ComputeShader.from({
+    label: "Sky / multi-scatter LUT",
+    body,
+    resources,
+});

package/src/shade/renderer/atmosphere/shader_sky_irradiance_lut.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_sky_irradiance_lut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/shader_sky_irradiance_lut.js"],"names":[],"mappings":"AAiMA,oDAWG;4BA3KyB,0BAA0B"}
+{"version":3,"file":"shader_sky_irradiance_lut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/shader_sky_irradiance_lut.js"],"names":[],"mappings":"AA4MA,oDAWG;4BA1LyB,0BAA0B"}