@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -0,0 +1,67 @@
+/**
+ * A participating-media volume's noise multiplier at a world point: a [0, 1] factor on its density
+ * from a tile of the noise atlas, which the importing shader binds as `tParticipatingMediaNoise`
+ * (`texture_3d<f32>`) with `sParticipatingMediaNoise` (a filtering sampler, clamped) — the way
+ * `scene_database` is a binding every reader of the volumes declares for itself — carried by the
+ * scene's wind, which it binds as `wind_field_add_resources` declares it (`wind_field`,
+ * `wind_field_atlas`, `wind_field_sampler`) and `GPUSceneWind.bind` fills.
+ *
+ * **One field, in world space.** The tile repeats every `1 / noise_inverse_scale` metres along
+ * each world axis, so neighbouring volumes with the same settings share one continuous field and a
+ * volume carried by a moving entity has the world's fog flow through it. `noise_offset` is the
+ * scroll, in tile units, already wrapped to [0, 1) by the host; `fract` folds the world position
+ * onto the tile.
+ *
+ * **Two taps for the shape.** A warp tap reads the same tile at half frequency and its own scroll
+ * (`noise_warp_offset`), and displaces the base lookup along a fixed oblique direction by
+ * `noise_warp` tile units times how far the warp value sits from its mean. As the two scrolls
+ * slide against each other the base field changes shape in place, which is the evolution a static
+ * texture otherwise lacks. `noise_warp == 0` is no warp tap; `noise_strength == 0` is none at all —
+ * callers branch on it before calling, uniformly, since it is a property of the volume and not of
+ * the thread.
+ *
+ * **The wind: the far field on the host, the rest here, as a flow map.** The host folds the far
+ * field `v_far(t)` × `noise_wind_factor` (plus the volume's own motion) into `noise_offset`, exactly,
+ * as a running sum. Where the published wind `w(p)` departs from the far field, the departure
+ * `d = (w(p) − v_far(t)) · noise_wind_factor` carries the noise on top, flow-map style: there is no
+ * history at a point to integrate a phase in, and `t · d` would jump by `t · Δd` whenever the local
+ * wind changed. Two phases half a period apart, `φ₀ = fract(s)` and `φ₁ = fract(s + ½)` with
+ * `s = t / P` (`noise_flow_phase`, folded on the host), each move the base lookup by `−d · φₖ · P`
+ * (in tile units), and a triangle weight `1 − |2φ₀ − 1|` crossfades them, so each phase resets
+ * where its weight is zero. The warp tap is shared by both. Bounded by 1 still: a convex blend of
+ * taps of a [0, 1] tile.
+ *
+ * **Uniform air is one tap, the scroll alone.** Below a reach of
+ * `PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD` tile units a period, the base takes one tap at the
+ * scrolled lookup, which is every point outside every cascade and every point whose air moves with
+ * the far field (`wind_field_sample` returns `v_far` exactly there). Above it the reach ramps in,
+ * from zero at the threshold to all of it at twice the threshold, so at the threshold both phases
+ * tap the one lookup and blend to it exactly: the branch is continuous.
+ *
+ * **By the field's shape** ({@link WIND_FIELD_UNIFORM}), the same functions either way:
+ * - as it is (`false`, the default): the flow map wherever the field departs from the far field
+ *   ({@link chunk_participating_media_noise_carried});
+ * - uniform (`true`), no cascades: the field departs from the far field nowhere, and the multiplier is
+ *   the one tap at the scrolled lookup and nothing else ({@link chunk_participating_media_noise_scrolled}),
+ *   which is what the flow map reads there, bit for bit. A pass whose field has no cascades links no
+ *   flow-map code: linked and never run, it cost the froxel build 1.3–1.9 µs a frame (RTX 4090,
+ *   1280×720, camera inside the fog), and the variant without it costs what the scroll alone did.
+ *
+ * The tap and the lookup both share are {@link chunk_participating_media_noise_tap}'s.
+ *
+ * **The entry points:**
+ * - `participating_media_noise_multiplier(volume, position)` samples the wind at `position` itself,
+ *   when the volume feels it;
+ * - `participating_media_noise_multiplier_in_wind(volume, position, wind)` takes the wind there
+ *   from the caller, for a pass that evaluates several volumes at one point and samples it once
+ *   (the froxel build). Pass `wind_field.far_velocity` for a volume that feels no wind.
+ *
+ * Bounded above by 1, which is what keeps `density` the path tracer's majorant.
+ *
+ * @see PARTICIPATING_MEDIA_NOISE the constants
+ * @see shader_volumetrics_noise_tile_bake what the engine's default tile holds
+ * @type {CodeChunkChoice}
+ */
+export const chunk_participating_media_noise: CodeChunkChoice;
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
+//# sourceMappingURL=chunk_participating_media_noise.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_participating_media_noise.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/chunk_participating_media_noise.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,8CAFU,eAAe,CAE+D;gCArExD,0CAA0C"}

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

