@woosh/meep-engine 3.34.0 → 3.36.0

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

@@ -0,0 +1,39 @@
+/**
+ * The froxel irradiance volume: the light a transparent surface standing in a froxel receives, for
+ * surfaces the lighting pass cannot see — the particles. The froxel GI stage (`gi/`) starts it with
+ * whatever the renderer's indirect lighting mode says a point there receives — the environment,
+ * Brick4, the light probe volume — and `shader_volumetrics_build_lighting` adds, in the same loop
+ * that lights the fog, every directional, point and spot light, their shadows, and the fog's own
+ * attenuation toward each light. idTech 8 builds the same thing in the same pass ("Froxels
+ * Irradiance Volume", Sousa, SIGGRAPH 2025, p.29).
+ *
+ * Stored in the Metro Exodus L1 encoding (`l1i/`): luma as SH2 — four coefficients — and chroma as
+ * its constant band only. Two lights of different colours from opposite sides therefore light both
+ * sides in their luminance-weighted mix, not one colour each; that is the price of 6 coefficients
+ * instead of 12.
+ *
+ * Every light is added as a delta — all of its irradiance from one direction — and scaled by
+ * `1/(2 pi)`, which is the scale under which `resolve_irradiance_sh_to_diffuse(Y, CoCg, n)` returns
+ * `E(n) / pi`: the Lambertian radiance of a unit-albedo surface facing `n`. With SH2 that is
+ * `E * max(0, 1/4 + cos(theta)/2)` per light, over `pi` — the band-limited clamped cosine, a quarter
+ * dim at the peak and a quarter lit a right angle past the terminator.
+ *
+ * - `volumetrics_irradiance_sh_add(sh, irradiance, direction_to_light)` — one light's contribution,
+ *   `irradiance` being what reaches the point at normal incidence and `direction_to_light` a unit
+ *   vector pointing toward the light.
+ * - `volumetrics_irradiance_sh_add_radiance(sh, radiance)` — a whole radiance field arriving at the
+ *   point, as RGB SH2: coefficients of radiance, not cosine-convolved, ordered `[DC, y, z, x]` in
+ *   the project's all-positive basis (`sh2_basis_at`). The form every GI source hands over — the
+ *   probes of Brick4 and of the light probe volume, and `GPULightCollection.environment_sh`. A light
+ *   is the delta field `E sh2_basis_at(l)`, and adding it this way adds exactly what
+ *   `volumetrics_irradiance_sh_add` does.
+ * - `volumetrics_irradiance_sh_storable(sh)` — what an `rgba16float` volume can hold. A clustered
+ *   light close to a froxel exceeds half precision on its own and stores as +Inf, and an infinite
+ *   luma times a zero band-1 basis is a NaN; either would reach every particle sampling that froxel.
+ *   Non-finite coefficients become 0 and the rest are clamped to the half range.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_irradiance_sh: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_irradiance_sh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_irradiance_sh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_irradiance_sh.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,SAAS,CA+DjB;0BAnGwB,iCAAiC"}

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

@@ -0,0 +1,107 @@
+import { F16_MAX_DEFINITION } from "../shader/chunk/math/F16_MAX_DEFINITION.js";
+import { F32_MAX_DEFINITION } from "../shader/chunk/math/F32_MAX_DEFINITION.js";
+import {
+    chunk_convert_to_irradiance_sh,
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { chunk_rgb_to_YCoCg } from "../shader/chunk/color/YCoCg/chunk_rgb_to_YCoCg.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * The froxel irradiance volume: the light a transparent surface standing in a froxel receives, for
+ * surfaces the lighting pass cannot see — the particles. The froxel GI stage (`gi/`) starts it with
+ * whatever the renderer's indirect lighting mode says a point there receives — the environment,
+ * Brick4, the light probe volume — and `shader_volumetrics_build_lighting` adds, in the same loop
+ * that lights the fog, every directional, point and spot light, their shadows, and the fog's own
+ * attenuation toward each light. idTech 8 builds the same thing in the same pass ("Froxels
+ * Irradiance Volume", Sousa, SIGGRAPH 2025, p.29).
+ *
+ * Stored in the Metro Exodus L1 encoding (`l1i/`): luma as SH2 — four coefficients — and chroma as
+ * its constant band only. Two lights of different colours from opposite sides therefore light both
+ * sides in their luminance-weighted mix, not one colour each; that is the price of 6 coefficients
+ * instead of 12.
+ *
+ * Every light is added as a delta — all of its irradiance from one direction — and scaled by
+ * `1/(2 pi)`, which is the scale under which `resolve_irradiance_sh_to_diffuse(Y, CoCg, n)` returns
+ * `E(n) / pi`: the Lambertian radiance of a unit-albedo surface facing `n`. With SH2 that is
+ * `E * max(0, 1/4 + cos(theta)/2)` per light, over `pi` — the band-limited clamped cosine, a quarter
+ * dim at the peak and a quarter lit a right angle past the terminator.
+ *
+ * - `volumetrics_irradiance_sh_add(sh, irradiance, direction_to_light)` — one light's contribution,
+ *   `irradiance` being what reaches the point at normal incidence and `direction_to_light` a unit
+ *   vector pointing toward the light.
+ * - `volumetrics_irradiance_sh_add_radiance(sh, radiance)` — a whole radiance field arriving at the
+ *   point, as RGB SH2: coefficients of radiance, not cosine-convolved, ordered `[DC, y, z, x]` in
+ *   the project's all-positive basis (`sh2_basis_at`). The form every GI source hands over — the
+ *   probes of Brick4 and of the light probe volume, and `GPULightCollection.environment_sh`. A light
+ *   is the delta field `E sh2_basis_at(l)`, and adding it this way adds exactly what
+ *   `volumetrics_irradiance_sh_add` does.
+ * - `volumetrics_irradiance_sh_storable(sh)` — what an `rgba16float` volume can hold. A clustered
+ *   light close to a froxel exceeds half precision on its own and stores as +Inf, and an infinite
+ *   luma times a zero band-1 basis is a NaN; either would reach every particle sampling that froxel.
+ *   Non-finite coefficients become 0 and the rest are clamped to the half range.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_irradiance_sh = CodeChunk.from(
+    //language=WGSL
+    `
+const VOLUMETRICS_IRRADIANCE_SH_SCALE : f32 = 0.15915494309189535; // 1 / (2 pi)
+
+fn volumetrics_irradiance_sh_add(
+    sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
+    irradiance: vec3<f32>,
+    direction_to_light: vec3<f32>,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    let light = convert_to_irradiance_sh(irradiance * VOLUMETRICS_IRRADIANCE_SH_SCALE, direction_to_light);
+
+    return ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "sh.CoCg + light.CoCg",
+        Y: "sh.Y + light.Y",
+    })};
+}
+
+fn volumetrics_irradiance_sh_add_radiance(
+    sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
+    radiance: array<vec3<f32>, 4>,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    // luma carries all four coefficients, chroma the constant band only; YCoCg is linear, so the
+    // transform goes through the coefficients as it would through the colours
+    let c0 = rgb_to_YCoCg(radiance[0]);
+
+    // the Metro layout is (x, y, z, constant); the basis order is (constant, y, z, x)
+    let Y = vec4<f32>(
+        rgb_to_YCoCg(radiance[3]).x,
+        rgb_to_YCoCg(radiance[1]).x,
+        rgb_to_YCoCg(radiance[2]).x,
+        c0.x,
+    );
+
+    // the chroma a light adds is its irradiance's own, not times the band-0 basis constant
+    const BAND_0_BASIS : f32 = 0.28209479177387814;
+
+    return ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "sh.CoCg + c0.yz * (VOLUMETRICS_IRRADIANCE_SH_SCALE / BAND_0_BASIS)",
+        Y: "sh.Y + Y * VOLUMETRICS_IRRADIANCE_SH_SCALE",
+    })};
+}
+
+fn volumetrics_irradiance_sh_storable(sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref}) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    // the comparison is what WGSL defines for a NaN; clamp is not
+    let Y_finite = (sh.Y == sh.Y) & (abs(sh.Y) < vec4<f32>(F32_MAX));
+    let CoCg_finite = (sh.CoCg == sh.CoCg) & (abs(sh.CoCg) < vec2<f32>(F32_MAX));
+
+    return ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "select(vec2<f32>(0.0), clamp(sh.CoCg, vec2<f32>(-F16_MAX), vec2<f32>(F16_MAX)), CoCg_finite)",
+        Y: "select(vec4<f32>(0.0), clamp(sh.Y, vec4<f32>(-F16_MAX), vec4<f32>(F16_MAX)), Y_finite)",
+    })};
+}
+
+`, [
+        chunk_convert_to_irradiance_sh,
+        chunk_rgb_to_YCoCg,
+        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+        F16_MAX_DEFINITION,
+        F32_MAX_DEFINITION,
+    ]
+);

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_froxel_centre_ws.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `volumetrics_froxel_centre_ws(voxel, resolution)` — the world position a froxel's value stands for:
+ * its column's centre, at the depth its slab's content sits at (`volumetrics_froxel_content_offset`),
+ * which is where the lighting pass's jittered samples average to and where
+ * `volumetrics_position_world_to_froxel_uvw` puts the froxel's texel centre. A froxel GI module
+ * whose answer depends on position asks it there; GI is smooth enough across a froxel that one
+ * sample is all of it.
+ *
+ * The enclosing shader binds `camera` and `volumetrics_metadata` under those names.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_centre_ws: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_froxel_centre_ws.d.ts.map

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_froxel_centre_ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_froxel_centre_ws.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/chunk_volumetrics_froxel_centre_ws.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;GAWG;AACH,iDAFU,SAAS,CAyBjB;0BAvCwB,oCAAoC"}

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_froxel_centre_ws.js

@@ -0,0 +1,44 @@
+import { chunk_cluster_depth_from_z_slice } from "../../light/cluster/chunk_cluster_depth_from_z_slice.js";
+import { chunk_camera_ray_from_uv } from "../../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { RAY_STRUCT } from "../../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { chunk_texel_coordinate_to_uv } from "../../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_camera_ray_planar_depth_scale } from "../chunk_camera_ray_planar_depth_scale.js";
+import { chunk_volumetrics_froxel_content_offset } from "../chunk_volumetrics_froxel_content_offset.js";
+
+/**
+ * `volumetrics_froxel_centre_ws(voxel, resolution)` — the world position a froxel's value stands for:
+ * its column's centre, at the depth its slab's content sits at (`volumetrics_froxel_content_offset`),
+ * which is where the lighting pass's jittered samples average to and where
+ * `volumetrics_position_world_to_froxel_uvw` puts the froxel's texel centre. A froxel GI module
+ * whose answer depends on position asks it there; GI is smooth enough across a froxel that one
+ * sample is all of it.
+ *
+ * The enclosing shader binds `camera` and `volumetrics_metadata` under those names.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_centre_ws = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_froxel_centre_ws(voxel: vec3<u32>, resolution: vec3<u32>) -> vec3<f32> {
+    let curve = volumetrics_metadata.froxel_cluster_parameters;
+    let near_far = camera.clip_near_far;
+
+    let slice = f32(voxel.z) + volumetrics_froxel_content_offset(curve.z);
+    let view_depth = clamp(cluster_depth_from_z_slice(slice, curve, f32(resolution.z)), near_far.x, near_far.y);
+
+    let ray = camera_ray_from_uv(texel_coordinate_to_uv(vec2<f32>(voxel.xy), resolution.xy), camera);
+
+    // planar depth to a distance along the ray, as the lighting pass does
+    return ray.origin + ray.direction * (view_depth * camera_ray_planar_depth_scale(ray.direction, camera));
+}
+`, [
+        RAY_STRUCT.declaration_chunk,
+        chunk_volumetrics_froxel_content_offset,
+        chunk_cluster_depth_from_z_slice,
+        chunk_camera_ray_from_uv,
+        chunk_texel_coordinate_to_uv,
+        chunk_camera_ray_planar_depth_scale,
+    ]
+);

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_gi.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What every froxel GI module shares. A module is one concrete compute shader per indirect lighting
+ * mode (`shader_volumetrics_gi_ibl`, `_brick4`, `_lpv`), one thread per froxel: it asks its mode what
+ * radiance arrives at the froxel, as RGB SH2, and hands the answer to `volumetrics_gi_store`. That
+ * starts the froxel irradiance volume, and `shader_volumetrics_build_lighting` adds the lights to it.
+ * A new mode is one more module: nothing downstream knows which mode wrote the volume.
+ *
+ * `volumetrics_froxel_centre_ws` (`chunk_volumetrics_froxel_centre_ws`) says where a froxel is, for a
+ * mode whose answer depends on position; `volumetrics_gi_store(voxel, radiance)` — scales the field by `INDIRECT_LIGHT_INTENSITY`, as the
+ *   deferred and forward paths scale their indirect light, encodes it as the volume stores light
+ *   (`volumetrics_irradiance_sh_add_radiance`) and writes it to `tGIY` / `tGICoCg`.
+ *
+ * The enclosing shader binds `tGIY` and `tGICoCg` under those names.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_gi: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_gi.d.ts.map

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_gi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_gi.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/chunk_volumetrics_gi.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;GAeG;AACH,mCAFU,SAAS,CA0BjB;0BA5CwB,oCAAoC"}

package/src/shade/renderer/volumetrics/gi/chunk_volumetrics_gi.js

@@ -0,0 +1,48 @@
+import {
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { INDIRECT_LIGHT_INTENSITY } from "../../deferred/INDIRECT_LIGHT_INTENSITY.js";
+import { chunk_volumetrics_irradiance_sh } from "../chunk_volumetrics_irradiance_sh.js";
+
+/**
+ * What every froxel GI module shares. A module is one concrete compute shader per indirect lighting
+ * mode (`shader_volumetrics_gi_ibl`, `_brick4`, `_lpv`), one thread per froxel: it asks its mode what
+ * radiance arrives at the froxel, as RGB SH2, and hands the answer to `volumetrics_gi_store`. That
+ * starts the froxel irradiance volume, and `shader_volumetrics_build_lighting` adds the lights to it.
+ * A new mode is one more module: nothing downstream knows which mode wrote the volume.
+ *
+ * `volumetrics_froxel_centre_ws` (`chunk_volumetrics_froxel_centre_ws`) says where a froxel is, for a
+ * mode whose answer depends on position; `volumetrics_gi_store(voxel, radiance)` — scales the field by `INDIRECT_LIGHT_INTENSITY`, as the
+ *   deferred and forward paths scale their indirect light, encodes it as the volume stores light
+ *   (`volumetrics_irradiance_sh_add_radiance`) and writes it to `tGIY` / `tGICoCg`.
+ *
+ * The enclosing shader binds `tGIY` and `tGICoCg` under those names.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_gi = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_gi_store(voxel: vec3<u32>, radiance: array<vec3<f32>, 4>) {
+    const INDIRECT_INTENSITY : f32 = ${INDIRECT_LIGHT_INTENSITY};
+
+    let scaled = array<vec3<f32>, 4>(
+        radiance[0] * INDIRECT_INTENSITY,
+        radiance[1] * INDIRECT_INTENSITY,
+        radiance[2] * INDIRECT_INTENSITY,
+        radiance[3] * INDIRECT_INTENSITY,
+    );
+
+    var sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+
+    let stored = volumetrics_irradiance_sh_storable(volumetrics_irradiance_sh_add_radiance(sh, scaled));
+
+    textureStore(tGIY, voxel, stored.Y);
+    textureStore(tGICoCg, voxel, vec4<f32>(stored.CoCg, 0.0, 0.0));
+}
+`, [
+        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+        chunk_volumetrics_irradiance_sh,
+    ]
+);

package/src/shade/renderer/volumetrics/gi/graph_build_froxel_gi.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The froxel GI stage: the renderer's indirect lighting at every froxel, as the froxel irradiance
+ * volume encodes light, for `shader_volumetrics_build_lighting` to add the lights to. One module per
+ * mode (see `chunk_volumetrics_gi`); this picks the one `indirect_lighting_mode` names and binds its
+ * source from the scene.
+ *
+ * @param {object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {ShadeIndirectLightingMode} options.indirect_lighting_mode
+ * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene_ctx the GI sources:
+ *   `lights.environment_sh`, `volumetric_light_map`, `light_probe_volume`
+ * @param {import("../../camera/GPUCameraContext.js").GPUCameraContext} options.camera
+ * @param {number} options.volumetrics_metadata graph handle
+ * @param {number[]} options.resolution the froxel grid
+ * @returns {{Y: number, CoCg: number}} handles of the GI volume, in the froxel irradiance encoding
+ */
+export function graph_build_froxel_gi({ graph, indirect_lighting_mode, scene_ctx, camera, volumetrics_metadata, resolution, }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    indirect_lighting_mode: ShadeIndirectLightingMode;
+    scene_ctx: import("../../scene/GPUSceneContext.js").GPUSceneContext;
+    camera: import("../../camera/GPUCameraContext.js").GPUCameraContext;
+    volumetrics_metadata: number;
+    resolution: number[];
+}): {
+    Y: number;
+    CoCg: number;
+};
+import { ShadeIndirectLightingMode } from "../../ShadeIndirectLightingMode.js";
+//# sourceMappingURL=graph_build_froxel_gi.d.ts.map

