@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/volumetrics/VOLUMETRIC_NOISE_PLAN_2026_10_15.md

@@ -0,0 +1,336 @@
+# Noise for participating-media volumes — design brief, 2026-10-15
+
+Status: **revision (c), built.** Written against the tree at 59861de99; the implementation is what
+the tree beside this file holds, and `NOTES.md` (2026-10-15) has the device numbers. Revisions (a)
+and (b) proposed a procedural field and then a texture with a stack of phases; Alex's answers
+(§6) settled on one static texture per slot in a general 3-D tile atlas, evolution by scrolling and
+a domain warp, no stacks, no clock. §4 and §5 describe what was built; §7 is what was left open.
+
+The ask: noise-modulated density on `ParticipatingMedia` volumes with a simple API and a cost that
+stays flat. The starting concept was a fixed number of octaves of 4-D noise, sampled in world
+space, with a per-volume scale and temporal rate, a per-volume lerp between uniform and noisy so one
+shader path serves both, and a global wind vector.
+
+## 1. What the tree had
+
+Facts, read from the sources, each of which shaped the design.
+
+**The volume model is a unit box posed by a matrix, carrying `density`, a particle spec, and an
+edge fade.** `PARTICIPATING_MEDIA_VOLUME_STRUCT` was `particle_spec`, `transform`,
+`transform_inverse`, `fade_distance`, `density` — a row in the scene database, rows packed from 0
+and rewritten whole whenever `SceneVolumetrics.version` moves. The renderer-side
+`ParticipatingMediaVolume` carried six dead stub fields (`noise_scale/amplitude/offset/velocity/
+evolution_speed`, `time`) from an older version of this very concept; nothing read them. Deleted.
+
+**The froxel density pass had no sample point.** `shader_volumetrics_build_participating_media`
+runs a 16×16 workgroup per z-slice over `ceil(w/16) × ceil(h/16) × 64` froxels — 120×68×64 =
+522,240 at 1080p, 2,073,600 at 2160p. Per froxel it builds the slab's world frustum (the z edges
+carry the per-column jitter), then for every volume row: reject on `aabb3_intersects_frustum`,
+estimate `frustum_unit_box_coverage` (8 three-plane intersections), evaluate the edge fade at the
+midpoint of the centre ray's intersection with the box, and accumulate `density × coverage × fade`.
+The density was a slab average, never a value at a point. Adding noise meant choosing a point, and
+the rule from 2026-10-09 applies — a froxel's value is evaluated at a per-frame jittered point,
+never a fixed lattice, or a large particle reading the volume shows the lattice as seams.
+
+**The lighting pass reads the density textures at a jittered point and the TAA integrates it.**
+STBN at the `(37, 71)` decorrelation offset, the 3-D TAA at 0.95, about 39 effective frames,
+reprojected by camera motion only. A density field that moves in world space is averaged over the
+window, not reprojected.
+
+**Nothing downstream re-evaluates the volumes.** The sun's optical-depth cascades and the
+local-light march both read `tParticipatingMedia1`, the froxel extinction texture. Noise costs once,
+in the density pass, never per shadow step.
+
+**The path tracer evaluates the volumes analytically and needs a majorant.**
+`participating_media_volume_density_at(volume, p)` is bounded above by `density`, and
+`chunk_medium_volumes`'s piece majorant is `Σ density × extinction`. The noise had to be a factor
+in [0, 1], applied inside that one function, or the null-collision estimator goes biased.
+
+**psrdnoise was in the tree with a GPU consumer already.** `chunk_psrdnoise3(x, period, alpha)`
+tiles at any integer period up to 289 on each axis. That property is what makes the bake exact:
+each octave gets an integer period across the tile, so each tiles on its own.
+
+**There was a 3-D slot atlas, a slot allocator, and a texture that resizes with its contents.**
+`GPUGeometrySDFManager` packs 50³ SDF slots into one 3-D texture and grows; `PageSlotAllocator` is
+an O(1) free list; `GPUTextureContext.resize(…, true)` copies the old extent across. None was a
+general tile atlas. The 2-D terrain atlas is a rect packer for arbitrary patches, a different thing.
+Brixelizer carries its own 8³ brick SDF atlas (the FFX port) and was left alone, as asked.
+
+**WebGPU has no bindless and no compressed 3-D textures.** A per-volume texture is an atlas or
+nothing, and the atlas is `r8unorm`: BC4 is 2-D only there. And no `r8unorm` storage texture in
+core WebGPU, which is why the bake writes a byte block into a storage buffer and copies it in.
+
+**Froxels are long in z.** On the 64-slice log curve a slab is ≈16% of its depth (≈8 m at 50 m,
+≈79 m at 500 m); a 16-px tile at 1080p is ≈1.4% of depth across. Features finer than the slab are
+averaged by the jitter and the TAA into a lower-contrast mean, so distant fog goes uniform on its own.
+
+## 2. What the field ships
+
+Tagged **VERIFIED** where the slides or source were read, **SECONDARY** where only documentation
+or a search summary was, **NOT RE-READ** where the material exists but was not opened.
+
+**Smolder — IO Interactive, 007 First Light, SIGGRAPH 2026 Advances (VERIFIED, slides + notes).**
+Not a noise system: a per-pixel raymarcher over baked animated density (OpenVDB frames in a custom
+sparse brick format, 4³ bricks stored 5³, 4 bits a voxel), 4-moment volumetric shadows on async
+compute, segment-based overlap culling (4 volumes), an adaptive lighting rate. No temporal
+filtering inside, blue noise per pixel, FSR's reactive mask. The density lookup "was only a small
+fraction" of the per-sample cost; and the one thing they refused was a fallback that makes artists
+"author content twice". 450 volumes shipped. Slides:
+`advances.realtimerendering.com/s2026/content/AlexanderMueller_Smolder_Siggraph26.pdf`.
+
+**Enshrouded — Keen Games, GPC 2025 "The fog is lifting" (VERIFIED, slides).** A froxel volume
+(160×90×64, to 10 km, temporally accumulated on the populate pass only) for atmosphere, weather and
+VFX-injected box volumes — `densityTexture, uvOffset, uvScale, density, falloff, …` — and a
+half-resolution ray march for the dense shroud over a world voxel volume (16³ tiles with a
+"half voxel border on each side for seamless trilinear filtering"). **Detail noise is baked**:
+Nubis-Cubed "Curly-Alligator" and "Alligator" types, "tileable, 128x128x128 four channels
+uncompressed", eroding density at ray-march samples. Slides on
+`static.graphicsprogrammingconference.com/public/2025/talks/the-fog-is-lifting-volumetric-rendering-enshrouded/`.
+The GPC 2024 talk (Lukas Feller, linked at the top of `NOTES.md`) is video only.
+
+**Assassin's Creed 4 — Wronski, SIGGRAPH 2014 (VERIFIED).** "Just one octave of Perlin noise that
+is animated by wind. We tried using multiple octaves, but in the end difference was rather subtle
+for added cost." Density and lighting 0.43 ms on PS4 at 160×90×64.
+
+**Bevy `scrolling_fog` (VERIFIED, source).** A repeating 3-D noise texture, a
+`density_texture_offset` the app advances on the CPU by `velocity × dt`, jitter under TAA.
+
+**Godot 4 FogMaterial (SECONDARY).** A static 3-D `density_texture` in clamped local box space,
+height falloff, edge fade; animation needs a custom shader. **Unity HDRP (SECONDARY):** 3-D mask
+texture, scroll speed and tiling per axis. **Unreal 5.4 (VERIFIED, local source):** local fog
+volumes are analytic (radial + exponential height, no noise); froxel fog density comes from
+Volume-domain materials evaluated per froxel at a jittered slice depth. **Frostbite 2015, RDR2
+2019, Nubis Cubed 2023 (NOT RE-READ):** PPTX only, or cited through Enshrouded.
+
+**The pattern.** Froxel fog ships one or two octaves of 3-D noise scrolled by wind, or a baked
+tileable 3-D texture eroding a density; hero effects are baked animated voxels. The 3-D texture is
+the universal artist hook, and 128³ is the size the two most recent references use.
+
+## 3. What it costs
+
+Per (froxel, volume) the noise is two trilinear `r8unorm` taps into an atlas of a few MiB (one tap
+when `noise_warp == 0`) plus ~25 scalar ops of coordinate arithmetic, against the ~300 ops the
+coverage estimator already spends per volume in the same loop. Paid only inside `aabb_intersects`;
+a froxel with no volume pays nothing, and a volume at `noise_strength == 0` branches around it
+uniformly, so a scene with no noisy volume costs what it did before. The device numbers, taken by
+the paired protocol in `volumetrics_froxel/measure.js` at 2160p, are in `NOTES.md` (2026-10-15).
+
+## 4. The concept, item by item, as built
+
+**Fixed number of octaves — 3, baked into the default tile.** Lacunarity 2, gain 0.5, three
+octaves of `psrdnoise3` at integer periods 4, 8 and 16 lattice units across the content, each
+offset by a constant times its index so the doubled lattices do not sit on the base one's corners.
+The finest octave is 8 texels a wavelength in a 128³ tile. At runtime the octave count is not a
+parameter: it is whatever the texture holds, and a user tile may hold one or ten at the same cost.
+
+**4-D noise — dropped (F1), on Alex's call.** "3-D preserves mass/volume better perceptually; 4-D
+is great for variation but with discrete samples not worth it, blurrier borders for little benefit
+and 2x taps." No phase stack either, for memory. The evolution is **scroll plus a domain warp**: a
+second tap of the same tile at half frequency and its own, slower scroll 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 (ratio 0.37) the base field changes shape in
+place. `noise_warp == 0` is one tap and a field that only slides.
+
+**Time tick / supplied time — no clock at all.** The scroll is a **phase on the volume**, two
+`[0, 1)³` offsets (`noise_offset`, `noise_warp_offset`) advanced once a frame by
+`participating_media_volume_advance_noise(volume, velocity, dt)` in f64 and wrapped there — a
+running sum, so a change of wind never jumps the field and a session running for days never grows
+a number. `ParticipatingMediaSystem.update(dt)` is the caller for an ECS scene; a playground calls
+it from its loop. Not called, the field stands still, which is what an accumulating reference
+wants. The GPU never multiplies a velocity by a time.
+
+**Temporal scale per volume — became `noise_warp`.** A rate had no meaning without a 4th
+dimension; the warp amount is the knob that sets how much the field changes shape as it moves.
+
+**World-space sampling — kept, with repeat.** The tile repeats every `noise_scale` metres along
+each world axis; `fract` folds the world position onto the tile. 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. User tiles must tile seamlessly; the engine's does by construction.
+
+**Noise scale per volume — one scalar, metres per tile repeat.** `noise_scale`, default 32 m,
+which with the default tile's four base features puts them 8 m apart and the finest octave at 2 m.
+
+**Lerp between noisy and uniform — `noise_strength ∈ [0, 1]`, blending to the texture's [0, 1]
+value.** `density(p) = density × fade(p) × mix(1, tile(p), strength)`. Bounded by `density`, so the
+tracer's majorant, the ray spans and the froxel coverage arithmetic are untouched. The remap that
+shapes the wisps — `smoothstep(−0.6, 0.6, fBm)`, psrdnoise's fBm sits in about ±0.7 — is baked, so
+the texture *is* the multiplier and a user tile is one too, with nothing more to say.
+
+**Uniform path.** `noise_strength == 0` branches around the taps inside the volume loop: a property
+of the volume, identical for every thread, so a uniform branch and not a variant.
+
+**Global wind — `SceneVolumetrics.wind`, felt per medium.** Per Alex's F7: effective velocity
+`= wind × noise_wind_factor + noise_velocity`, two explicit fields on the component, folded by the
+system into the phase. The row carries phases only. *Superseded 2026-10-16 (GPU fluid S3,
+`GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §6): `SceneVolumetrics.wind` is removed, and a scroll
+writes each row's phase words through `SceneVolumetrics.invalidate_noise()` instead of repacking the
+table. The phases fold the scene's far field (`GPUFluidSystem.far_field`, still air without one);
+the fluid's departure from it is sampled on the GPU wherever the noise is evaluated and carries the
+noise as a flow map, on a flow clock the host folds into the row (`noise_flow_phase`, period 2.5 s),
+scaled by `noise_wind_factor`, which the row now carries too. A per-volume read-back of the wind was
+built first and withdrawn on Alex's word: the data is on the GPU. The scroll also changed sign: it
+had carried the noise upwind.*
+
+**Where the froxel pass evaluates it.** Once per froxel, before the volume loop, a world point
+inside the slab at an STBN jitter with a **third** decorrelation offset `(53, 97)` — the aerial pass
+owns zero and the lighting pass `(37, 71)`, and two passes drawing the same number lock their
+nuisance variables together, which biases the estimate and no TAA window recovers it. Per volume
+inside `aabb_intersects`, the multiplier at that point scales the slab's weight. The slab's z jitter
+is already per frame, so the point moves on all three axes.
+
+**Band limiting — none (F2).** No mips (a one-texel skirt is wrong from level 1 down, and the
+tracer samples one level anyway), no octave skipping; the texture is band-limited at its texel and
+the jitter plus the TAA average the froxel.
+
+**What the path tracer gets.** The same `participating_media_volume_density_at`, which now needs
+`tParticipatingMediaNoise` and `sParticipatingMediaNoise` bound by every shader that imports it:
+the accumulating tracer, `graph_path_trace_scene`, the Brick4 probe bake, both lightmap viz bakes
+and the deprecated LPV trace all declare and bind them.
+
+**The TAA envelope — a stated limit.** At 0.95 the history spans ≈39 frames, 0.65 s at 60 Hz; a
+feature scrolls `|v| × 0.65 s` inside that window. Wind at a few m/s on 8 m features is fine; 10 m/s
+on 2 m features is mush, and a history reprojected by the scroll is a separate piece of work.
+
+## 5. The design, in one place
+
+### 5.1 `GPUTileAtlas3D` — general, one instance for the volumetrics
+
+`shade/renderer/texture/atlas/GPUTileAtlas3D.js`. One 3-D `GPUTextureContext` of one format, cut
+into tiles of `content_size + 2·border` texels, slots linear (x fastest, z slowest), handed out by
+a free list that reuses the most recently freed slot first.
+
+- `new GPUTileAtlas3D({ device, format, content_size, border, slots_x, slots_y, capacity, usage, label })`,
+  every argument required. `slots_x`/`slots_y` are the starting footprint; `capacity` is rounded
+  up to whole z layers of it. `usage` is how the clients bind the texture (`TEXTURE_BINDING`,
+  `STORAGE_BINDING`); the atlas adds the `COPY_DST | COPY_SRC` its writes and grows need (added
+  2026-10-16 for the SDF manager, whose build stores into its tiles).
+- `allocate()` returns a slot and, when none is free, **grows the texture by a layer**, copying the
+  old extent across (`resize(…, true)`; x and y do not change, so every tile keeps its origin).
+  **Once z is at `maxTextureDimension3D` it widens instead** (2026-10-16, Alex's design): the
+  smaller of x and y doubles (x on a tie, capped at the device), the layers halve (+1 for the slot
+  being allocated), and every tile handed out is copied — in runs along x, a whole old row per
+  copy when a side doubles — to where its slot sits under the new footprint, through
+  `GPUTextureContext.replace`. A slot keeps its index and texels; its origin moves. Rare and as
+  costly as a full copy. The ceiling is `capacity_limit`, the device's limit in tiles cubed; past
+  it, `allocate` throws with the numbers. `free(slot)`, `is_live(slot)`, `live_count`.
+- `write(slot, content)` takes `content_size³` texels and builds the skirt on the host
+  (`tile_atlas_bordered_block`, pure and exported: the skirt is the content wrapped) in one
+  `writeTexture`. `copy_from_buffer(encoder, slot, buffer, offset, bytes_per_row)` lands a whole
+  bordered tile a device producer wrote, rows padded to the copy alignment.
+- `slot_origin(slot, out)` is the same arithmetic in JS and WGSL.
+- A grow replaces the `GPUTexture` and a widen moves every tile; take a view, the footprint or an
+  origin after allocating, never across an `allocate`. The frame graph imports the texture per
+  frame and the noise shader takes the footprint from `textureDimensions`, so the passes are fine
+  by construction.
+
+The volumetrics instance (`PARTICIPATING_MEDIA_NOISE.js`): `r8unorm`, content 128, border 1
+(tile 130), footprint 2×1, capacity 2 — the engine's tile and one spare, 4.4 MB — growing by 2
+slots (4.4 MB) a layer to 30 on a 2048-limit device, then widening. Per scene, on `GPUSceneVolumetrics.noise_atlas`:
+a volume names its tile by slot and the volumes are the scene's.
+
+`GPUGeometrySDFManager` is the second instance (G4, 2026-10-16): `r32float`, content 50, border 0
+(every reader loads inside its tile and clamps the far tap to the last texel, and a wrapped skirt
+would be wrong for a distance field anyway), starting footprint 4×4 — the 16 slots it started with,
+and its smallest growth step — to 40 layers (640 slots, 320 MB) on a 2048-limit device, then
+widening to 8×4×21 and on. A slot is its geometry's id, so it claims slots in order and frees none.
+Brixelizer's atlas is not migrated.
+
+### 5.2 The engine's default tile — slot 0, baked on first update
+
+`shader_volumetrics_noise_tile_bake` + `bake_volumetrics_noise_tile`: a compute dispatch over the
+whole 130³ tile — skirt included, by wrapping the texel index, the same rule the host applies — into
+a transient storage buffer of 256-byte rows, four `r8unorm` texels a word, then
+`copyBufferToTexture` into the slot, in one command stream. Three octaves at periods 4/8/16,
+`features` 4, remap baked. Runs once, from `GPUSceneVolumetrics.update` the first time it is
+called (a bake needs a command stream and the constructor has none). Deterministic, so the
+emulator bakes small tiles in `shader_volumetrics_noise_tile_bake.spec.js`.
+
+### 5.3 The API
+
+ECS, flat on `ParticipatingMedia`:
+
+    noise_strength    = 0        // [0, 1]; 0 = uniform, nothing evaluated
+    noise_scale       = 32       // metres per tile repeat (default tile: 8 m base features)
+    noise_warp        = 0.1      // tile units the warp may displace by; 0 = one tap, slide only
+    noise_velocity    = [0,0,0]  // m/s, the medium's own motion, added to the wind
+    noise_wind_factor = 1        // how much of the scene wind it feels
+    noise_texture     = 0        // atlas slot; 0 = the engine's
+
+Scene: `SceneVolumetrics.wind` (m/s) — removed 2026-10-16, see above. Tiles: `GPUSceneVolumetrics.noise_atlas` —
+`allocate()`, `write(slot, Uint8Array(128³))`, `free(slot)`.
+
+Renderer-side `ParticipatingMediaVolume`: `noise_strength`, `noise_scale`, `noise_warp`,
+`noise_slot`, and the phase state `noise_offset`, `noise_warp_offset`, advanced by
+`participating_media_volume_advance_noise(volume, velocity_m_s, dt_s)`, which returns whether
+anything moved.
+
+GPU row, appended to `PARTICIPATING_MEDIA_VOLUME_STRUCT`: `noise_offset: vec3f`,
+`noise_warp_offset: vec3f`, `noise_slot: u32`, `noise_strength: f32`, `noise_inverse_scale: f32`,
+`noise_warp: f32`. Packed by `GPUSceneVolumetrics` whenever the version moves — which, while any
+volume's phase moves, is every frame (tens of rows). *Since 2026-10-16 a scroll moves
+`SceneVolumetrics.noise_version` instead, and only the moved rows' phase words go up: seven, with
+`noise_flow_phase`; `noise_wind_factor` and `noise_flow_phase` sit in the padding after `density`.*
+
+Serialization: `ParticipatingMediaSerializationAdapter` version 1 (eighteen doubles),
+`ParticipatingMediaSerializationUpgrader_0_1` fills a version-0 save with the defaults.
+
+### 5.4 The shader
+
+`chunk_participating_media_noise`, bound as `tParticipatingMediaNoise` (`texture_3d<f32>`) with
+`sParticipatingMediaNoise` (linear, clamped — the wrap is the skirt's and `fract`'s, never the
+sampler's, which would wrap the whole atlas):
+
+    tap(slot, u):  cell = (slot mod sx, (slot / sx) mod sy, slot / (sx·sy)), sx/sy from textureDimensions
+                   texel = cell·130 + 1 + fract(u)·128;  sample at texel / atlas_size
+    multiplier(volume, p):
+                   base = p · noise_inverse_scale;  u = base + noise_offset
+                   if noise_warp > 0:  w = tap(slot, base·0.5 + noise_warp_offset)
+                                       u += (w − 0.5) · noise_warp · (0.6, 0.48, −0.64)
+                   return mix(1, tap(slot, u), noise_strength)
+
+`participating_media_volume_density_at` multiplies it in under `if (noise_strength > 0)`.
+
+### 5.5 Specs
+
+`GPUTileAtlas3D.spec.js` (slots, placement, skirt, growth with tiles preserved — read back off the
+software device — the limit, formats); `shader_volumetrics_noise_tile_bake.spec.js` (emulator: skirt
+= content wrapped, range, periodicity of the field across the content, padding words untouched,
+octaves and features, determinism, the octave ceiling, WGSL validity);
+`chunk_participating_media_noise.spec.js` (emulator, hand-built atlas: texel centres, wrap, the
+skirt blend and never the next slot, strength, scale, scroll, the warp's displacement in closed
+form, the density function bounded); `ParticipatingMediaVolume.spec.js` (the advance: units,
+wrap, continuity, a week of frames); `GPUSceneVolumetrics.spec.js` and
+`GPUViewVolumetrics.passes.spec.js` (unchanged, now encoding the atlas); the ECS `*.noise.spec.js`
+trio (component JSON/equality, adapter round trip and the 0→1 upgrade, the system's fold and
+per-frame invalidation).
+
+## 6. The forks, as answered
+
+Revision (a): **F1** flow noise — yes in principle, then ditched with the texture pivot (§4).
+**F2** octave band-limiting — "with textures insignificant", dropped. **F3** [0, 1] multiplier —
+"absolutely". **F4** CPU-side wrapped phase — fine, "a mod on the CPU". **F5** scalar scale — fine.
+**F6** delete the stubs — yes. **F7** per-volume velocity additive plus a multiplier on the wind —
+yes: `noise_velocity`, `noise_wind_factor`.
+
+Revision (b): **G1** no stacks — "one static texture, temporal variation via domain warping and
+scrolling"; built as scroll + warp. **G2** 128³ — yes. **G3** general atlas from day one — yes.
+**G4** migrating the SDF manager — a follow-up; Brixelizer left alone or promoted out of its FFX
+naming, not built on. **G5** world-space repeat only — yes. **G6** automatic growth — "house style";
+16 slots was fine, 2 was chosen as the first layer since a layer is 4.4 MB and growth is automatic.
+**G7** `r8unorm` — yes.
+
+## 7. Open, by measurement or by later ask
+
+- The repeat distance is `noise_scale`; at 32 m on a wide bank seen from above it may read as a
+  lattice. The fix, if it shows, is a user tile with more features or a larger scale — no code.
+- A per-volume `contrast`, a local clamped sampling mode (a texture that *is* the shape), exponential
+  height falloff, and history reprojected by the scroll: each a one-field or one-pass addition the
+  layout leaves room for, none asked for.
+- The froxel-versus-tracer parity check for a noisy volume was not run on the device this pass;
+  both paths read one function and the chunk spec pins the function.
+
+## 8. Not verified this pass
+
+RDR2's and Frostbite's fog-density slides (PPTX only). Nubis Cubed's noise authoring (cited
+through Enshrouded). The GPC 2024 Enshrouded talk (video only). The contrast dip of a phase
+crossfade, which the no-stacks decision made moot.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_integrate_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_integrate_optical_depth.js"],"names":[],"mappings":"AAKA,sDAsEC;0BAzEyB,iCAAiC"}
+{"version":3,"file":"chunk_integrate_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_integrate_optical_depth.js"],"names":[],"mappings":"AAOA,sDAsEC;0BA3EyB,iCAAiC"}

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

@@ -1,76 +1,82 @@
-import { chunk_frustum_clip_ray } from "../shader/chunk/geometry/frustum/chunk_frustum_clip_ray.js";
-import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
-
-export const chunk_integrate_optical_depth = CodeChunk.from(
-    //language=WGSL
-    `
-fn integrate_optical_depth(ray_ws: ${RAY_STRUCT.wgsl_ref}) -> vec3<f32>{
-
-    // volumetrics_metadata.frustum, NOT camera.frustum. The camera's frustum has no usable far
-    // plane: an infinite reverse-Z projection puts (0,0,0,near) in row 2 of the VP, a normal that
-    // cannot be normalized, so PerspectiveCamera.update_frustum zeroes the entry outright.
-    // frustum_clip_ray then discards it — correctly — which leaves the frustum OPEN at the far end,
-    // and a ray whose direction lies inside the view cone crosses no plane outward at all. t_exit
-    // stays at its 1e20 sentinel; capped by a directional light's tmax of 1.496e11 that gives a
-    // step of ~9.35e9, so the first sample lands far outside the grid, the loop below breaks on
-    // iteration one, and this returns zero — no media self-shadowing at all whenever the sun is in
-    // front of the camera, which is exactly when shafts are wanted.
-    //
-    // The metadata frustum is the same one rebuilt with a FINITE far plane
-    // (update_frustum_far_plane), which the participating-media pass already slices against.
-    var frustum_tmax = min(
-        ray_ws.tmax,
-        frustum_clip_ray(ray_ws.origin, ray_ws.direction, volumetrics_metadata.frustum)
-    );
-
-    if(frustum_tmax <= 0.0){
-        return vec3<f32>(0.0);
-    }
-    
-    // go as far as we can in frustum space
-    const STEP_COUNT = 16;
-    
-    let step_size = frustum_tmax / STEP_COUNT;
-    
-    var optical_depth = vec3<f32>(0.0);
-    
-    // offset ray forward a tiny mount to avoid aliasing
-    var t_previous = step_size * 0.1; 
-    var t_current = step_size;
-    
-    for(var i = 0; i < STEP_COUNT; i++){
-        
-        let position_ws = ray_ws.origin + ray_ws.direction * t_current;
-        
-        let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
-        
-        if(any(abs(uvw.xyz - 0.5) >= vec3(0.5))){
-            // out of bounds, stop integration
-            break;
-        }
-        
-        let t_delta = t_current - t_previous;
-        
-        let sample_extinction = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
-        
-        optical_depth += sample_extinction * t_delta;
-        
-        // update
-        t_previous = t_current;
-        t_current += step_size;
-    }
-    
-    // if ray goes outside of the frustum, integrate over fog volumes
-    // TODO implement
-    
-    return optical_depth;
-}
-    `,
-    [
-        RAY_STRUCT.declaration_chunk,
-        volumetrics_position_world_to_froxel_uvw,
-        chunk_frustum_clip_ray,
-    ]
-)
+import { chunk_frustum_clip_ray } from "../shader/chunk/geometry/frustum/chunk_frustum_clip_ray.js";
+import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
+import { SAMPLER_LINEAR_RESOURCE } from "../texture/SAMPLER_LINEAR_RESOURCE.js";
+import { PARTICIPATING_MEDIA_1_RESOURCE, VOLUMETRICS_METADATA_RESOURCE } from "./VOLUMETRICS_RESOURCES.js";
+
+export const chunk_integrate_optical_depth = CodeChunk.from(
+    //language=WGSL
+    `
+fn integrate_optical_depth(ray_ws: ${RAY_STRUCT.wgsl_ref}) -> vec3<f32>{
+
+    // volumetrics_metadata.frustum, NOT camera.frustum. The camera's frustum has no usable far
+    // plane: an infinite reverse-Z projection puts (0,0,0,near) in row 2 of the VP, a normal that
+    // cannot be normalized, so PerspectiveCamera.update_frustum zeroes the entry outright.
+    // frustum_clip_ray then discards it — correctly — which leaves the frustum OPEN at the far end,
+    // and a ray whose direction lies inside the view cone crosses no plane outward at all. t_exit
+    // stays at its 1e20 sentinel; capped by a directional light's tmax of 1.496e11 that gives a
+    // step of ~9.35e9, so the first sample lands far outside the grid, the loop below breaks on
+    // iteration one, and this returns zero — no media self-shadowing at all whenever the sun is in
+    // front of the camera, which is exactly when shafts are wanted.
+    //
+    // The metadata frustum is the same one rebuilt with a FINITE far plane
+    // (update_frustum_far_plane), which the participating-media pass already slices against.
+    var frustum_tmax = min(
+        ray_ws.tmax,
+        frustum_clip_ray(ray_ws.origin, ray_ws.direction, volumetrics_metadata.frustum)
+    );
+
+    if(frustum_tmax <= 0.0){
+        return vec3<f32>(0.0);
+    }
+    
+    // go as far as we can in frustum space
+    const STEP_COUNT = 16;
+    
+    let step_size = frustum_tmax / STEP_COUNT;
+    
+    var optical_depth = vec3<f32>(0.0);
+    
+    // offset ray forward a tiny mount to avoid aliasing
+    var t_previous = step_size * 0.1; 
+    var t_current = step_size;
+    
+    for(var i = 0; i < STEP_COUNT; i++){
+        
+        let position_ws = ray_ws.origin + ray_ws.direction * t_current;
+        
+        let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
+        
+        if(any(abs(uvw.xyz - 0.5) >= vec3(0.5))){
+            // out of bounds, stop integration
+            break;
+        }
+        
+        let t_delta = t_current - t_previous;
+        
+        let sample_extinction = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
+        
+        optical_depth += sample_extinction * t_delta;
+        
+        // update
+        t_previous = t_current;
+        t_current += step_size;
+    }
+    
+    // if ray goes outside of the frustum, integrate over fog volumes
+    // TODO implement
+    
+    return optical_depth;
+}
+    `,
+    [
+        RAY_STRUCT.declaration_chunk,
+        volumetrics_position_world_to_froxel_uvw,
+        chunk_frustum_clip_ray,
+    ]
+)
+
+chunk_integrate_optical_depth.requireResource(SAMPLER_LINEAR_RESOURCE);
+chunk_integrate_optical_depth.requireResource(PARTICIPATING_MEDIA_1_RESOURCE);
+chunk_integrate_optical_depth.requireResource(VOLUMETRICS_METADATA_RESOURCE);

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

@@ -3,10 +3,14 @@
  * through, where the froxel volumetrics discretize.
  *
  * - `participating_media_volume_density_at` is the volume's particle density at a world position:
- *   `density` times its edge fade, zero outside its box. The fade is the per-axis smoothstep over
- *   `fade_distance` (in world units, unaffected by scale) that `compute_volume_fade_factor` evaluates
- *   at a froxel's midpoint; here it is the field itself. Bounded above by `density`, so
- *   `density * extinction` majorizes the volume anywhere in it.
+ *   `density` times its edge fade times its noise, zero outside its box. The fade is the per-axis
+ *   smoothstep over `fade_distance` (in world units, unaffected by scale) that
+ *   `compute_volume_fade_factor` evaluates at a froxel's midpoint; here it is the field itself. The
+ *   noise is `chunk_participating_media_noise`'s [0, 1] multiplier from the volumetrics noise
+ *   atlas, carried by the scene's wind at the point, which an importing shader therefore binds as
+ *   `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, and the wind field as
+ *   `wind_field_add_resources` declares it. Bounded above by `density`, so `density * extinction`
+ *   majorizes the volume anywhere in it.
  * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
  *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
  *   length, and the distances are in its units: the local direction is not renormalized.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_participating_media_volume_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAFU,SAAS,CAgDjB;0BAnEwB,iCAAiC"}
+{"version":3,"file":"chunk_participating_media_volume_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,sDAFU,SAAS,CAwDjB;0BAhFwB,iCAAiC"}

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

@@ -1,6 +1,7 @@
 import { chunk_aabb3_slab_span } from "../shader/chunk/geometry/aabb3/chunk_aabb3_slab_span.js";
 import { chunk_mat4_extract_scale } from "../shader/chunk/geometry/mat4/chunk_mat4_extract_scale.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_participating_media_noise } from "./noise/chunk_participating_media_noise.js";
 import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
 
 /**
@@ -8,10 +9,14 @@ import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_
  * through, where the froxel volumetrics discretize.
  *
  * - `participating_media_volume_density_at` is the volume's particle density at a world position:
- *   `density` times its edge fade, zero outside its box. The fade is the per-axis smoothstep over
- *   `fade_distance` (in world units, unaffected by scale) that `compute_volume_fade_factor` evaluates
- *   at a froxel's midpoint; here it is the field itself. Bounded above by `density`, so
- *   `density * extinction` majorizes the volume anywhere in it.
+ *   `density` times its edge fade times its noise, zero outside its box. The fade is the per-axis
+ *   smoothstep over `fade_distance` (in world units, unaffected by scale) that
+ *   `compute_volume_fade_factor` evaluates at a froxel's midpoint; here it is the field itself. The
+ *   noise is `chunk_participating_media_noise`'s [0, 1] multiplier from the volumetrics noise
+ *   atlas, carried by the scene's wind at the point, which an importing shader therefore binds as
+ *   `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, and the wind field as
+ *   `wind_field_add_resources` declares it. Bounded above by `density`, so `density * extinction`
+ *   majorizes the volume anywhere in it.
  * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
  *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
  *   length, and the distances are in its units: the local direction is not renormalized.
@@ -32,14 +37,21 @@ fn participating_media_volume_density_at(volume: ${PARTICIPATING_MEDIA_VOLUME_ST
         return 0.0;
     }
 
-    if (volume.fade_distance <= 0.001) {
-        return volume.density;
+    var density = volume.density;
+
+    if (volume.fade_distance > 0.001) {
+        let to_edge_world = to_edge_local * mat4_extract_scale(volume.transform);
+        let fade = smoothstep(vec3<f32>(0.0), vec3<f32>(volume.fade_distance), to_edge_world);
+
+        density *= fade.x * fade.y * fade.z;
     }
 
-    let to_edge_world = to_edge_local * mat4_extract_scale(volume.transform);
-    let fade = smoothstep(vec3<f32>(0.0), vec3<f32>(volume.fade_distance), to_edge_world);
+    // a property of the volume, so every thread agrees: a uniform branch, not a variant
+    if (volume.noise_strength > 0.0) {
+        density *= participating_media_noise_multiplier(volume, position);
+    }
 
-    return volume.density * fade.x * fade.y * fade.z;
+    return density;
 }
 
 fn participating_media_volume_span(
@@ -66,5 +78,6 @@ fn participating_media_volume_span(
         PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
         chunk_aabb3_slab_span,
         chunk_mat4_extract_scale,
+        chunk_participating_media_noise,
     ]
 );

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

@@ -0,0 +1,19 @@
+/**
+ * Froxel-grid texture coordinates of a point given as its clip position and its planar view depth.
+ *
+ * The second half of {@link volumetrics_position_world_to_froxel_uvw}, for a caller that already
+ * has those two: a march along a straight line, where both are affine in the line parameter and
+ * cost two `fma` per sample, a vec4 and a scalar, instead of two matrix products (see
+ * {@link chunk_volumetrics_sample_froxel_extinction}).
+ *
+ * `content_offset` is {@link chunk_volumetrics_froxel_content_offset} of the grid's slice scale. It
+ * depends on nothing but the grid, so a march evaluates it once and passes it in. Evaluated per
+ * sample, it is an `exp` and three divides that the compiler leaves inside the loop.
+ *
+ * NOTE: we don't clamp final slice coordinate, this is intentional, we let the linear texture sampler take care of that.
+ * See {@link build_light_cluster_parameters}
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_uvw_from_clip: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_froxel_uvw_from_clip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_froxel_uvw_from_clip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_froxel_uvw_from_clip.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,qDAFU,SAAS,CAmCjB;0BApDwB,iCAAiC"}