@woosh/meep-engine 3.33.0 → 3.35.0

package/src/shade/renderer/light/GPULightCollection.js

@@ -7,6 +7,7 @@ import { GPUTextureContext } from "../texture/GPUTextureContext.js";
 import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
 import { texture_write_to_gpu } from "../texture/texture_write_to_gpu.js";
 import { execute_filter_environment_map } from "./environment/execute_filter_environment_map.js";
+import { ENVIRONMENT_SH_TYPE, shader_project_environment_sh } from "./environment/shader_project_environment_sh.js";
 import { LIGHT_DATABASE_SPEC } from "./LIGHT_DATABASE_SPEC.js";
 import { light_record_directional } from "./model/io/light_record_directional.js";
 import { light_record_point } from "./model/io/light_record_point.js";
@@ -152,6 +153,13 @@ export class GPULightCollection {
      */
     #environment_source;
 
+    /**
+     * The environment's radiance as RGB SH2, projected from {@link #environment} whenever it changes;
+     * see {@link shader_project_environment_sh}.
+     * @type {GPUBuffer}
+     */
+    #environment_sh;
+
 
     /**
      *
@@ -161,9 +169,21 @@ export class GPULightCollection {
         return this.#environment;
     }
 
+    /**
+     * The environment's radiance as RGB SH2 (`ENVIRONMENT_SH_TYPE`), the form the renderer's probe-based
+     * indirect lighting hands over too: what the froxel GI stage starts the froxel irradiance volume
+     * with under IBL. Zero while there is no environment, as {@link environment} is black then.
+     *
+     * @returns {GPUBuffer}
+     */
+    get environment_sh() {
+        return this.#environment_sh;
+    }
+
 
     get gpu_memory_usage() {
         return this.#environment.gpu_memory_usage
+            + this.#environment_sh.size
             + this.#database.gpu_memory_usage
             ;
     }
@@ -194,6 +214,13 @@ export class GPULightCollection {
             | GPUTextureUsage.STORAGE_BINDING // so we can convolve it in compute shader
         ;
 
+        // zeroed on creation, which is what an absent environment projects to
+        this.#environment_sh = device.createBuffer({
+            label: "environment SH",
+            size: ENVIRONMENT_SH_TYPE.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+
         this.#database = new GPUDatabase({
             device,
             label: 'Light Collection / Database',
@@ -236,6 +263,9 @@ export class GPULightCollection {
 
             gpu_ctx.allocate();
 
+            // what a black environment projects to; nothing to run the projection over
+            this.#device.queue.writeBuffer(this.#environment_sh, 0, new Float32Array(this.#environment_sh.size / 4));
+
             return;
         }
 
@@ -271,6 +301,16 @@ export class GPULightCollection {
 
         execute_filter_environment_map(gpu_ctx, cmd);
 
+        // after the prefilter, whose roughest levels are what it reads
+        shader_project_environment_sh.dispatch({
+            encoder: cmd,
+            group_count_x: 1,
+            bindings: {
+                tEnvironment: gpu_ctx.obtainView(),
+                output: this.#environment_sh,
+            },
+        });
+
         cmd.finish();
     }
 
@@ -461,5 +501,6 @@ export class GPULightCollection {
         this.#shadow_context.destroy();
         this.#database.destroy();
         this.#environment.destroy();
+        this.#environment_sh.destroy();
     }
 }

package/src/shade/renderer/light/environment/shader_project_environment_sh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The layout {@link shader_project_environment_sh} writes: the environment's radiance as RGB SH2,
+ * coefficient `k` in `.xyz` of element `k`, ordered `[DC, y, z, x]` in the project's all-positive
+ * basis (`sh2_basis_at`); `.w` is unused. Radiance, not cosine-convolved — the convention the probes
+ * of Brick4 and of the light probe volume are stored in — so `sh2_color_get_irradiance_at` turns it
+ * into the irradiance of a surface facing the direction evaluated at.
+ *
+ * @type {WebGPUArray}
+ */
+export const ENVIRONMENT_SH_TYPE: WebGPUArray;
+/**
+ * Directions the projection samples, spread evenly over the sphere (`sphere_fibonacci_point`).
+ * The field is the environment at the roughness diffuse reads it at, so this is far more than its
+ * two bands can hold, and it costs nothing that recurs: the pass runs when the environment changes.
+ *
+ * @type {number}
+ */
+export const ENVIRONMENT_SH_SAMPLE_COUNT: number;
+/**
+ * The environment as RGB SH2 of radiance ({@link ENVIRONMENT_SH_TYPE}): the form the renderer's other
+ * indirect lighting — Brick4, the light probe volume — already hands over, so the froxel GI stage
+ * (`volumetrics/gi/`) takes the environment as one more source of it. What the froxel irradiance
+ * volume is started with under IBL, and what a lit particle's ambient is there; reading the
+ * environment itself per pixel, as the forward mesh path does, cost 880 us of lighting's 1,090 us on
+ * the bonfire's overdraw at 1898x926 (RTX 4090).
+ *
+ * The field projected is the one the forward path reads (`get_ibl_irradiance`: the prefiltered map at
+ * roughness 1, times pi), and the radiance stored is what that field is the cosine convolution of, so
+ * convolving it back gives the forward path's diffuse up to what two bands drop. Run by
+ * `GPULightCollection` when the environment changes, after the prefilter it reads.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_project_environment_sh: ComputeShader;
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_project_environment_sh.d.ts.map

package/src/shade/renderer/light/environment/shader_project_environment_sh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_project_environment_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_project_environment_sh.js"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,kCAFU,WAAW,CAEyC;AAE9D;;;;;;GAMG;AACH,0CAFU,MAAM,CAEgC;AAyDhD;;;;;;;;;;;;;;GAcG;AACH,4CAFU,aAAa,CAMpB;4BAjGyB,kCAAkC;8BAFhC,+BAA+B"}

package/src/shade/renderer/light/environment/shader_project_environment_sh.js

@@ -0,0 +1,105 @@
+import { chunk_get_ibl_irradiance } from "../../deferred/indirect/chunk_get_ibl_irradiance.js";
+import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
+import { chunk_sphere_fibonacci_point } from "../../shader/chunk/geometry/sphere/chunk_sphere_fibonacci_point.js";
+import { chunk_sh2_basis_at } from "../../shader/chunk/spherical_harmonics/chunk_sh2_basis_at.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+
+/**
+ * The layout {@link shader_project_environment_sh} writes: the environment's radiance as RGB SH2,
+ * coefficient `k` in `.xyz` of element `k`, ordered `[DC, y, z, x]` in the project's all-positive
+ * basis (`sh2_basis_at`); `.w` is unused. Radiance, not cosine-convolved — the convention the probes
+ * of Brick4 and of the light probe volume are stored in — so `sh2_color_get_irradiance_at` turns it
+ * into the irradiance of a surface facing the direction evaluated at.
+ *
+ * @type {WebGPUArray}
+ */
+export const ENVIRONMENT_SH_TYPE = WebGPUArray.from(vec4f, 4);
+
+/**
+ * Directions the projection samples, spread evenly over the sphere (`sphere_fibonacci_point`).
+ * The field is the environment at the roughness diffuse reads it at, so this is far more than its
+ * two bands can hold, and it costs nothing that recurs: the pass runs when the environment changes.
+ *
+ * @type {number}
+ */
+export const ENVIRONMENT_SH_SAMPLE_COUNT = 1024;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    // read texel by texel (texture_octahedral_sample_bilinear), as the forward path reads it
+    .addTexture("tEnvironment")
+    .addStorageBuffer("output", ENVIRONMENT_SH_TYPE, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const SAMPLE_COUNT : u32 = ${ENVIRONMENT_SH_SAMPLE_COUNT}u;
+
+// One invocation: the projection is 1024 reads that happen when the environment changes and never
+// otherwise, and a single lane needs no reduction and runs whole on the emulator.
+@compute @workgroup_size(1)
+fn main() {
+    var sh_0 = vec3<f32>(0.0);
+    var sh_1 = vec3<f32>(0.0);
+    var sh_2 = vec3<f32>(0.0);
+    var sh_3 = vec3<f32>(0.0);
+
+    for (var i = 0u; i < SAMPLE_COUNT; i++) {
+        let direction = sphere_fibonacci_point(f32(i), f32(SAMPLE_COUNT));
+
+        // exactly what the forward mesh path takes as a surface's diffuse irradiance under IBL
+        let irradiance = get_ibl_irradiance(direction);
+
+        let basis = sh2_basis_at(direction);
+
+        sh_0 += irradiance * basis[0];
+        sh_1 += irradiance * basis[1];
+        sh_2 += irradiance * basis[2];
+        sh_3 += irradiance * basis[3];
+    }
+
+    // each sample stands for an equal share of the sphere
+    let weight = 4.0 * PI / f32(SAMPLE_COUNT);
+
+    // What was projected is irradiance; what is stored is the radiance it is the cosine convolution
+    // of, band by band: the clamped cosine's zonal weights are pi for band 0 and 2 pi / 3 for band 1.
+    let band_0 = weight / PI;
+    let band_1 = weight * 3.0 / (2.0 * PI);
+
+    output[0] = vec4<f32>(sh_0 * band_0, 0.0);
+    output[1] = vec4<f32>(sh_1 * band_1, 0.0);
+    output[2] = vec4<f32>(sh_2 * band_1, 0.0);
+    output[3] = vec4<f32>(sh_3 * band_1, 0.0);
+}
+`, [
+    chunk_sphere_fibonacci_point,
+    chunk_get_ibl_irradiance,
+    chunk_sh2_basis_at,
+    PI_DECLARATION,
+]);
+
+/**
+ * The environment as RGB SH2 of radiance ({@link ENVIRONMENT_SH_TYPE}): the form the renderer's other
+ * indirect lighting — Brick4, the light probe volume — already hands over, so the froxel GI stage
+ * (`volumetrics/gi/`) takes the environment as one more source of it. What the froxel irradiance
+ * volume is started with under IBL, and what a lit particle's ambient is there; reading the
+ * environment itself per pixel, as the forward mesh path does, cost 880 us of lighting's 1,090 us on
+ * the bonfire's overdraw at 1898x926 (RTX 4090).
+ *
+ * The field projected is the one the forward path reads (`get_ibl_irradiance`: the prefiltered map at
+ * roughness 1, times pi), and the radiance stored is what that field is the cosine convolution of, so
+ * convolving it back gives the forward path's diffuse up to what two bands drop. Run by
+ * `GPULightCollection` when the environment changes, after the prefilter it reads.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_project_environment_sh = ComputeShader.from({
+    label: "Environment / project SH",
+    resources,
+    body,
+});

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#252@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#250@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/material/GPUMaterialManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AAyNA;IAiFI;;;;;;;;OAQG;IACH,yCANW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,aACrB,iBAAiB,EAmD3B;IApID;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IAsBrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IAoLD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAiMnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;;;;;;;;;;OAYG;IACH,kBAHW,aAAa,GACX,OAAO,CAyBnB;IAED;;;;OAIG;IACH,gBAWC;IAED;;;;;;;;;OASG;IACH,kBAFW,qBAAqB,QAM/B;IAsBD;;;;;;OAMG;IACH,0BAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAED;;;;;;OAMG;IACH,wBAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAuED;;;OAGG;IACH,YAFW,sBAAsB,QAiChC;;CAEJ;6BA51BY,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;gCACzD,OAAO,yBAAyB,EAAE,iBAAiB;6BACnD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;oCAC1C,OAAO,qCAAqC,EAAE,qBAAqB;mCApBzE,yBAAyB;mCAjBG,8CAA8C"}
+{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AAyNA;IAiFI;;;;;;;;OAQG;IACH,yCANW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,aACrB,iBAAiB,EAmD3B;IApID;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IAsBrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IAoLD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAiMnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;;;;;;;;;;OAYG;IACH,kBAHW,aAAa,GACX,OAAO,CAyBnB;IAED;;;;OAIG;IACH,gBAaC;IAED;;;;;;;;;OASG;IACH,kBAFW,qBAAqB,QAM/B;IAsBD;;;;;;OAMG;IACH,0BAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAED;;;;;;OAMG;IACH,wBAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAuED;;;OAGG;IACH,YAFW,sBAAsB,QAiChC;;CAEJ;6BA91BY,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;gCACzD,OAAO,yBAAyB,EAAE,iBAAiB;6BACnD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;oCAC1C,OAAO,qCAAqC,EAAE,qBAAqB;mCApBzE,yBAAyB;mCAjBG,8CAA8C"}

package/src/shade/renderer/material/GPUMaterialManager.js

@@ -724,6 +724,8 @@ export class GPUMaterialManager {
 
         this.#dynamic_contexts.length = 0;
 
+        this.#metadata_table.destroy();
+
         this.#list_version++;
         this.#version++;
     }

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

@@ -21,7 +21,8 @@ rows, and the decision to spawn is the GPU's.
 - Scene / bone attachment: an emitter stands at an entity with a row; its world matrix is that row
   of the scene's `transforms` table, composed by the GPU hierarchy pass.
 - Distinct per-particle lifecycle: **no** built-in age/position — the schema + program define state.
-- Billboard drawing reuses engine shader chunks incl. lighting (forward-shaded, optional per emitter).
+- Lighting per emitter (`EMITTER_FLAG.LIGHTING`): the scene's lights from the froxel irradiance
+  volume the fog pass writes, plus the environment map. See "Lighting" below.
 - Blend modes (alpha + additive) via a **single** premultiplied blend setup.
 - Authored curves and RGB/RGBA gradients compiled into arithmetic for simulation.
 - Spawning decided on the GPU, per emitter, with the CPU able to ask for bursts through the same path.
@@ -516,19 +517,13 @@ draw's.
 ### Rendering
 
 A 6-vertex quad is expanded per instance (billboard/velocity-stretch/axis-lock/world modes) by
-`chunk_particle_billboard_vertex`. Fragment: sample atlas (region + flipbook frame), optional forward
-lighting via `chunk_shade_standard_material_direct` + IBL, optional soft-depth fade. Soft-depth
-fading scales both RGB and alpha for premultiplied inputs; straight-alpha and additive inputs have
-alpha scaled before premultiplication.
+`chunk_particle_billboard_vertex`. Fragment: sample atlas (region + flipbook frame), optional
+soft-depth fade, optional lighting (below). Soft-depth fading scales both RGB and alpha for
+premultiplied inputs; straight-alpha and additive inputs have alpha scaled before premultiplication.
 
 Additive vs. alpha is never a pipeline switch: the shader emits premultiplied RGB with alpha 0
 (additive) or alpha a (normal), so one setup covers both and the choice stays per particle and
-GPU-driven. Under AVBOIT that choice picks which accumulators the fragment writes; in the blended
-pipeline `shaders/shader_particle_render.js` builds it is one blend state,
-`(one, one-minus-src-alpha)` on both channels. That pipeline is not this system's — it is what
-`GPUParticularRenderer` draws `particular`'s CPU-simulated particles with, over a draw list it sorts
-back to front on the CPU — but it shares this vertex stage, this atlas and flipbook math, and
-`particle_fade_color`, so a sprite looks the same whichever draws it.
+GPU-driven. Under AVBOIT that choice picks which accumulators the fragment writes.
 
 ### Drawing: an AVBOIT side channel
 
@@ -564,8 +559,8 @@ contribution at the three points where the meshlet buckets have just made theirs
    The whole decision is `chunk_particle_avboit_contribution`, and it is spec'd on the emulator.
 
 All three read the alive list and the draw args straight from `simulate`; the vertex stage is one
-chunk (`chunk_particle_billboard_vertex`), shared by the splat, the draw and the blended pipeline
-`particular` uses. `GPUParticleSystem` implements the three methods; `Renderer.feature_particles_enabled`
+chunk (`chunk_particle_billboard_vertex`), shared by the splat and the draw. `GPUParticleSystem`
+implements the three methods; `Renderer.feature_particles_enabled`
 runs `execute` before the transparency pass and hands the system to the orchestrator. MBOIT is legacy
 and gets no particle path, so under it the particles simulate and are not drawn.
 
@@ -582,7 +577,7 @@ everything `chunk_particle_avboit_contribution` does after its premultiply
 ECS system over the pair `[ParticleEffect, Transform64]` — the component says what an entity emits,
 the transform says where — in exactly the shape `DecalSystem` and `MeshSystem` use for their own
 content. Construct it with `(graphicsEngine, scene, assetManager)` and add it to the EntityManager.
-It is opt-in and coexists with the legacy CPU `ParticleEmitterSystem`.
+It is opt-in.
 
 ```js
 entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager));