package/src/shade/renderer/volumetrics/gi/graph_build_froxel_gi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_build_froxel_gi.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/graph_build_froxel_gi.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;GAeG;AACH;IATsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;IAC9C,sBAAsB,EAAzD,yBAAyB;IACyC,SAAS,EAA3E,OAAO,gCAAgC,EAAE,eAAe;IAEa,MAAM,EAA3E,OAAO,kCAAkC,EAAE,gBAAgB;IAC3C,oBAAoB,EAApC,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACN;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAkErC;0CAtFyC,oCAAoC"}

package/src/shade/renderer/volumetrics/gi/graph_build_froxel_gi.js

@@ -0,0 +1,90 @@
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import { ShadeIndirectLightingMode } from "../../ShadeIndirectLightingMode.js";
+import { shader_volumetrics_gi_brick4 } from "./shader_volumetrics_gi_brick4.js";
+import { shader_volumetrics_gi_ibl } from "./shader_volumetrics_gi_ibl.js";
+import { shader_volumetrics_gi_lpv } from "./shader_volumetrics_gi_lpv.js";
+import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION } from "./volumetrics_gi_resources.js";
+
+/**
+ * The froxel GI stage: the renderer's indirect lighting at every froxel, as the froxel irradiance
+ * volume encodes light, for `shader_volumetrics_build_lighting` to add the lights to. One module per
+ * mode (see `chunk_volumetrics_gi`); this picks the one `indirect_lighting_mode` names and binds its
+ * source from the scene.
+ *
+ * @param {object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {ShadeIndirectLightingMode} options.indirect_lighting_mode
+ * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene_ctx the GI sources:
+ *   `lights.environment_sh`, `volumetric_light_map`, `light_probe_volume`
+ * @param {import("../../camera/GPUCameraContext.js").GPUCameraContext} options.camera
+ * @param {number} options.volumetrics_metadata graph handle
+ * @param {number[]} options.resolution the froxel grid
+ * @returns {{Y: number, CoCg: number}} handles of the GI volume, in the froxel irradiance encoding
+ */
+export function graph_build_froxel_gi({
+                                          graph,
+                                          indirect_lighting_mode,
+                                          scene_ctx,
+                                          camera,
+                                          volumetrics_metadata,
+                                          resolution,
+                                      }) {
+    const volume = () => TextureResourceDescriptor.from({
+        resolution,
+        dimension: "3d",
+        format: "rgba16float",
+        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
+    });
+
+    const bindings = {
+        volumetrics_metadata,
+        camera: graph_import_buffer(graph, camera.buffer.buffer, "froxel gi camera"),
+        tGIY: volume(),
+        tGICoCg: volume(),
+    };
+
+    let shader;
+
+    switch (indirect_lighting_mode) {
+        case ShadeIndirectLightingMode.IBL:
+            shader = shader_volumetrics_gi_ibl;
+            bindings.environment_sh = scene_ctx.lights.environment_sh;
+            break;
+
+        case ShadeIndirectLightingMode.Brick4:
+            shader = shader_volumetrics_gi_brick4;
+            bindings.brick4 = scene_ctx.volumetric_light_map.buffer;
+            break;
+
+        case ShadeIndirectLightingMode.LPV: {
+            shader = shader_volumetrics_gi_lpv;
+            const lpv = scene_ctx.light_probe_volume;
+            bindings.lpv_lookup = lpv.buffer_mesh_bvh;
+            bindings.lpv_metadata = lpv.buffer_metadata;
+            bindings.lpv_mesh = lpv.buffer_mesh;
+            bindings.lpv_probes = lpv.buffer_probes;
+            break;
+        }
+
+        default:
+            throw new Error(`Unsupported indirect lighting mode: ${indirect_lighting_mode}`);
+    }
+
+    const outputs = graph_compute_pass({
+        graph,
+        shader,
+        group_count: [
+            Math.ceil(resolution[0] / VOLUMETRICS_GI_WORKGROUP_RESOLUTION[0]),
+            Math.ceil(resolution[1] / VOLUMETRICS_GI_WORKGROUP_RESOLUTION[1]),
+            Math.ceil(resolution[2] / VOLUMETRICS_GI_WORKGROUP_RESOLUTION[2]),
+        ],
+        bindings,
+    });
+
+    return {
+        Y: outputs.tGIY,
+        CoCg: outputs.tGICoCg,
+    };
+}

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_brick4.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.Brick4`: the sparse volumetric lightmap's probes,
+ * interpolated at each froxel's centre and truncated from SH3 to SH2. See `chunk_volumetrics_gi` for
+ * what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_brick4: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_volumetrics_gi_brick4.d.ts.map

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_brick4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_volumetrics_gi_brick4.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_brick4.js"],"names":[],"mappings":"AA2CA;;;;;;GAMG;AACH,2CAFU,aAAa,CAMpB;8BAnD2B,+BAA+B"}

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_brick4.js

@@ -0,0 +1,55 @@
+import { BRICK4_DATA_STRUCT } from "../../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
+import { chunk_brick4_sample_sh } from "../../global_illumination/brick4/gpu/draw/chunk_brick4_sample_sh.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_volumetrics_gi } from "./chunk_volumetrics_gi.js";
+import { chunk_volumetrics_froxel_centre_ws } from "./chunk_volumetrics_froxel_centre_ws.js";
+import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION, volumetrics_gi_resource_group } from "./volumetrics_gi_resources.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.addGroup(
+    volumetrics_gi_resource_group()
+        .addStorageBuffer("brick4", BRICK4_DATA_STRUCT)
+);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VOLUMETRICS_GI_WORKGROUP_RESOLUTION.join(", ")})
+fn main(@builtin(global_invocation_id) voxel: vec3<u32>) {
+    let resolution = textureDimensions(tGIY);
+
+    if (any(voxel >= resolution)) {
+        return;
+    }
+
+    let position = volumetrics_froxel_centre_ws(voxel, resolution);
+
+    // A froxel has no surface. The normal only masks probes behind one, and a zero normal weighs
+    // every probe of the brick the same (brick4_probe_compute_weight_by_normal), which is the
+    // interpolation a point in open space wants.
+    let sh = brick4_sample_sh(position, vec3<f32>(0.0));
+
+    // SH3 to SH2: the first four coefficients are the same two bands, in the same order
+    volumetrics_gi_store(voxel, array<vec3<f32>, 4>(sh[0], sh[1], sh[2], sh[3]));
+}
+`, [
+    chunk_volumetrics_gi,
+    chunk_volumetrics_froxel_centre_ws,
+    chunk_brick4_sample_sh,
+]);
+
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.Brick4`: the sparse volumetric lightmap's probes,
+ * interpolated at each froxel's centre and truncated from SH3 to SH2. See `chunk_volumetrics_gi` for
+ * what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_brick4 = ComputeShader.from({
+    label: "Volumetrics / GI Brick4",
+    resources,
+    body,
+});

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_ibl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.IBL`: the environment, as
+ * `GPULightCollection.environment_sh` holds it (`shader_project_environment_sh`), at every froxel.
+ * See `chunk_volumetrics_gi` for what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_ibl: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_volumetrics_gi_ibl.d.ts.map

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_ibl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_volumetrics_gi_ibl.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_ibl.js"],"names":[],"mappings":"AAmCA;;;;;;GAMG;AACH,wCAFU,aAAa,CAMpB;8BA5C2B,+BAA+B"}

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_ibl.js

