@woosh/meep-engine 3.49.0 → 3.51.0

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

@@ -1,23 +1,25 @@
 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 { ShaderSwitchSet } from "../../shader/compiler/ShaderSwitchSet.js";
+import { shader_volumetrics_gi } from "./shader_volumetrics_gi.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_irradiance` 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.
+ * volume encodes light, for `shader_volumetrics_build_irradiance` to add the lights to. The shader is
+ * built for the renderer's switches, which pick the indirect lighting mode it samples
+ * (`chunk_volumetrics_gi_sample`); this binds the environment and the running mode's source.
  *
  * @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 {ShaderSwitchSet} [options.shader_switches] the renderer's
+ * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene_ctx for its environment,
+ *   `lights.environment_sh`
+ * @param {import("../../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4] the scene's,
+ *   while Brick4 runs
+ * @param {import("../../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv] the
+ *   scene's, while LPV runs. A source not given is the shader's default, for a variant that does not read it
  * @param {import("../../camera/GPUCameraContext.js").GPUCameraContext} options.camera
  * @param {number} options.volumetrics_metadata graph handle
  * @param {number[]} options.resolution the froxel grid
@@ -25,8 +27,10 @@ import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION } from "./volumetrics_gi_resources.
  */
 export function graph_build_froxel_gi({
                                           graph,
-                                          indirect_lighting_mode,
+                                          shader_switches = ShaderSwitchSet.EMPTY,
                                           scene_ctx,
+                                          brick4,
+                                          lpv,
                                           camera,
                                           volumetrics_metadata,
                                           resolution,
@@ -43,38 +47,24 @@ export function graph_build_froxel_gi({
         camera: graph_import_buffer(graph, camera.buffer.buffer, "froxel gi camera"),
         tGIY: volume(),
         tGICoCg: volume(),
+        environment_sh: scene_ctx.lights.environment_sh,
     };
 
-    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;
-        }
+    // the running mode's source; the others are the shader's defaults, which its variant does not read
+    if (brick4 !== undefined) {
+        bindings.brick4 = brick4.buffer;
+    }
 
-        default:
-            throw new Error(`Unsupported indirect lighting mode: ${indirect_lighting_mode}`);
+    if (lpv !== undefined) {
+        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;
     }
 
     const outputs = graph_compute_pass({
         graph,
-        shader,
+        shader: shader_volumetrics_gi.variant(shader_switches),
         group_count: [
             Math.ceil(resolution[0] / VOLUMETRICS_GI_WORKGROUP_RESOLUTION[0]),
             Math.ceil(resolution[1] / VOLUMETRICS_GI_WORKGROUP_RESOLUTION[1]),

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

@@ -0,0 +1,10 @@
+/**
+ * The froxel GI stage: the renderer's indirect lighting at every froxel, one thread per froxel. Which
+ * mode's light it asks for is a shader switch ({@link chunk_volumetrics_gi_sample}); the bindings are
+ * the same for every mode. See `chunk_volumetrics_gi` for what it does with the answer.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_volumetrics_gi.d.ts.map

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

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

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

@@ -0,0 +1,51 @@
+import { BRICK4_DATA_STRUCT } from "../../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
+import { LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS } from "../../global_illumination/probe/octahedral/LPV_SHADER_RESOURCE_GROUP.js";
+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 { chunk_volumetrics_gi_sample } from "./chunk_volumetrics_gi_sample.js";
+import { VOLUMETRICS_GI_WORKGROUP_RESOLUTION, volumetrics_gi_resource_group } from "./volumetrics_gi_resources.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+// every indirect lighting mode's source, whichever the variant reads (chunk_volumetrics_gi_sample). The pass
+// binds the environment and the running mode's source; the others have defaults the variant does not read.
+resources.addGroup(
+    volumetrics_gi_resource_group()
+        .addUniform("environment_sh", ENVIRONMENT_SH_TYPE)
+        .addStorageBuffer("brick4", BRICK4_DATA_STRUCT, false, true)
+);
+resources.addGroup(LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS);
+
+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;
+    }
+
+    volumetrics_gi_store(voxel, volumetrics_gi_sample(voxel, resolution));
+}
+`, [
+    chunk_volumetrics_gi,
+    chunk_volumetrics_gi_sample,
+]);
+
+/**
+ * The froxel GI stage: the renderer's indirect lighting at every froxel, one thread per froxel. Which
+ * mode's light it asks for is a shader switch ({@link chunk_volumetrics_gi_sample}); the bindings are
+ * the same for every mode. See `chunk_volumetrics_gi` for what it does with the answer.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_gi = ComputeShader.from({
+    label: "Volumetrics / GI",
+    resources,
+    body,
+});

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

@@ -6,6 +6,16 @@
  * @returns {ShaderResourceGroupDescriptor}
  */
 export function volumetrics_gi_resource_group(): ShaderResourceGroupDescriptor;
+/**
+ * The froxel GI's luma volume, as its modules write it (`chunk_volumetrics_gi`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_GI_Y_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The froxel GI's chroma volume, as its modules write it (`chunk_volumetrics_gi`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_GI_COCG_RESOURCE: ShaderResourceDescriptor;
 /**
  * Workgroup shape of every froxel GI module, `[x, y, z]` in froxels: flat in z like the lighting
  * pass, and 64 invocations.
@@ -14,4 +24,5 @@ export function volumetrics_gi_resource_group(): ShaderResourceGroupDescriptor;
  */
 export const VOLUMETRICS_GI_WORKGROUP_RESOLUTION: number[];
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
 //# sourceMappingURL=volumetrics_gi_resources.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"volumetrics_gi_resources.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/gi/volumetrics_gi_resources.js"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,iDAFa,6BAA6B,CAQzC;AAzBD;;;GAGG;AACH,wCAFU,wBAAwB,CAE0F;AAE5H;;;GAGG;AACH,2CAFU,wBAAwB,CAEgG;AAiBlI;;;;;GAKG;AACH,kDAFU,MAAM,EAAE,CAE2C;8CApCf,wDAAwD;yCAD7D,mDAAmD"}

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

@@ -1,6 +1,19 @@
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CAMERA_RESOURCE } from "../../camera/CAMERA_RESOURCE.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
-import { VOLUMETRICS_METADATA_STRUCT } from "../VOLUMETRICS_METADATA_STRUCT.js";
+import { VOLUMETRICS_METADATA_RESOURCE } from "../VOLUMETRICS_RESOURCES.js";
+
+/**
+ * The froxel GI's luma volume, as its modules write it (`chunk_volumetrics_gi`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_GI_Y_RESOURCE = ShaderResourceDescriptor.storageTexture("tGIY", "rgba16float", "3d", "write-only");
+
+/**
+ * The froxel GI's chroma volume, as its modules write it (`chunk_volumetrics_gi`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_GI_COCG_RESOURCE = ShaderResourceDescriptor.storageTexture("tGICoCg", "rgba16float", "3d", "write-only");
 
 /**
  * The bindings every froxel GI module has, whatever its mode reads: where the froxels are, and the
@@ -11,10 +24,10 @@ import { VOLUMETRICS_METADATA_STRUCT } from "../VOLUMETRICS_METADATA_STRUCT.js";
  */
 export function volumetrics_gi_resource_group() {
     return new ShaderResourceGroupDescriptor()
-        .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-        .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-        .addStorageTexture("tGIY", "rgba16float", "3d", "write-only")
-        .addStorageTexture("tGICoCg", "rgba16float", "3d", "write-only");
+        .add(VOLUMETRICS_METADATA_RESOURCE)
+        .add(CAMERA_RESOURCE)
+        .add(VOLUMETRICS_GI_Y_RESOURCE)
+        .add(VOLUMETRICS_GI_COCG_RESOURCE);
 }
 
 /**

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

@@ -18,12 +18,15 @@
  * @param {number} options.shadowmap_atlas
  * @param {number} options.volumetrics_metadata where the froxels are
  * @param {number[]} options.resolution the froxel grid
- * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode which froxel GI
- *   module starts the volume
- * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lights' pass is built for them
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the GI that starts the volume and the
+ *   lights' pass are built for them
+ * @param {import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4] the scene's,
+ *   while Brick4 runs
+ * @param {import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv] the
+ *   scene's, while LPV runs
  * @returns {{Y: number, CoCg: number}} handles of the volume: luma SH2, and chroma in `.rg`
  */
-export function graph_build_froxel_irradiance({ graph, camera, view, lights, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetrics_metadata, resolution, indirect_lighting_mode, shader_switches, }: {
+export function graph_build_froxel_irradiance({ graph, camera, view, lights, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetrics_metadata, resolution, shader_switches, brick4, lpv, }: {
     graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     camera: import("../camera/GPUCameraContext.js").GPUCameraContext;
     view: import("../view/GPUViewContext.js").GPUViewContext;
@@ -34,8 +37,9 @@ export function graph_build_froxel_irradiance({ graph, camera, view, lights, lig
     shadowmap_atlas: number;
     volumetrics_metadata: number;
     resolution: number[];
-    indirect_lighting_mode: import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode;
     shader_switches?: ShaderSwitchSet;
+    brick4?: import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap;
+    lpv?: import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume;
 }): {
     Y: number;
     CoCg: number;

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_froxel_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_froxel_irradiance.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAfmG,KAAK,EAA7F,OAAO,2DAA2D,EAAE,UAAU;IACZ,MAAM,EAAxE,OAAO,+BAA+B,EAAE,gBAAgB;IACI,IAAI,EAAhE,OAAO,2BAA2B,EAAE,cAAc;IACmB,MAAM,EAA3E,OAAO,gCAAgC,EAAE,kBAAkB;IAC3C,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACqE,sBAAsB,EAAnG,OAAO,iCAAiC,EAAE,yBAAyB;IAEzC,eAAe,GAAzC,eAAe;IACb;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAmFrC;gCAjH+B,uCAAuC"}
+{"version":3,"file":"graph_build_froxel_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_froxel_irradiance.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAlBmG,KAAK,EAA7F,OAAO,2DAA2D,EAAE,UAAU;IACZ,MAAM,EAAxE,OAAO,+BAA+B,EAAE,gBAAgB;IACI,IAAI,EAAhE,OAAO,2BAA2B,EAAE,cAAc;IACmB,MAAM,EAA3E,OAAO,gCAAgC,EAAE,kBAAkB;IAC3C,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACkB,eAAe,GAAzC,eAAe;IAEoE,MAAM,GAAzF,OAAO,iDAAiD,EAAE,cAAc;IAEkB,GAAG,GAA7F,OAAO,mDAAmD,EAAE,mBAAmB;IAE7E;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAsFrC;gCAvH+B,uCAAuC"}

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

@@ -26,9 +26,12 @@ import { shader_volumetrics_build_irradiance } from "./shader_volumetrics_build_
  * @param {number} options.shadowmap_atlas
  * @param {number} options.volumetrics_metadata where the froxels are
  * @param {number[]} options.resolution the froxel grid
- * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode which froxel GI
- *   module starts the volume
- * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lights' pass is built for them
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the GI that starts the volume and the
+ *   lights' pass are built for them
+ * @param {import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4] the scene's,
+ *   while Brick4 runs
+ * @param {import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv] the
+ *   scene's, while LPV runs
  * @returns {{Y: number, CoCg: number}} handles of the volume: luma SH2, and chroma in `.rg`
  */
 export function graph_build_froxel_irradiance({
@@ -42,13 +45,16 @@ export function graph_build_froxel_irradiance({
                                                   shadowmap_atlas,
                                                   volumetrics_metadata,
                                                   resolution,
-                                                  indirect_lighting_mode,
                                                   shader_switches = ShaderSwitchSet.EMPTY,
+                                                  brick4,
+                                                  lpv,
                                               }) {
 
     const gi = graph_build_froxel_gi({
         graph,
-        indirect_lighting_mode,
+        shader_switches,
+        brick4,
+        lpv,
         scene_ctx: view.scene,
         camera,
         volumetrics_metadata,

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA4VA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB+B,KAAK;IACC,MAAM;IACJ,MAAM;IACV,IAAI;IACZ,GAAG;IAIH,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACY,qBAAqB,EAAvC,MAAM,EAAE;IACU,qBAAqB,EAAvC,MAAM,EAAE;IAGQ,oBAAoB,EAApC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,UAAU,GAA3B,MAAM;IACqB,eAAe;IAChB,eAAe,GAAzC,eAAe;;;;;;EAiLzB;gCApiB+B,uCAAuC"}
+{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA+aA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB+B,KAAK;IACC,MAAM;IACJ,MAAM;IACV,IAAI;IACZ,GAAG;IAIH,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACY,qBAAqB,EAAvC,MAAM,EAAE;IACU,qBAAqB,EAAvC,MAAM,EAAE;IAGQ,oBAAoB,EAApC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,UAAU,GAA3B,MAAM;IACqB,eAAe;IAChB,eAAe,GAAzC,eAAe;;;;;;EAsLzB;gCA3nB+B,uCAAuC"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
 import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
@@ -8,8 +9,15 @@ import { graph_import_texture } from "../shader/graph/graph_import_texture.js";
 import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
+import { WIND_FIELD_UNIFORM } from "../wind/WIND_FIELD_UNIFORM.js";
 import { volumetrics_sun_shadow_texture_name } from "./chunk_volumetrics_sun_optical_depth.js";
 import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "./noise/PARTICIPATING_MEDIA_NOISE.js";
+import { VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION } from "./chunk_volumetrics_media_group_list.js";
+import { shader_volumetrics_bin_participating_media } from "./shader_volumetrics_bin_participating_media.js";
+import {
+    shader_volumetrics_split_participating_media,
+    VOLUMETRICS_MEDIA_SPLIT_LANES
+} from "./shader_volumetrics_split_participating_media.js";
 import { shader_volumetrics_build_lighting } from "./shader_volumetrics_build_lighting.js";
 import { shader_volumetrics_build_participating_media } from "./shader_volumetrics_build_participating_media.js";
 import { shader_volumetrics_build_scattering_lut } from "./shader_volumetrics_build_scattering_lut.js";
@@ -33,6 +41,7 @@ import {
  * @param {GPUViewContext} options.view
  * @param {number} options.volumetrics_metadata
  * @param {number[]} options.resolution output resolution
+ * @param {ShaderSwitchSet} options.shader_switches the renderer's; the build adds the wind field's shape
  */
 function graph_integrate_participating_media({
                                                  graph,
@@ -41,10 +50,26 @@ function graph_integrate_participating_media({
                                                  view,
                                                  volumetrics_metadata,
                                                  resolution,
+                                                 shader_switches,
                                              }) {
 
     const data = {};
 
+    // the media build's workgroups, each of which the bin gives a list of the volumes it may see
+    const groups = [
+        Math.ceil(resolution[0] / VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION[0]),
+        Math.ceil(resolution[1] / VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION[1]),
+        resolution[2],
+    ];
+
+    // A bit a volume. Sized from the scene's volumes, which the table's rows never outnumber; the
+    // shaders take the volume count off the table and the words a list gets off this buffer.
+    const volume_count = scene.volumetrics.source.volumes.length;
+    const list_words = Math.ceil(volume_count / 32);
+    const group_lists_bytes = 4 * Math.max(4, groups[0] * groups[1] * groups[2] * list_words);
+
+    // the near and the far field: a count, then a row for every volume either may hold
+    const field_bytes = 4 * Math.max(4, 1 + volume_count);
 
     const pass = graph.add(
         "aerial lut",
@@ -66,10 +91,40 @@ function graph_integrate_participating_media({
              */
             const output1 = resources.get(data.output1);
 
+            const group_lists = resources.get(data.group_lists);
+            const near_field = resources.get(data.near_field);
+            const far_field = resources.get(data.far_field);
+
             const encoder = context.encoder;
 
             const volumetrics_metadata = resources.get(data.volumetrics_metadata);
 
+            shader_volumetrics_split_participating_media.dispatch({
+                encoder,
+                bindings: {
+                    camera: camera.buffer.buffer,
+                    volumetrics_metadata,
+                    scene_database: scene.scene_database_buffer,
+                    near_field,
+                    far_field,
+                },
+                group_count_x: Math.max(1, Math.ceil(volume_count / VOLUMETRICS_MEDIA_SPLIT_LANES)),
+            });
+
+            shader_volumetrics_bin_participating_media.dispatch({
+                encoder,
+                bindings: {
+                    camera: camera.buffer.buffer,
+                    volumetrics_metadata,
+                    scene_database: scene.scene_database_buffer,
+                    near_field,
+                    group_lists,
+                },
+                group_count_x: groups[0],
+                group_count_y: groups[1],
+                group_count_z: groups[2],
+            });
+
             /**
              * The scene's noise atlas, imported this frame so a grow between frames is seen.
              * @type {GPUTextureContext}
@@ -79,28 +134,55 @@ function graph_integrate_participating_media({
             // the per-froxel point the noise is read at moves by this volume every frame
             const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
 
-            shader_volumetrics_build_participating_media.dispatchThreads({
+            const bindings = {
+                camera: camera.buffer.buffer,
+                view: view.uniform_buffer.buffer,
+                volumetrics_metadata,
+                scene_database: scene.scene_database_buffer,
+                tSTBN_vec3: tSTBN_vec3.obtainView(),
+                tParticipatingMediaNoise: noise_atlas.obtainView(),
+                sParticipatingMediaNoise: context.graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
+                tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                group_lists,
+            };
+
+            // taken this frame rather than held: a producer that grows the field replaces its atlas
+            scene.wind.bind(bindings);
+
+            // and read in the shape it has this frame: with no cascades the wind is the far field
+            // everywhere, and that variant links neither the cascades' read nor the noise's flow map
+            const switches = shader_switches.with(WIND_FIELD_UNIFORM, scene.wind.cascade_count === 0);
+
+            shader_volumetrics_build_participating_media.variant(switches).dispatchThreads({
                 encoder,
                 thread_count_x: output0.width,
                 thread_count_y: output0.height,
                 thread_count_z: output0.depth,
-                bindings: {
-                    camera: camera.buffer.buffer,
-                    view: view.uniform_buffer.buffer,
-                    volumetrics_metadata,
-                    scene_database: scene.scene_database_buffer,
-                    tSTBN_vec3: tSTBN_vec3.obtainView(),
-                    tParticipatingMediaNoise: noise_atlas.obtainView(),
-                    sParticipatingMediaNoise: context.graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
-                    tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                    tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                }
+                bindings,
             });
 
 
         });
 
     data.volumetrics_metadata = pass.read(volumetrics_metadata);
+    // the split appends to lists counted from zero
+    data.near_field = pass.create("participating media near field", BufferResourceDescriptor.from(
+        field_bytes,
+        GPUBufferUsage.STORAGE,
+        0, 4,
+    ));
+    data.far_field = pass.create("participating media far field", BufferResourceDescriptor.from(
+        field_bytes,
+        GPUBufferUsage.STORAGE,
+        0, 4,
+    ));
+    // the bin ORs bits into zeroed lists
+    data.group_lists = pass.create("participating media group lists", BufferResourceDescriptor.from(
+        group_lists_bytes,
+        GPUBufferUsage.STORAGE,
+        0, group_lists_bytes,
+    ));
     data.noise_atlas = pass.read(graph_import_texture(graph, scene.volumetrics.noise_atlas.texture, "volumetrics noise atlas"));
 
     data.output0 = pass.create("Participating Media 0", TextureResourceDescriptor.from({
@@ -120,6 +202,7 @@ function graph_integrate_participating_media({
         participating_media0: data.output0,
         participating_media1: data.output1,
         volumetrics_metadata: data.volumetrics_metadata,
+        far_field: data.far_field,
     };
 }
 
@@ -409,6 +492,7 @@ export function graph_build_volumetrics({
     const {
         participating_media0,
         participating_media1,
+        far_field,
     } = graph_integrate_participating_media({
         graph,
         scene: view.scene,
@@ -416,6 +500,7 @@ export function graph_build_volumetrics({
         resolution: volumetric_resolution,
         volumetrics_metadata,
         camera,
+        shader_switches,
     });
 
     const sun_shadow_cascades = graph_build_sun_shadow_volume({
@@ -484,6 +569,7 @@ export function graph_build_volumetrics({
 
         const light_scattering_lut = resources.get(data.light_scattering_lut);
         const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
+        const far_field = resources.get(data.far_field);
 
         const encoder = context.encoder;
 
@@ -513,6 +599,7 @@ export function graph_build_volumetrics({
 
                 // RDR2-style far-field march inputs (used beyond froxel_far)
                 scene_database: view.scene.scene_database_buffer,
+                far_field,
                 light_data: lights.buffer_data,
                 tSunTransmittance: sun_transmittance_lut.obtainView(),
 
@@ -527,6 +614,7 @@ export function graph_build_volumetrics({
     a_data.participating_media1 = a_pass.read(participating_media1);
     a_data.volumetrics_metadata = a_pass.read(volumetrics_metadata);
     a_data.sun_transmittance_lut = a_pass.read(transmittance_lut);
+    a_data.far_field = a_pass.read(far_field);
 
     a_data.output = a_pass.create("Integrated Volumetrics", TextureResourceDescriptor.from({
         resolution: volumetric_resolution,

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.d.ts

@@ -88,6 +88,41 @@ export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL: number;
  * @type {readonly number[]}
  */
 export const PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION: readonly number[];
+/**
+ * The flow map's period, seconds: how long each of the two phases that carry the noise along the
+ * wind field's departure from its far field runs before it resets, half a period apart, each reset
+ * at zero weight. See `chunk_participating_media_noise`.
+ *
+ * **The pulse against the stretch, measured** (RTX 4090, 2026-10-16: the engine's tile read back off
+ * the device, and the GPU fluid read back over a fog volume while a wake circled through it at
+ * 10 m/s beside a vortex, at `GPUFluidComponent`'s defaults):
+ * - the pulse: how much of the field's change is the crossfade rather than the transport, the rms
+ *   of the one over the rms of the other for a uniform departure. It depends only on the reach
+ *   `λ = |d| · P / noise_scale`, tile units a period: about 1 (the noise rebuilds in place as fast as
+ *   it travels, and no travel reads) up to λ ≈ 0.08, 0.47 at 0.32, 0.15 at 1 — features have to move
+ *   about a quarter of a tile, the default tile's feature, before they are seen to move;
+ * - the stretch: the deformation a phase puts on the noise, `σ_max(I − φ · P · ∇d) − 1`, averaged
+ *   over the phases by their weights;
+ * - where the departure reads (|d| ≥ 1 m/s, 2,429 lattice points at 0.5 m), at the default
+ *   `noise_scale` of 32 m, the medians cross at 2.48 s: 1.05 against 0.34 at 1 s, 0.98 against 0.73
+ *   at 2 s, 0.88 against 1.15 at 3 s, 0.77 against 1.60 at 4 s. At a 16 m scale they cross at 2.06 s,
+ *   and over |d| ≥ 0.5 m/s at 2.4 to 2.9 s.
+ *
+ * So 2.5 s, the balance at the engine's default scale. It scales as `sqrt(feature · flow length) /
+ * speed`, so no one period is the balance everywhere.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD: number;
+/**
+ * Below this reach, in tile units a flow period, the departure from the far field takes no flow map:
+ * one tap, the uniform-air path. Ignoring a reach moves the lookup by at most the reach, which moves
+ * the multiplier by at most the tile's steepest gradient times it; the engine's tile, read back off
+ * the device, rises at most 35.3 a tile unit (median 9.6), so at this reach the most the neglect
+ * changes the multiplier is half an `r8unorm` step, below what the tile itself resolves. The reach
+ * ramps in from here to twice here, so the branch is continuous.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD: number;
 /**
  * How the atlas is sampled: trilinear, and clamped — the wrap is done by the skirt and by `fract`
  * on the tile coordinate, never by the sampler, which would wrap the whole atlas.

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PARTICIPATING_MEDIA_NOISE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,0DAFU,MAAM,CAE+C;AAE/D;;;GAGG;AACH,oDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,kDAFU,MAAM,CAE2H;AAE3I;;;GAGG;AACH,qEAA+D;AAE/D;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;;;GAIG;AACH,uDAFU,MAAM,CAE0C;AAE1D;;;;GAIG;AACH,qDAFU,MAAM,CAEwC;AAExD;;;;GAIG;AACH,yDAFU,MAAM,CAE4C;AAE5D;;;;;GAKG;AACH,wDAFU,MAAM,CAE2C;AAE3D;;;;GAIG;AACH,mDAFU,MAAM,CAEwC;AAExD;;;;;GAKG;AACH,oDAFU,MAAM,CAE0C;AAE1D;;;;;GAKG;AACH,uDAFU,SAAS,MAAM,EAAE,CAE+D;AAE1F;;;;GAIG;AACH,2DAFU,iBAAiB,CAKxB;kCAlH+B,kDAAkD"}
+{"version":3,"file":"PARTICIPATING_MEDIA_NOISE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,0DAFU,MAAM,CAE+C;AAE/D;;;GAGG;AACH,oDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,kDAFU,MAAM,CAE2H;AAE3I;;;GAGG;AACH,qEAA+D;AAE/D;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;;;GAIG;AACH,uDAFU,MAAM,CAE0C;AAE1D;;;;GAIG;AACH,qDAFU,MAAM,CAEwC;AAExD;;;;GAIG;AACH,yDAFU,MAAM,CAE4C;AAE5D;;;;;GAKG;AACH,wDAFU,MAAM,CAE2C;AAE3D;;;;GAIG;AACH,mDAFU,MAAM,CAEwC;AAExD;;;;;GAKG;AACH,oDAFU,MAAM,CAE0C;AAE1D;;;;;GAKG;AACH,uDAFU,SAAS,MAAM,EAAE,CAE+D;AAE1F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDAFU,MAAM,CAEyC;AAEzD;;;;;;;;GAQG;AACH,uDAFU,MAAM,CAE6D;AAE7E;;;;GAIG;AACH,2DAFU,iBAAiB,CAKxB;kCAvJ+B,kDAAkD"}

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js

@@ -104,6 +104,43 @@ export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL = 0.37;
  */
 export const PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION = Object.freeze([0.6, 0.48, -0.64]);
 
+/**
+ * The flow map's period, seconds: how long each of the two phases that carry the noise along the
+ * wind field's departure from its far field runs before it resets, half a period apart, each reset
+ * at zero weight. See `chunk_participating_media_noise`.
+ *
+ * **The pulse against the stretch, measured** (RTX 4090, 2026-10-16: the engine's tile read back off
+ * the device, and the GPU fluid read back over a fog volume while a wake circled through it at
+ * 10 m/s beside a vortex, at `GPUFluidComponent`'s defaults):
+ * - the pulse: how much of the field's change is the crossfade rather than the transport, the rms
+ *   of the one over the rms of the other for a uniform departure. It depends only on the reach
+ *   `λ = |d| · P / noise_scale`, tile units a period: about 1 (the noise rebuilds in place as fast as
+ *   it travels, and no travel reads) up to λ ≈ 0.08, 0.47 at 0.32, 0.15 at 1 — features have to move
+ *   about a quarter of a tile, the default tile's feature, before they are seen to move;
+ * - the stretch: the deformation a phase puts on the noise, `σ_max(I − φ · P · ∇d) − 1`, averaged
+ *   over the phases by their weights;
+ * - where the departure reads (|d| ≥ 1 m/s, 2,429 lattice points at 0.5 m), at the default
+ *   `noise_scale` of 32 m, the medians cross at 2.48 s: 1.05 against 0.34 at 1 s, 0.98 against 0.73
+ *   at 2 s, 0.88 against 1.15 at 3 s, 0.77 against 1.60 at 4 s. At a 16 m scale they cross at 2.06 s,
+ *   and over |d| ≥ 0.5 m/s at 2.4 to 2.9 s.
+ *
+ * So 2.5 s, the balance at the engine's default scale. It scales as `sqrt(feature · flow length) /
+ * speed`, so no one period is the balance everywhere.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD = 2.5;
+
+/**
+ * Below this reach, in tile units a flow period, the departure from the far field takes no flow map:
+ * one tap, the uniform-air path. Ignoring a reach moves the lookup by at most the reach, which moves
+ * the multiplier by at most the tile's steepest gradient times it; the engine's tile, read back off
+ * the device, rises at most 35.3 a tile unit (median 9.6), so at this reach the most the neglect
+ * changes the multiplier is half an `r8unorm` step, below what the tile itself resolves. The reach
+ * ramps in from here to twice here, so the branch is continuous.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD = 1 / (2 * 255 * 35.3);
+
 /**
  * How the atlas is sampled: trilinear, and clamped — the wrap is done by the skirt and by `fract`
  * on the tile coordinate, never by the sampler, which would wrap the whole atlas.

package/src/shade/renderer/volumetrics/noise/bake_volumetrics_noise_tile.d.ts

@@ -11,7 +11,8 @@ export function enquire_bake_volumetrics_noise_tile_pipelines(enquiry: PipelineE
  *
  * @param {object} options
  * @param {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} options.command
- * @param {import("../../texture/atlas/GPUTileAtlas3D.js").GPUTileAtlas3D} options.atlas a one-byte-a-texel atlas
+ * @param {import("../../texture/atlas/GPUTileAtlas3D.js").GPUTileAtlas3D} options.atlas a one-byte-a-texel atlas of
+ * cubic tiles: the field has `features` periods along every edge
  * @param {number} options.slot a live slot of it
  * @param {number} options.features base features along each edge of the content, an integer
  * @param {number} options.octaves octaves to sum, 1 to {@link VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT}

package/src/shade/renderer/volumetrics/noise/bake_volumetrics_noise_tile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bake_volumetrics_noise_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/bake_volumetrics_noise_tile.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,uEAFW,eAAe,QAIzB;AAED;;;;;;;;;;;GAWG;AACH;IAN+F,OAAO,EAA3F,OAAO,2CAA2C,EAAE,sBAAsB;IACF,KAAK,EAA7E,OAAO,uCAAuC,EAAE,cAAc;IAC9C,IAAI,EAApB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,OAAO,EAAvB,MAAM;SAqDhB;8BAjFY,OAAO,6CAA6C,EAAE,eAAe"}
+{"version":3,"file":"bake_volumetrics_noise_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/bake_volumetrics_noise_tile.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,uEAFW,eAAe,QAIzB;AAED;;;;;;;;;;;;GAYG;AACH;IAP+F,OAAO,EAA3F,OAAO,2CAA2C,EAAE,sBAAsB;IACF,KAAK,EAA7E,OAAO,uCAAuC,EAAE,cAAc;IAE9C,IAAI,EAApB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,OAAO,EAAvB,MAAM;SAyDhB;8BAtFY,OAAO,6CAA6C,EAAE,eAAe"}