@@ -719,7 +714,6 @@ src/shade/renderer/particles/
   shaders/shader_particle_emit.js            per-newborn INIT, sized by the scan
   shaders/shader_particle_simulate.js        per-particle UPDATE + compaction + orphan kill
   shaders/shader_particle_finalize.js        reset counters (+ budget) / build indirect args
-  shaders/shader_particle_render.js          blended billboard pipeline (GPUParticularRenderer's)
   shaders/chunk_particle_setup_context.js    VM builtins from the emitter's node, + the RNG seed
   shaders/chunk_particle_emitter_age.js      the tick pass's running age, off the emitter_state table
   shaders/chunk_particle_spawn_budget.js     take from the frame's spawn budget; both ticks spend it
@@ -784,6 +778,63 @@ was seeded.
 
 Done: `Renderer.feature_particles_enabled` (off by default), `Renderer.particles(scene_ctx)` creating
 one system per scene context on first use, `simulate` recorded before the transparency pass and the
-system passed to the AVBOIT orchestrator as its side channel. Remaining:
-1. For lit emitters, compile a render variant that swaps the disabled lighting hook for a
-   shading-chunk-backed lighting hook (+ the `SHADING_LIGHT_RESOURCE_GROUP`).
+system passed to the AVBOIT orchestrator as its side channel.
+
+### Lighting
+
+An emitter flagged `EMITTER_FLAG.LIGHTING` treats its colour as a diffuse albedo; an emitter without
+it is its own colour, which is what additive (emissive) emitters want and stay. The flag is read per
+fragment from the emitter record, so lit and unlit particles share one pipeline and one draw. All of
+it is evaluated per pixel (`chunk_particle_lighting`, the model in `chunk_particle_lighting_model`):
+a vertex need not be on screen, and one quad can span the frustum.
+
+- **Direct light comes from the froxel irradiance volume** (`volumetrics/chunk_volumetrics_irradiance_sh`),
+  which `shader_volumetrics_build_lighting` writes in the loop that lights the fog: every
+  directional, point and spot light at the froxel, shadowed, attenuated by the fog toward it, stored
+  as luma SH2 + constant chroma (Metro's L1 YCoCg, 6 coefficients in two `rgba16float` volumes, since
+  `rg16float` is not a storage format without `texture-formats-tier1`). The volume rides the
+  orchestrator to side channels as `volumetrics_irradiance`. Resolution is the fog's — 16 px tiles
+  and 64 slices — so light and shadow edges inside a particle are soft. idTech 8 builds the same
+  volume in the same pass (Sousa, SIGGRAPH 2025, p.29); Ghost of Tsushima lights particles from its
+  haze grid the same way. Chosen over per-pixel forward shading (UE's most expensive mode, and a
+  flat card lit that way goes black from behind), per-vertex/per-particle lighting (the light
+  clusters are screen-space: a point off screen has no light list, the artefact that moved idTech 8
+  off it) and a per-particle lighting atlas (DOOM 2016, CoD IW: best-looking, but it needs a
+  world-space light lookup this engine does not have).
+- **The SH is evaluated at the normal and the irradiance clamped at zero.** One light gives
+  `E max(0, 1/4 + cos/2)`. SH2 cannot keep two lights apart: a light's lobe is `-E/4` facing away
+  from it, so a light behind a particle subtracts from the ones in front before the clamp sees a
+  total. Measured on the bonfire before transmission, the moon behind the smoke brought the fire-lit
+  side down to about half (display red 10 against 21).
+- **Chroma has no direction**: two lights of different colours from opposite sides tint both sides
+  their mix. Measured on the bonfire, the blue moon moves the fire-lit underside of the smoke from
+  (22.9, 5.3, 1.5) to (15.9, 4.7, 2.6) in display values; a same-coloured moon only brightens it.
+- **Indirect light is in the same volume**, whatever the renderer's `indirect_lighting_mode`. The
+  froxel GI stage (`volumetrics/gi/`) starts the volume with one concrete module per mode — IBL,
+  Brick4, LPV — each asking its source what radiance arrives at the froxel's centre, as RGB SH2,
+  and `shader_volumetrics_build_lighting` adds the lights to that. The particle knows no mode: a new
+  GI system is one more module. IBL's source is `GPULightCollection.environment_sh`, the
+  environment projected to radiance SH2 when it changes (`shader_project_environment_sh`); Brick4
+  interpolates its probes (SH3, truncated) with a zero normal, which weighs every probe of the
+  brick alike; LPV interpolates the tetrahedron the froxel falls in, and gives nothing outside the
+  mesh, as the deferred LPV pass does. Measured at 1898x926 (RTX 4090): the IBL module 5-6 us, the
+  Brick4 module 31 us over an empty map. Reading the environment per pixel instead, as the forward
+  mesh path does, had been 880 us of lighting's 1,090 us — the particle draw is all overdraw.
+- **Back-face transmission** (Persson, "Practical Particle Lighting", GDC 2012, pp.34-37): the same
+  light evaluated at `-normal`, passed on in proportion to `1 - alpha`. The dense core of a puff
+  holds light from behind back and its thin edges let it through — smoke backlit by the moon has an
+  edge instead of being black. It costs nothing measurable: the draw is bound by its texture reads.
+- **The normal** is the quad's own plane per projection mode, turned to the side the eye is on and
+  bent out toward the corners (`particle_billboard_normal`), so a sprite shades as a puff.
+- **The directional light skips the atmosphere's transmittance** the fog applies: meshes are lit by
+  `sun.color` as it stands, and a lit particle has to agree with the surface beside it.
+
+Cost, bonfire (~1,300 live, smoke and soot lit), RTX 4090, lit minus unlit p10 in one page: the
+draw +90..275 us at 1898x926 (of ~450) across runs, +0.8..1.2 ms at 3818x2006 (of ~2.1 ms). The fog pass does
+not get slower for the two extra stores — paired against the tree before it, it measured 77 vs 89 us
+and 280 vs 320 us, reason not established. The volume has no temporal filter of its own: with the
+simulation frozen, lit and unlit smoke change equally from frame to frame even with the screen TAA
+off (0.09 vs 0.09 mean display units). That scene has no shadow edge through the smoke, which is
+where a one-sample-per-froxel volume would show it first.
+
+Open: a particle does not shade the fog or other particles (the volume holds no particle density).

package/src/shade/renderer/particles/GPUParticleSystem.d.ts

@@ -295,10 +295,12 @@ export class GPUParticleSystem {
      * @param {number} args.integral graph handle of the integral texture
      * @param {number} args.volumetrics_lut graph handle
      * @param {number} args.volumetrics_metadata graph handle
+     * @param {{Y: number, CoCg: number}} args.volumetrics_irradiance graph handles of the froxel
+     *   irradiance volume, what an emitter flagged `EMITTER_FLAG.LIGHTING` is lit by
      * @param {{color: number, norm: number, extinction: number, emission: number}} args.accumulators
      * @returns {{color: number, norm: number, extinction: number, emission: number}} after the draw
      */
-    avboit_draw({ graph, view_ctx, camera, depth_texture, warp, integral, volumetrics_lut, volumetrics_metadata, accumulators }: {
+    avboit_draw({ graph, view_ctx, camera, depth_texture, warp, integral, volumetrics_lut, volumetrics_metadata, volumetrics_irradiance, accumulators }: {
         graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
         view_ctx: import("../view/GPUViewContext.js").GPUViewContext;
         camera: number;
@@ -307,6 +309,10 @@ export class GPUParticleSystem {
         integral: number;
         volumetrics_lut: number;
         volumetrics_metadata: number;
+        volumetrics_irradiance: {
+            Y: number;
+            CoCg: number;
+        };
         accumulators: {
             color: number;
             norm: number;

package/src/shade/renderer/particles/GPUParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}