@@ -0,0 +1,47 @@
+import { ENVIRONMENT_SH_TYPE } from "../../light/environment/shader_project_environment_sh.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_volumetrics_gi } from "./chunk_volumetrics_gi.js";
+import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION, volumetrics_gi_resource_group } from "./volumetrics_gi_resources.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.addGroup(
+    volumetrics_gi_resource_group()
+        .addUniform("environment_sh", ENVIRONMENT_SH_TYPE)
+);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VOLUMETRICS_GI_WORKGROUP_RESOLUTION.join(", ")})
+fn main(@builtin(global_invocation_id) voxel: vec3<u32>) {
+    if (any(voxel >= textureDimensions(tGIY))) {
+        return;
+    }
+
+    // the environment is infinitely far: every froxel receives the same field
+    volumetrics_gi_store(voxel, array<vec3<f32>, 4>(
+        environment_sh[0].xyz,
+        environment_sh[1].xyz,
+        environment_sh[2].xyz,
+        environment_sh[3].xyz,
+    ));
+}
+`, [
+    chunk_volumetrics_gi,
+]);
+
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.IBL`: the environment, as
+ * `GPULightCollection.environment_sh` holds it (`shader_project_environment_sh`), at every froxel.
+ * See `chunk_volumetrics_gi` for what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_ibl = ComputeShader.from({
+    label: "Volumetrics / GI IBL",
+    resources,
+    body,
+});

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_lpv.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.LPV`: the light probe volume's tetrahedral mesh, its
+ * probes (radiance SH2) interpolated barycentrically at each froxel's centre. See
+ * `chunk_volumetrics_gi` for what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_lpv: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_volumetrics_gi_lpv.d.ts.map

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_lpv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_volumetrics_gi_lpv.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_lpv.js"],"names":[],"mappings":"AAmDA;;;;;;GAMG;AACH,wCAFU,aAAa,CAMpB;8BAzD2B,+BAA+B"}

package/src/shade/renderer/volumetrics/gi/shader_volumetrics_gi_lpv.js

@@ -0,0 +1,63 @@
+import { LPV_SHADER_RESOURCE_GROUP } from "../../global_illumination/probe/octahedral/LPV_SHADER_RESOURCE_GROUP.js";
+import { chunk_lpv_mesh_interpolation_probe_sh } from "../../shader/chunk/light/lpv/chunk_lpv_mesh_interpolation_probe_sh.js";
+import { chunk_lpv_mesh_lookup_nearest_cell } from "../../shader/chunk/light/lpv/chunk_lpv_mesh_lookup_nearest_cell.js";
+import { INVALID_TET_DECLARATION } from "../../shader/chunk/light/lpv/INVALID_TET_DECLARATION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_volumetrics_gi } from "./chunk_volumetrics_gi.js";
+import { chunk_volumetrics_froxel_centre_ws } from "./chunk_volumetrics_froxel_centre_ws.js";
+import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION, volumetrics_gi_resource_group } from "./volumetrics_gi_resources.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.addGroup(volumetrics_gi_resource_group());
+resources.addGroup(LPV_SHADER_RESOURCE_GROUP);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VOLUMETRICS_GI_WORKGROUP_RESOLUTION.join(", ")})
+fn main(@builtin(global_invocation_id) voxel: vec3<u32>) {
+    let resolution = textureDimensions(tGIY);
+
+    if (any(voxel >= resolution)) {
+        return;
+    }
+
+    let position = volumetrics_froxel_centre_ws(voxel, resolution);
+
+    var weights: vec4<f32>;
+    let tet = lpv_mesh_lookup_nearest_cell(position, &weights);
+
+    // Outside the probe mesh there is nothing to interpolate, and the deferred LPV pass gives such a
+    // point no indirect light either. No visibility mask: that needs a surface normal, and a froxel
+    // has none.
+    var radiance = array<vec3<f32>, 4>();
+
+    if (tet != INVALID_TET) {
+        radiance = lpv_mesh_interpolation_probe_sh(weights, tet);
+    }
+
+    volumetrics_gi_store(voxel, radiance);
+}
+`, [
+    chunk_volumetrics_gi,
+    chunk_volumetrics_froxel_centre_ws,
+    chunk_lpv_mesh_lookup_nearest_cell,
+    chunk_lpv_mesh_interpolation_probe_sh,
+    INVALID_TET_DECLARATION,
+]);
+
+/**
+ * Froxel GI under `ShadeIndirectLightingMode.LPV`: the light probe volume's tetrahedral mesh, its
+ * probes (radiance SH2) interpolated barycentrically at each froxel's centre. See
+ * `chunk_volumetrics_gi` for what a GI module is.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi_lpv = ComputeShader.from({
+    label: "Volumetrics / GI LPV",
+    resources,
+    body,
+});

package/src/shade/renderer/volumetrics/gi/volumetrics_gi_resources.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The bindings every froxel GI module has, whatever its mode reads: where the froxels are, and the
+ * two volumes it writes (`chunk_volumetrics_gi`). rgba16float for both, because rg16float is not a
+ * storage format without texture-formats-tier1.
+ *
+ * @returns {ShaderResourceGroupDescriptor}
+ */
+export function volumetrics_gi_resource_group(): ShaderResourceGroupDescriptor;
+/**
+ * Workgroup shape of every froxel GI module, `[x, y, z]` in froxels: flat in z like the lighting
+ * pass, and 64 invocations.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_GI_WORKGROUP_RESOLUTION: number[];
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
+//# sourceMappingURL=volumetrics_gi_resources.d.ts.map

package/src/shade/renderer/volumetrics/gi/volumetrics_gi_resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volumetrics_gi_resources.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/volumetrics_gi_resources.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,iDAFa,6BAA6B,CAQzC;AAED;;;;;GAKG;AACH,kDAFU,MAAM,EAAE,CAE2C;8CAxBf,wDAAwD"}