@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1,13 +1,16 @@
 import { assert } from "../../../core/assert.js";
 import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.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";
 import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
 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 { 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";
@@ -31,6 +34,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,
@@ -39,6 +43,7 @@ function graph_integrate_participating_media({
                                                  view,
                                                  volumetrics_metadata,
                                                  resolution,
+                                                 shader_switches,
                                              }) {
 
     const data = {};
@@ -68,25 +73,47 @@ function graph_integrate_participating_media({
 
             const volumetrics_metadata = resources.get(data.volumetrics_metadata);
 
-            shader_volumetrics_build_participating_media.dispatchThreads({
+            /**
+             * The scene's noise atlas, imported this frame so a grow between frames is seen.
+             * @type {GPUTextureContext}
+             */
+            const noise_atlas = resources.get(data.noise_atlas);
+
+            // 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);
+
+            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),
+            };
+
+            // 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,
-                    tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                    tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                }
+                bindings,
             });
 
 
         });
 
     data.volumetrics_metadata = pass.read(volumetrics_metadata);
+    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({
         resolution,
@@ -217,6 +244,7 @@ function graph_build_sun_shadow_volume({
  * @param view
  * @param camera
  * @param resolution
+ * @param {ShaderSwitchSet} shader_switches the renderer's; the lighting pass is built for them
  * @returns {number} the lit scattering volume
  */
 function graph_integrate_light_scattering({
@@ -235,6 +263,7 @@ function graph_integrate_light_scattering({
                                               view,
                                               camera,
                                               resolution,
+                                              shader_switches,
                                           }) {
 
     const data = {};
@@ -296,7 +325,7 @@ function graph_integrate_light_scattering({
             bindings[volumetrics_sun_shadow_texture_name(cascade)] = sun_shadow_cascades[cascade].obtainView();
         }
 
-        shader_volumetrics_build_lighting.dispatchThreads({
+        shader_volumetrics_build_lighting.variant(shader_switches).dispatchThreads({
             encoder,
             thread_count_x: output.width,
             thread_count_y: output.height,
@@ -355,6 +384,7 @@ function graph_integrate_light_scattering({
  * @param {number} [options.taa_history] imported previous-frame accumulated scattering volume
  * @param {number} [options.taa_output] imported destination for this frame's accumulated scattering volume
  * @param {GPUCameraContext} [options.camera_previous] previous-frame camera, for temporal reprojection
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lighting pass is built for them
  */
 export function graph_build_volumetrics({
                                             graph,
@@ -372,6 +402,7 @@ export function graph_build_volumetrics({
                                             taa_history,
                                             taa_output,
                                             camera_previous,
+                                            shader_switches = ShaderSwitchSet.EMPTY,
                                         }) {
 
     assert.defined(view, 'view');
@@ -397,6 +428,7 @@ export function graph_build_volumetrics({
         resolution: volumetric_resolution,
         volumetrics_metadata,
         camera,
+        shader_switches,
     });
 
     const sun_shadow_cascades = graph_build_sun_shadow_volume({
@@ -423,6 +455,7 @@ export function graph_build_volumetrics({
         light_cluster_parameters,
         shadowmap_atlas,
         lights,
+        shader_switches,
     })
 
     // Temporal reprojection of the per-froxel lit scattering volume, applied BEFORE aerial

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

@@ -0,0 +1,133 @@
+/**
+ * The volumetrics noise atlas, as the shaders and the host both know it.
+ *
+ * A participating-media volume's noise is a tile of this atlas sampled in world space, wrapping
+ * every `noise_scale` metres, scrolled by the wind and warped by a second, slower tap of the same
+ * tile. The tile sizes are compile-time facts of the shader (`chunk_participating_media_noise`
+ * derives a slot's texel origin from them and the atlas texture's own dimensions), so they are
+ * constants here and the atlas instance is built from the same numbers.
+ *
+ * Why 128³ with a one-texel skirt: the engine's default tile holds four base features along each
+ * edge with the finest of three octaves at eight texels a wavelength; Enshrouded's detail noise is
+ * 128³, Godot advises 64³ or under, and one texel of skirt is what a trilinear tap needs to wrap.
+ * A tile is 2.2 MB in `r8unorm` — uncompressed because WebGPU admits no compressed 3-D texture.
+ *
+ * See `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+ */
+/**
+ * Texels of content along each axis of a tile.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE: number;
+/**
+ * Texels of skirt on each side: what a linear filter reads past the content.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_BORDER: number;
+/**
+ * Texels along each axis of a whole tile, skirt included.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_SIZE: number;
+/**
+ * One byte a texel: the tile is a [0, 1] multiplier on density and nothing else.
+ * @type {GPUTextureFormat}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_FORMAT: GPUTextureFormat;
+/**
+ * The atlas's x/y footprint in tiles — fixed for its life, since it grows along z.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X: number;
+/**
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y: number;
+/**
+ * Slots allocated up front: the engine's own tile and one spare. The atlas grows by a layer of
+ * `SLOTS_X × SLOTS_Y` whenever that runs out.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY: number;
+/**
+ * The slot the engine bakes its own tile into at start-up, and the slot a volume samples unless
+ * told otherwise.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT: number;
+/**
+ * Base features along each edge of the engine's default tile: four 32-texel wavelengths, so the
+ * tile repeats every four features in the world.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES: number;
+/**
+ * Octaves baked into the engine's default tile, lacunarity 2, gain 0.5 — the finest at 8 texels a
+ * wavelength. AC4 shipped one octave and found more "rather subtle for added cost"; here the cost
+ * is paid once at bake time, so three is the budget, and a fourth would alias at 4 texels.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES: number;
+/**
+ * The warp tap samples the same tile at this fraction of the base frequency: a coarser field, so the
+ * displacement it drives is a smooth undulation of the base rather than a shimmer.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCALE: number;
+/**
+ * How fast the warp tap scrolls, as a fraction of the base tap's scroll in its own tile units. Not
+ * 1: the two fields have to slide against each other for the base to keep changing shape rather
+ * than ride along unchanged.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL: number;
+/**
+ * The fixed direction the warp displaces along, a unit vector off every axis so the shear is
+ * oblique rather than a slide along x. A scalar tap can only displace along one direction; which
+ * one matters little for an isotropic field, and a constant keeps the tap count at two.
+ * @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.
+ * @type {SamplerDescriptor}
+ */
+export const PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR: SamplerDescriptor;
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+//# sourceMappingURL=PARTICIPATING_MEDIA_NOISE.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,152 @@
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+
+/**
+ * The volumetrics noise atlas, as the shaders and the host both know it.
+ *
+ * A participating-media volume's noise is a tile of this atlas sampled in world space, wrapping
+ * every `noise_scale` metres, scrolled by the wind and warped by a second, slower tap of the same
+ * tile. The tile sizes are compile-time facts of the shader (`chunk_participating_media_noise`
+ * derives a slot's texel origin from them and the atlas texture's own dimensions), so they are
+ * constants here and the atlas instance is built from the same numbers.
+ *
+ * Why 128³ with a one-texel skirt: the engine's default tile holds four base features along each
+ * edge with the finest of three octaves at eight texels a wavelength; Enshrouded's detail noise is
+ * 128³, Godot advises 64³ or under, and one texel of skirt is what a trilinear tap needs to wrap.
+ * A tile is 2.2 MB in `r8unorm` — uncompressed because WebGPU admits no compressed 3-D texture.
+ *
+ * See `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+ */
+
+/**
+ * Texels of content along each axis of a tile.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE = 128;
+
+/**
+ * Texels of skirt on each side: what a linear filter reads past the content.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_BORDER = 1;
+
+/**
+ * Texels along each axis of a whole tile, skirt included.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_SIZE = PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE + 2 * PARTICIPATING_MEDIA_NOISE_TILE_BORDER;
+
+/**
+ * One byte a texel: the tile is a [0, 1] multiplier on density and nothing else.
+ * @type {GPUTextureFormat}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_FORMAT = "r8unorm";
+
+/**
+ * The atlas's x/y footprint in tiles — fixed for its life, since it grows along z.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X = 2;
+
+/**
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y = 1;
+
+/**
+ * Slots allocated up front: the engine's own tile and one spare. The atlas grows by a layer of
+ * `SLOTS_X × SLOTS_Y` whenever that runs out.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY = 2;
+
+/**
+ * The slot the engine bakes its own tile into at start-up, and the slot a volume samples unless
+ * told otherwise.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT = 0;
+
+/**
+ * Base features along each edge of the engine's default tile: four 32-texel wavelengths, so the
+ * tile repeats every four features in the world.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES = 4;
+
+/**
+ * Octaves baked into the engine's default tile, lacunarity 2, gain 0.5 — the finest at 8 texels a
+ * wavelength. AC4 shipped one octave and found more "rather subtle for added cost"; here the cost
+ * is paid once at bake time, so three is the budget, and a fourth would alias at 4 texels.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES = 3;
+
+/**
+ * The warp tap samples the same tile at this fraction of the base frequency: a coarser field, so the
+ * displacement it drives is a smooth undulation of the base rather than a shimmer.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCALE = 0.5;
+
+/**
+ * How fast the warp tap scrolls, as a fraction of the base tap's scroll in its own tile units. Not
+ * 1: the two fields have to slide against each other for the base to keep changing shape rather
+ * than ride along unchanged.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL = 0.37;
+
+/**
+ * The fixed direction the warp displaces along, a unit vector off every axis so the shear is
+ * oblique rather than a slide along x. A scalar tap can only displace along one direction; which
+ * one matters little for an isotropic field, and a constant keeps the tap count at two.
+ * @type {readonly number[]}
+ */
+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.
+ * @type {SamplerDescriptor}
+ */
+export const PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR = SamplerDescriptor.from({
+    magFilter: "linear",
+    minFilter: "linear",
+});

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

@@ -0,0 +1,9 @@
+/**
+ * What one bake of a noise tile is told: the tile's geometry, the row stride of the block it writes,
+ * and the field to bake.
+ *
+ * @see shader_volumetrics_noise_tile_bake
+ */
+export const VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,uEAcuC;6BAtBV,mCAAmC"}

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

@@ -0,0 +1,24 @@
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * What one bake of a noise tile is told: the tile's geometry, the row stride of the block it writes,
+ * and the field to bake.
+ *
+ * @see shader_volumetrics_noise_tile_bake
+ */
+export const VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT = WebGPUStruct.from({
+    // texels along each axis of the whole tile, skirt included
+    tile_size: u32,
+    // texels of content along each axis
+    content_size: u32,
+    // texels of skirt on each side; the skirt is the content wrapped
+    border: u32,
+    // u32 words per row of the output block: the row stride, padded to the copy alignment
+    words_per_row: u32,
+    // base features along each edge of the content — the base octave's period in lattice units, an
+    // integer so the octave tiles exactly
+    features: f32,
+    // octaves summed, lacunarity 2, gain 0.5; at most VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT
+    octaves: u32,
+}, "VolumetricsNoiseTileBakeSettings");

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

@@ -0,0 +1,28 @@
+/**
+ * Offer the pipeline {@link bake_volumetrics_noise_tile} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bake_volumetrics_noise_tile_pipelines(enquiry: PipelineEnquiry): void;
+/**
+ * Bake a noise tile on the device into a slot of an atlas: a compute dispatch into a transient
+ * block, then a copy of the block into the slot, both in the given command stream. Nothing is
+ * read back and nothing persists but the tile.
+ *
+ * @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 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}
+ */
+export function bake_volumetrics_noise_tile({ command, atlas, slot, features, octaves }: {
+    command: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+    atlas: import("../../texture/atlas/GPUTileAtlas3D.js").GPUTileAtlas3D;
+    slot: number;
+    features: number;
+    octaves: number;
+}): void;
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+//# sourceMappingURL=bake_volumetrics_noise_tile.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;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"}

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

@@ -0,0 +1,96 @@
+import { assert } from "../../../../core/assert.js";
+import { COPY_BYTES_PER_ROW_ALIGNMENT } from "../../../device/COPY_BYTES_PER_ROW_ALIGNMENT.js";
+import {
+    shader_volumetrics_noise_tile_bake,
+    VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT
+} from "./shader_volumetrics_noise_tile_bake.js";
+import { VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT } from "./VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.js";
+
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+
+/**
+ * psrdnoise's hash modulus, the longest period an octave can have before it repeats inside itself.
+ * @type {number}
+ */
+const PSRDNOISE_PERIOD_CEILING = 289;
+
+/**
+ * Offer the pipeline {@link bake_volumetrics_noise_tile} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bake_volumetrics_noise_tile_pipelines(enquiry) {
+    enquiry.compute.push(shader_volumetrics_noise_tile_bake.pipeline);
+}
+
+/**
+ * Bake a noise tile on the device into a slot of an atlas: a compute dispatch into a transient
+ * block, then a copy of the block into the slot, both in the given command stream. Nothing is
+ * read back and nothing persists but the tile.
+ *
+ * @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 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}
+ */
+export function bake_volumetrics_noise_tile({ command, atlas, slot, features, octaves }) {
+    assert.defined(command, 'command');
+    assert.defined(atlas, 'atlas');
+    assert.equal(atlas.bytes_per_texel, 1, 'the bake packs one byte a texel');
+    assert.ok(atlas.is_live(slot), `slot ${slot} is not allocated`);
+    assert.isNonNegativeInteger(features, 'features');
+    assert.greaterThan(features, 0, 'features');
+    assert.isNonNegativeInteger(octaves, 'octaves');
+    assert.greaterThan(octaves, 0, 'octaves');
+    assert.lessThanOrEqual(octaves, VOLUMETRICS_NOISE_TILE_BAKE_OCTAVE_LIMIT, 'octaves');
+    assert.lessThanOrEqual(features * 2 ** (octaves - 1), PSRDNOISE_PERIOD_CEILING, `the finest octave's period ${features * 2 ** (octaves - 1)} is past psrdnoise's ceiling of ${PSRDNOISE_PERIOD_CEILING}, where the field repeats inside the tile`);
+
+    const content_size = atlas.content_size;
+
+    assert.ok(content_size[0] === content_size[1] && content_size[1] === content_size[2], `the bake makes a cubic tile, the same periods along every edge; the atlas holds ${content_size[0]}×${content_size[1]}×${content_size[2]}`);
+
+    const tile_size = atlas.tile_size[0];
+
+    const bytes_per_row = Math.ceil(tile_size / COPY_BYTES_PER_ROW_ALIGNMENT) * COPY_BYTES_PER_ROW_ALIGNMENT;
+    const words_per_row = bytes_per_row / 4;
+
+    const buffer = command.allocateTransientBuffer(
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        bytes_per_row * tile_size * tile_size,
+    );
+
+    const settings = command.allocateTransientBuffer(
+        GPUBufferUsage.UNIFORM,
+        VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.aligned_size,
+    );
+
+    command.writeValueBuffer(settings, 0, VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT, {
+        tile_size,
+        content_size: content_size[0],
+        border: atlas.border,
+        words_per_row,
+        features,
+        octaves,
+    });
+
+    // one thread a word, a word four texels along x
+    const words_across = Math.ceil(tile_size / 4);
+
+    shader_volumetrics_noise_tile_bake.dispatch({
+        encoder: command,
+        bindings: {
+            settings,
+            output: buffer,
+        },
+        group_count_x: Math.ceil(words_across / 8),
+        group_count_y: Math.ceil(tile_size / 8),
+        group_count_z: tile_size,
+    });
+
+    atlas.copy_from_buffer(command.gpu_encoder, slot, buffer, 0, bytes_per_row);
+}