@@ -0,0 +1,73 @@
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
+import { WIND_FIELD_UNIFORM } from "../../wind/WIND_FIELD_UNIFORM.js";
+import { chunk_participating_media_noise_carried } from "./chunk_participating_media_noise_carried.js";
+import { chunk_participating_media_noise_scrolled } from "./chunk_participating_media_noise_scrolled.js";
+
+/**
+ * A participating-media volume's noise multiplier at a world point: a [0, 1] factor on its density
+ * from a tile of the noise atlas, which the importing shader binds as `tParticipatingMediaNoise`
+ * (`texture_3d<f32>`) with `sParticipatingMediaNoise` (a filtering sampler, clamped) — the way
+ * `scene_database` is a binding every reader of the volumes declares for itself — carried by the
+ * scene's wind, which it binds as `wind_field_add_resources` declares it (`wind_field`,
+ * `wind_field_atlas`, `wind_field_sampler`) and `GPUSceneWind.bind` fills.
+ *
+ * **One field, in world space.** The tile repeats every `1 / noise_inverse_scale` metres along
+ * each world axis, so neighbouring volumes with the same settings share one continuous field and a
+ * volume carried by a moving entity has the world's fog flow through it. `noise_offset` is the
+ * scroll, in tile units, already wrapped to [0, 1) by the host; `fract` folds the world position
+ * onto the tile.
+ *
+ * **Two taps for the shape.** A warp tap reads the same tile at half frequency and its own scroll
+ * (`noise_warp_offset`), and displaces the base lookup along a fixed oblique direction by
+ * `noise_warp` tile units times how far the warp value sits from its mean. As the two scrolls
+ * slide against each other the base field changes shape in place, which is the evolution a static
+ * texture otherwise lacks. `noise_warp == 0` is no warp tap; `noise_strength == 0` is none at all —
+ * callers branch on it before calling, uniformly, since it is a property of the volume and not of
+ * the thread.
+ *
+ * **The wind: the far field on the host, the rest here, as a flow map.** The host folds the far
+ * field `v_far(t)` × `noise_wind_factor` (plus the volume's own motion) into `noise_offset`, exactly,
+ * as a running sum. Where the published wind `w(p)` departs from the far field, the departure
+ * `d = (w(p) − v_far(t)) · noise_wind_factor` carries the noise on top, flow-map style: there is no
+ * history at a point to integrate a phase in, and `t · d` would jump by `t · Δd` whenever the local
+ * wind changed. Two phases half a period apart, `φ₀ = fract(s)` and `φ₁ = fract(s + ½)` with
+ * `s = t / P` (`noise_flow_phase`, folded on the host), each move the base lookup by `−d · φₖ · P`
+ * (in tile units), and a triangle weight `1 − |2φ₀ − 1|` crossfades them, so each phase resets
+ * where its weight is zero. The warp tap is shared by both. Bounded by 1 still: a convex blend of
+ * taps of a [0, 1] tile.
+ *
+ * **Uniform air is one tap, the scroll alone.** Below a reach of
+ * `PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD` tile units a period, the base takes one tap at the
+ * scrolled lookup, which is every point outside every cascade and every point whose air moves with
+ * the far field (`wind_field_sample` returns `v_far` exactly there). Above it the reach ramps in,
+ * from zero at the threshold to all of it at twice the threshold, so at the threshold both phases
+ * tap the one lookup and blend to it exactly: the branch is continuous.
+ *
+ * **By the field's shape** ({@link WIND_FIELD_UNIFORM}), the same functions either way:
+ * - as it is (`false`, the default): the flow map wherever the field departs from the far field
+ *   ({@link chunk_participating_media_noise_carried});
+ * - uniform (`true`), no cascades: the field departs from the far field nowhere, and the multiplier is
+ *   the one tap at the scrolled lookup and nothing else ({@link chunk_participating_media_noise_scrolled}),
+ *   which is what the flow map reads there, bit for bit. A pass whose field has no cascades links no
+ *   flow-map code: linked and never run, it cost the froxel build 1.3–1.9 µs a frame (RTX 4090,
+ *   1280×720, camera inside the fog), and the variant without it costs what the scroll alone did.
+ *
+ * The tap and the lookup both share are {@link chunk_participating_media_noise_tap}'s.
+ *
+ * **The entry points:**
+ * - `participating_media_noise_multiplier(volume, position)` samples the wind at `position` itself,
+ *   when the volume feels it;
+ * - `participating_media_noise_multiplier_in_wind(volume, position, wind)` takes the wind there
+ *   from the caller, for a pass that evaluates several volumes at one point and samples it once
+ *   (the froxel build). Pass `wind_field.far_velocity` for a volume that feels no wind.
+ *
+ * Bounded above by 1, which is what keeps `density` the path tracer's majorant.
+ *
+ * @see PARTICIPATING_MEDIA_NOISE the constants
+ * @see shader_volumetrics_noise_tile_bake what the engine's default tile holds
+ * @type {CodeChunkChoice}
+ */
+export const chunk_participating_media_noise = CodeChunkChoice.from(WIND_FIELD_UNIFORM);
+
+chunk_participating_media_noise.add(false, chunk_participating_media_noise_carried);
+chunk_participating_media_noise.add(true, chunk_participating_media_noise_scrolled);

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

@@ -0,0 +1,14 @@
+/**
+ * {@link chunk_participating_media_noise} in a wind field as it is ({@link WIND_FIELD_UNIFORM}
+ * `false`): the scroll, and on top of it the flow map of the field's departure from the far field,
+ * wherever the field departs. Samples the wind through `chunk_wind_field_sample`.
+ *
+ * Below a reach of {@link PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD} tile units a period, the base is
+ * one tap at the scrolled lookup; above it the reach ramps in, from zero at the threshold to all of it
+ * at twice the threshold, so at the threshold both phases tap the one lookup and blend to it exactly.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_carried: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_participating_media_noise_carried.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_participating_media_noise_carried.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/chunk_participating_media_noise_carried.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,sDAFU,SAAS,CA2DjB;0BA3EwB,oCAAoC"}

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

@@ -0,0 +1,76 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_wind_field_sample } from "../../wind/chunk_wind_field_sample.js";
+import { WIND_FIELD_STRUCT } from "../../wind/WIND_FIELD_STRUCT.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "../PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+import { chunk_participating_media_noise_tap } from "./chunk_participating_media_noise_tap.js";
+import { PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD, PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD } from "./PARTICIPATING_MEDIA_NOISE.js";
+
+/**
+ * {@link chunk_participating_media_noise} in a wind field as it is ({@link WIND_FIELD_UNIFORM}
+ * `false`): the scroll, and on top of it the flow map of the field's departure from the far field,
+ * wherever the field departs. Samples the wind through `chunk_wind_field_sample`.
+ *
+ * Below a reach of {@link PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD} tile units a period, the base is
+ * one tap at the scrolled lookup; above it the reach ramps in, from zero at the threshold to all of it
+ * at twice the threshold, so at the threshold both phases tap the one lookup and blend to it exactly.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_carried = CodeChunk.from(
+    //language=WGSL
+    `
+const PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD: f32 = ${PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD};
+const PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD: f32 = ${PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD};
+
+fn participating_media_noise_multiplier_in_wind(
+    volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref},
+    position: vec3<f32>,
+    wind: vec3<f32>,
+) -> f32 {
+    let u = participating_media_noise_lookup(volume, position);
+
+    // the departure from the far field the host scrolled by, as tile units a flow period
+    let flow = (wind - wind_field.far_velocity) * (volume.noise_wind_factor * PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD * volume.noise_inverse_scale);
+    let reach = length(flow);
+
+    var value: f32;
+
+    if (reach <= PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD) {
+        value = participating_media_noise_tap(volume.noise_slot, u);
+    } else {
+        // 0 at the threshold, where both phases tap u and blend to it exactly, and 1 from twice it
+        let carried = flow * min(reach / PARTICIPATING_MEDIA_NOISE_FLOW_THRESHOLD - 1.0, 1.0);
+
+        let phase0 = fract(volume.noise_flow_phase);
+        let phase1 = fract(volume.noise_flow_phase + 0.5);
+
+        // phase 0's weight: zero where it resets, one half a period later, where phase 1 resets
+        let weight0 = 1.0 - abs(2.0 * phase0 - 1.0);
+
+        let tap0 = participating_media_noise_tap(volume.noise_slot, u - carried * phase0);
+        let tap1 = participating_media_noise_tap(volume.noise_slot, u - carried * phase1);
+
+        // mix's form, so that equal taps blend to themselves exactly
+        value = tap1 + (tap0 - tap1) * weight0;
+    }
+
+    return mix(1.0, value, volume.noise_strength);
+}
+
+fn participating_media_noise_multiplier(volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref}, position: vec3<f32>) -> f32 {
+    var wind = wind_field.far_velocity;
+
+    // a property of the volume, so every thread agrees
+    if (volume.noise_wind_factor != 0.0) {
+        wind = wind_field_sample(position);
+    }
+
+    return participating_media_noise_multiplier_in_wind(volume, position, wind);
+}
+    `, [
+        PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
+        WIND_FIELD_STRUCT.declaration_chunk,
+        chunk_participating_media_noise_tap,
+        chunk_wind_field_sample,
+    ]
+);

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

@@ -0,0 +1,14 @@
+/**
+ * {@link chunk_participating_media_noise} in a uniform wind field ({@link WIND_FIELD_UNIFORM} `true`):
+ * the field has no cascades, so the wind is the far field everywhere and departs from it nowhere, and
+ * the noise is the host's scroll alone — one tap at the scrolled lookup, which is what the flow map
+ * takes at a departure of zero, exactly.
+ *
+ * The wind `participating_media_noise_multiplier_in_wind` is handed is the far field at the point,
+ * whoever sampled it, and is not read.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_scrolled: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_participating_media_noise_scrolled.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_participating_media_noise_scrolled.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/chunk_participating_media_noise_scrolled.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,uDAFU,SAAS,CAuBjB;0BArCwB,oCAAoC"}

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

@@ -0,0 +1,38 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { WIND_FIELD_STRUCT } from "../../wind/WIND_FIELD_STRUCT.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "../PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+import { chunk_participating_media_noise_tap } from "./chunk_participating_media_noise_tap.js";
+
+/**
+ * {@link chunk_participating_media_noise} in a uniform wind field ({@link WIND_FIELD_UNIFORM} `true`):
+ * the field has no cascades, so the wind is the far field everywhere and departs from it nowhere, and
+ * the noise is the host's scroll alone — one tap at the scrolled lookup, which is what the flow map
+ * takes at a departure of zero, exactly.
+ *
+ * The wind `participating_media_noise_multiplier_in_wind` is handed is the far field at the point,
+ * whoever sampled it, and is not read.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_scrolled = CodeChunk.from(
+    //language=WGSL
+    `
+fn participating_media_noise_multiplier_in_wind(
+    volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref},
+    position: vec3<f32>,
+    wind: vec3<f32>,
+) -> f32 {
+    let value = participating_media_noise_tap(volume.noise_slot, participating_media_noise_lookup(volume, position));
+
+    return mix(1.0, value, volume.noise_strength);
+}
+
+fn participating_media_noise_multiplier(volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref}, position: vec3<f32>) -> f32 {
+    return participating_media_noise_multiplier_in_wind(volume, position, wind_field.far_velocity);
+}
+    `, [
+        PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
+        WIND_FIELD_STRUCT.declaration_chunk,
+        chunk_participating_media_noise_tap,
+    ]
+);

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

@@ -0,0 +1,21 @@
+/**
+ * What both of {@link chunk_participating_media_noise}'s alternatives read the tile through:
+ * - `participating_media_noise_tap(slot, u)`: one trilinear tap of a slot's tile at a tile
+ *   coordinate, wrapped;
+ * - `participating_media_noise_lookup(volume, position)`: where a volume's base tap lands for a world
+ *   point before the wind's departure carries it, the scroll and the warp applied, in tile units.
+ *
+ * Reads `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, as the importing shader binds them.
+ *
+ * **The slot's texels.** The atlas is tiles of `PARTICIPATING_MEDIA_NOISE_TILE_SIZE` texels — the
+ * content and a one-texel skirt holding the content wrapped — in a grid the texture's own
+ * dimensions describe, x fastest and z slowest, placed by `tile_atlas_slot_origin` as the atlas
+ * places it. A tile coordinate in [0, 1) lands on the content; the trilinear footprint at its edges
+ * reaches exactly one texel into the skirt, which is why the skirt is there and why the sampler is
+ * clamped rather than repeating.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_tap: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_participating_media_noise_tap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_participating_media_noise_tap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/chunk_participating_media_noise_tap.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAFU,SAAS,CA4CjB;0BAzEwB,oCAAoC"}

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

@@ -0,0 +1,74 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_tile_atlas_slot_origin } from "../../texture/atlas/chunk_tile_atlas_slot_origin.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "../PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+import {
+    PARTICIPATING_MEDIA_NOISE_TILE_BORDER,
+    PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE,
+    PARTICIPATING_MEDIA_NOISE_TILE_SIZE,
+    PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION,
+    PARTICIPATING_MEDIA_NOISE_WARP_SCALE
+} from "./PARTICIPATING_MEDIA_NOISE.js";
+
+const [warp_x, warp_y, warp_z] = PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION;
+
+/**
+ * What both of {@link chunk_participating_media_noise}'s alternatives read the tile through:
+ * - `participating_media_noise_tap(slot, u)`: one trilinear tap of a slot's tile at a tile
+ *   coordinate, wrapped;
+ * - `participating_media_noise_lookup(volume, position)`: where a volume's base tap lands for a world
+ *   point before the wind's departure carries it, the scroll and the warp applied, in tile units.
+ *
+ * Reads `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, as the importing shader binds them.
+ *
+ * **The slot's texels.** The atlas is tiles of `PARTICIPATING_MEDIA_NOISE_TILE_SIZE` texels — the
+ * content and a one-texel skirt holding the content wrapped — in a grid the texture's own
+ * dimensions describe, x fastest and z slowest, placed by `tile_atlas_slot_origin` as the atlas
+ * places it. A tile coordinate in [0, 1) lands on the content; the trilinear footprint at its edges
+ * reaches exactly one texel into the skirt, which is why the skirt is there and why the sampler is
+ * clamped rather than repeating.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_noise_tap = CodeChunk.from(
+    //language=WGSL
+    `
+const PARTICIPATING_MEDIA_NOISE_TILE_SIZE: u32 = ${PARTICIPATING_MEDIA_NOISE_TILE_SIZE}u;
+const PARTICIPATING_MEDIA_NOISE_TILE_CONTENT: f32 = ${PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE}.0;
+const PARTICIPATING_MEDIA_NOISE_TILE_BORDER: f32 = ${PARTICIPATING_MEDIA_NOISE_TILE_BORDER}.0;
+const PARTICIPATING_MEDIA_NOISE_WARP_SCALE: f32 = ${PARTICIPATING_MEDIA_NOISE_WARP_SCALE};
+const PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION: vec3<f32> = vec3<f32>(${warp_x}, ${warp_y}, ${warp_z});
+
+// one trilinear tap of a slot's tile at a tile coordinate, which may be anything: it is wrapped here
+fn participating_media_noise_tap(slot: u32, u: vec3<f32>) -> f32 {
+    let atlas = textureDimensions(tParticipatingMediaNoise);
+    let tile = vec3<u32>(PARTICIPATING_MEDIA_NOISE_TILE_SIZE);
+
+    // the footprint the bound texture was built with, read off the texture itself
+    let origin = vec3<f32>(tile_atlas_slot_origin(slot, atlas.xy / tile.xy, tile));
+
+    // content texel c is centred at origin + border + c + 0.5, so a tile coordinate t in [0, 1) is
+    // the texel coordinate origin + border + t * content; no half-texel term
+    let texel = origin + PARTICIPATING_MEDIA_NOISE_TILE_BORDER + fract(u) * PARTICIPATING_MEDIA_NOISE_TILE_CONTENT;
+
+    return textureSampleLevel(tParticipatingMediaNoise, sParticipatingMediaNoise, texel / vec3<f32>(atlas), 0.0).r;
+}
+
+// the base tap's tile coordinate for a world point: scrolled, and displaced by the warp tap
+fn participating_media_noise_lookup(volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref}, position: vec3<f32>) -> vec3<f32> {
+    let base = position * volume.noise_inverse_scale;
+
+    var u = base + volume.noise_offset;
+
+    if (volume.noise_warp > 0.0) {
+        let warp = participating_media_noise_tap(volume.noise_slot, base * PARTICIPATING_MEDIA_NOISE_WARP_SCALE + volume.noise_warp_offset);
+
+        u += (warp - 0.5) * volume.noise_warp * PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION;
+    }
+
+    return u;
+}
+    `, [
+        PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
+        chunk_tile_atlas_slot_origin,
+    ]
+);

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

@@ -0,0 +1,10 @@
+/**
+ * The most octaves one bake sums. A per-thread budget in the sense of the engine's loop rule: at
+ * 8 the finest octave of a 128³ tile is already below one texel a wavelength, so nothing past it
+ * can land in the texture.
+ * @type {number}
+ */
+export const VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT: number;
+export const shader_volumetrics_noise_tile_bake: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_volumetrics_noise_tile_bake.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_volumetrics_noise_tile_bake.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/shader_volumetrics_noise_tile_bake.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,uDAFU,MAAM,CAE0C;AAuG1D,+DAIG;8BAtH2B,+BAA+B"}

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

@@ -0,0 +1,121 @@
+import { chunk_psrdnoise3 } from "../../shader/chunk/noise/psrdnoise/chunk_psrdnoise3.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 { VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT } from "./VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.js";
+
+/**
+ * The most octaves one bake sums. A per-thread budget in the sense of the engine's loop rule: at
+ * 8 the finest octave of a 128³ tile is already below one texel a wavelength, so nothing past it
+ * can land in the texture.
+ * @type {number}
+ */
+export const VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT = 8;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("settings", VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT)
+    .addStorageBuffer("output", WebGPUArray.u32, true);
+
+/**
+ * Bakes one noise tile — content and skirt — into a byte block, four texels a word.
+ *
+ * **The field.** Three octaves (by default) of `psrdnoise3`, lacunarity 2, gain 0.5, each octave
+ * at an integer period in lattice units across the content so that each one tiles exactly: the
+ * base at `features` periods per edge, the next at twice that, and so on. Every octave is
+ * offset by a constant times its index so the doubled lattices do not sit on the base one's
+ * corners. The sum is normalised by the amplitudes and remapped with `smoothstep(-0.6, 0.6)` —
+ * psrdnoise's fBm sits in about ±0.7 — into the [0, 1] multiplier the volumes apply to density. The
+ * remap is baked rather than applied at sample time so that a user tile is a multiplier too, with
+ * nothing more to say about it.
+ *
+ * **The skirt is the content wrapped**, computed here by wrapping the texel index rather than
+ * copied afterwards — the same rule `tile_atlas_bordered_block` applies on the host, so a tile
+ * baked here and one written there are the same shape.
+ *
+ * **The block.** Rows of `words_per_row` u32s, four `r8unorm` texels a word, `tile_size` rows an
+ * image, `tile_size` images: the layout `copyBufferToTexture` reads when the row stride is padded
+ * to the copy alignment. One thread writes one word; a lane past the tile's edge writes nothing
+ * into it, so the padding words stay zero.
+ *
+ * Runs once per tile at start-up (the engine's default) and never per frame. Deterministic: the
+ * same settings give the same bytes on every device the hash agrees on, which is what lets the
+ * emulator bake a small one in a spec.
+ *
+ * @see bake_volumetrics_noise_tile the driver
+ * @see chunk_participating_media_noise the reader
+ */
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT: u32 = ${VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT}u;
+
+// keeps each octave's lattice off the corners of the one below it
+const VOLUMETRICS_NOISE_TILE_OCTAVE_OFFSET: vec3<f32> = vec3<f32>(17.0, 31.0, 47.0);
+
+// the multiplier a texel holds, from where it sits in the tile: the skirt reads the content wrapped
+fn volumetrics_noise_tile_texel(texel: vec3<u32>) -> f32 {
+    let n = settings.content_size;
+
+    // (texel - border) mod n, kept in u32: border <= n, so one extra period is enough
+    let c = (texel + vec3<u32>(n - settings.border)) % vec3<u32>(n);
+
+    // texel centres, across the content as [0, 1)
+    let p = (vec3<f32>(c) + 0.5) / f32(n);
+
+    let octaves = min(settings.octaves, VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT);
+
+    var sum = 0.0;
+    var amplitude = 1.0;
+    var norm = 0.0;
+
+    for (var k = 0u; k < octaves; k++) {
+        // an integer period per octave, so each one tiles the content exactly
+        let period = settings.features * f32(1u << k);
+        let offset = VOLUMETRICS_NOISE_TILE_OCTAVE_OFFSET * f32(k);
+
+        sum += psrdnoise3(p * period + offset, vec3<f32>(period), 0.0).x * amplitude;
+        norm += amplitude;
+        amplitude *= 0.5;
+    }
+
+    return smoothstep(-0.6, 0.6, sum / norm);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn main(
+    @builtin(global_invocation_id) gid: vec3<u32>
+) {
+    let tile = settings.tile_size;
+    let x0 = gid.x * 4u;
+
+    if (x0 >= tile || gid.y >= tile || gid.z >= tile) {
+        return;
+    }
+
+    var word = 0u;
+
+    for (var lane = 0u; lane < 4u; lane++) {
+        let x = x0 + lane;
+
+        if (x < tile) {
+            let value = volumetrics_noise_tile_texel(vec3<u32>(x, gid.y, gid.z));
+
+            word |= u32(clamp(value, 0.0, 1.0) * 255.0 + 0.5) << (lane * 8u);
+        }
+    }
+
+    output[(gid.z * tile + gid.y) * settings.words_per_row + gid.x] = word;
+}
+    `, [
+        chunk_psrdnoise3,
+    ]
+);
+
+export const shader_volumetrics_noise_tile_bake = ComputeShader.from({
+    label: "Volumetrics / bake noise tile",
+    resources,
+    body,
+});

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

@@ -7,6 +7,12 @@
  * @type {number[]}
  */
 export const VOLUMETRICS_IRRADIANCE_WORKGROUP_RESOLUTION: number[];
+/**
+ * The most point lights, and separately spot lights, of a froxel's cluster cell this pass adds, each with
+ * its shadow tap. Chosen, not derived. Past it the rest of that type's list in the cell goes unshaded: the highest ids, except within one 32-light window where the GPU's lane order decides (PROPOSAL_HIERARCHICAL, I.6).
+ * @type {number}
+ */
+export const VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET: number;
 /**
  * The froxel irradiance volume (`chunk_volumetrics_irradiance_sh`): what a lit particle standing in a
  * froxel is lit by. Starts from the froxel GI stage's volume and adds every directional, point and

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

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_build_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_irradiance.js"],"names":[],"mappings":"AAqCA;;;;;;;GAOG;AACH,0DAFU,MAAM,EAAE,CAEmD;AAwKrE;;;;;;;;;GASG;AACH,kDAFU,aAAa,CAMpB;8BA3M2B,4BAA4B"}
+{"version":3,"file":"shader_volumetrics_build_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_irradiance.js"],"names":[],"mappings":"AAqCA;;;;;;;GAOG;AACH,0DAFU,MAAM,EAAE,CAEmD;AAErE;;;;GAIG;AACH,kDAFU,MAAM,CAEsC;AA0KtD;;;;;;;;;GASG;AACH,kDAFU,aAAa,CAMpB;8BApN2B,4BAA4B"}

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

@@ -45,6 +45,13 @@ import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
  */
 export const VOLUMETRICS_IRRADIANCE_WORKGROUP_RESOLUTION = [8, 8, 1];
 
+/**
+ * The most point lights, and separately spot lights, of a froxel's cluster cell this pass adds, each with
+ * its shadow tap. Chosen, not derived. Past it the rest of that type's list in the cell goes unshaded: the highest ids, except within one 32-light window where the GPU's lane order decides (PROPOSAL_HIERARCHICAL, I.6).
+ * @type {number}
+ */
+export const VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET = 32;
+
 const resources = new ShaderResourceSetDescriptor();
 
 // The froxel irradiance volume (chunk_volumetrics_irradiance_sh): luma SH2 in one, chroma in the .rg
@@ -151,7 +158,8 @@ fn main(
     let point_count = light_cluster_count_point(cluster_metadata.counts);
     let spot_count = light_cluster_count_spot(cluster_metadata.counts);
 
-    for (var j = 0u; j < point_count; j++) {
+    // Budget: VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET
+    for (var j = 0u; j < min(point_count, ${VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET}u); j++) {
         let light_index = cluster_data[cluster_offset + j];
         let direct_light = get_point_light_info_by_index(&light_data, light_index, position_ws);
 
@@ -164,7 +172,8 @@ fn main(
         irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
     }
 
-    for (var k = 0u; k < spot_count; k++) {
+    // Budget: VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET
+    for (var k = 0u; k < min(spot_count, ${VOLUMETRICS_IRRADIANCE_LIGHT_BUDGET}u); k++) {
         let light_index = cluster_data[cluster_offset + point_count + k];
         let direct_light = get_spot_light_info_by_index(&light_data, light_index, position_ws);
 

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

@@ -15,6 +15,13 @@
  * @type {number[]}
  */
 export const VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION: number[];
+/**
+ * The most point lights, and separately spot lights, of a froxel's cluster cell the fog's in-scatter adds.
+ * Each one marches the medium toward the light and takes a shadow tap, the dearest per-light work here.
+ * Chosen, not derived. Past it the rest of that type's list in the cell goes unshaded: the highest ids, except within one 32-light window where the GPU's lane order decides (PROPOSAL_HIERARCHICAL, I.6).
+ * @type {number}
+ */
+export const VOLUMETRICS_LIGHTING_LIGHT_BUDGET: number;
 export const shader_volumetrics_build_lighting: ComputeShader;
 import { ComputeShader } from "../shader/ComputeShader.js";
 //# sourceMappingURL=shader_volumetrics_build_lighting.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_build_lighting.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_lighting.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;GAeG;AACH,wDAFU,MAAM,EAAE,CAEiD;AAiXnE,8DAIE;8BA9Z4B,4BAA4B"}
+{"version":3,"file":"shader_volumetrics_build_lighting.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_lighting.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;GAeG;AACH,wDAFU,MAAM,EAAE,CAEiD;AAEnE;;;;;GAKG;AACH,gDAFU,MAAM,CAEoC;AAmXpD,8DAIE;8BAxa4B,4BAA4B"}