@woosh/meep-engine 3.41.0 → 3.43.0

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

@@ -0,0 +1,228 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_light_cluster_counts } from "../light/cluster/chunk_light_cluster_counts.js";
+import { chunk_light_cluster_metadata_by_position } from "../light/cluster/chunk_light_cluster_metadata_by_position.js";
+import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../light/cluster/shader_cluster_assign_lights.js";
+import { chunk_cluster_depth_from_z_slice } from "../light/cluster/chunk_cluster_depth_from_z_slice.js";
+import { chunk_camera_ray_from_uv } from "../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { chunk_stbn_sample_vec3 } from "../shader/chunk/noise/chunk_stbn_sample_vec3.js";
+import {
+    chunk_directional_lights_iteration_mask
+} from "../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import {
+    chunk_get_directional_light_info_by_index
+} from "../shader/chunk/light/io/chunk_get_directional_light_info_by_index.js";
+import {
+    chunk_get_point_light_info_by_index
+} from "../shader/chunk/light/io/chunk_get_point_light_info_by_index.js";
+import { chunk_get_spot_light_info_by_index } from "../shader/chunk/light/io/chunk_get_spot_light_info_by_index.js";
+import {
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { chunk_texel_coordinate_to_uv } from "../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { chunk_uv_to_texel_coordinate } from "../shader/chunk/texture/chunk_uv_to_texel_coordinate.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { chunk_shadowmap_get_light_visibility } from "../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
+import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
+import { chunk_volumetrics_irradiance_sh } from "./chunk_volumetrics_irradiance_sh.js";
+import { chunk_volumetrics_local_light_shadow } from "./chunk_volumetrics_local_light_shadow.js";
+import { chunk_camera_ray_planar_depth_scale } from "./chunk_camera_ray_planar_depth_scale.js";
+import { chunk_volumetrics_column_jitter } from "./chunk_volumetrics_column_jitter.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+
+/**
+ * Workgroup shape of this pass, `[x, y, z]` in froxels, stated to the `@workgroup_size` below and
+ * read back out of it by the dispatch. Flat in z and 64 invocations, for the reasons the fog's
+ * lighting pass gives (`VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION`): it walks the same light
+ * clusters, and those are farthest apart along depth.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_IRRADIANCE_WORKGROUP_RESOLUTION = [8, 8, 1];
+
+const resources = new ShaderResourceSetDescriptor();
+
+// The froxel irradiance volume (chunk_volumetrics_irradiance_sh): luma SH2 in one, chroma in the .rg
+// of the other. rgba16float for both, because rg16float is not a storage format without
+// texture-formats-tier1. It starts from what the froxel GI stage (gi/) wrote to tGIY / tGICoCg.
+resources.createGroup()
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
+    .addTexture("tGIY", "float", "3d")
+    .addTexture("tGICoCg", "float", "3d")
+    .addStorageTexture("tIrradianceY", "rgba16float", "3d", "write-only")
+    .addStorageTexture("tIrradianceCoCg", "rgba16float", "3d", "write-only");
+
+// Lighting information
+resources.createGroup()
+    .addStorageBuffer("light_data", WebGPUArray.u32)
+    // clusters
+    .addUniform("cluster_parameters", vec3f)
+    .addStorageBuffer("cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT)
+    .addStorageBuffer("cluster_data", WebGPUArray.u32)
+    // shadows
+    .addTexture("shadowmapAtlas", "depth")
+    .addSampler("sCompareLinear", "comparison", SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VOLUMETRICS_IRRADIANCE_WORKGROUP_RESOLUTION.join(",")})
+fn main(
+    @builtin(global_invocation_id) voxel : vec3<u32>
+){
+    let resolution = textureDimensions(tIrradianceY);
+
+    if (any(voxel >= resolution)) {
+        return;
+    }
+
+    // The fog lighting pass's sample, taken the same way (shader_volumetrics_build_lighting, where
+    // the irradiance was written until it had a pass of its own): one point per froxel per frame,
+    // jittered across the slab in depth by the column jitter and the blue noise, and in xy by the
+    // blue noise. Never a fixed point. A particle spans many froxels and reads them trilinearly, and
+    // a lattice of samples that never moves shows on it as seams wherever neighbouring texels
+    // disagree — beside a light, along a shadow edge. Moved every frame, the lattice is resolved by
+    // the main TAA, which the particles are drawn ahead of.
+    let near_far = camera.clip_near_far;
+    let curve = volumetrics_metadata.froxel_cluster_parameters;
+
+    let z_jitter = volumetrics_column_jitter(voxel.xy, view.frame_index);
+
+    let z0 = max(near_far.x, cluster_depth_from_z_slice(f32(voxel.z) + z_jitter, curve, f32(resolution.z)));
+    let z1 = min(near_far.y, cluster_depth_from_z_slice(f32(voxel.z + 1u) + z_jitter, curve, f32(resolution.z)));
+
+    // the lighting pass's offset and temporal axis, so the two passes ask about the same point
+    const STBN_DECORRELATION_OFFSET = vec2<u32>(37u, 71u);
+
+    let noise = stbn_sample_vec3(vec3(voxel.xy + STBN_DECORRELATION_OFFSET, view.frame_index + voxel.z));
+
+    // interpolate the cubes, then take the cube root: uniform in world-space volume across the slab
+    let view_depth = pow(mix(z0 * z0 * z0, z1 * z1 * z1, noise.z), 0.333333);
+
+    let tile_uv = saturate(texel_coordinate_to_uv(vec2<f32>(voxel.xy) + (noise.xy - 0.5), resolution.xy));
+    let view_ray = camera_ray_from_uv(tile_uv, camera);
+
+    // view_depth is planar, so step the ray by the planar-to-distance scale
+    let position_ws = view_ray.origin
+        + view_ray.direction * (view_depth * camera_ray_planar_depth_scale(view_ray.direction, camera));
+
+    let view_pixel_coord = uv_to_texel_coordinate(tile_uv, vec2(view.width, view.height));
+
+    var irradiance: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+
+    // Each light as the surfaces around the froxel receive it: its colour and its shadow, and no
+    // medium on the way in. The deferred and forward paths light meshes by exactly this, and a lit
+    // particle beside a lit log has to agree with it — the fog is composited over both afterwards.
+
+    var directional_bits = directional_lights_iteration_mask(&light_data);
+    while (directional_bits != 0u) {
+        let directional_index = countTrailingZeros(directional_bits);
+        directional_bits &= ~(1u << directional_index);
+
+        let sun = get_directional_light_info_by_index(&light_data, directional_index);
+
+        let shadow_term = shadowmap_get_directional_light_visibility(
+            &light_data,
+            directional_index,
+            position_ws,
+            // toward-camera, the deferred cascade-blend convention; view_ray runs camera->scene
+            -view_ray.direction,
+            sun.direction
+        );
+
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * sun.color, sun.direction);
+    }
+
+    let cluster_metadata = light_cluster_metadata_by_position(
+        view_pixel_coord,
+        view_depth,
+        vec2(view.width, view.height)
+    );
+
+    let cluster_offset = cluster_metadata.offset;
+    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++) {
+        let light_index = cluster_data[cluster_offset + j];
+        let direct_light = get_point_light_info_by_index(&light_data, light_index, position_ws);
+
+        if (all(direct_light.color == vec3(0.0))) {
+            continue;
+        }
+
+        let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
+
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
+    }
+
+    for (var k = 0u; k < spot_count; 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);
+
+        if (all(direct_light.color == vec3(0.0))) {
+            continue;
+        }
+
+        let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
+
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
+    }
+
+    // What the renderer's indirect lighting gives this froxel, in the same encoding; the lights add
+    // to it. Written by the froxel GI module the mode selects, which is all this pass knows of GI.
+    irradiance.Y += textureLoad(tGIY, voxel, 0);
+    irradiance.CoCg += textureLoad(tGICoCg, voxel, 0).xy;
+
+    // nothing filters this volume, so nothing downstream would stop an Inf or a NaN here
+    let stored = volumetrics_irradiance_sh_storable(irradiance);
+
+    textureStore(tIrradianceY, voxel, stored.Y);
+    textureStore(tIrradianceCoCg, voxel, vec4<f32>(stored.CoCg, 0.0, 0.0));
+}
+    `, [
+        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+        RAY_STRUCT.declaration_chunk,
+        chunk_volumetrics_column_jitter,
+        chunk_cluster_depth_from_z_slice,
+        chunk_stbn_sample_vec3,
+        chunk_texel_coordinate_to_uv,
+        chunk_uv_to_texel_coordinate,
+        chunk_camera_ray_from_uv,
+        chunk_camera_ray_planar_depth_scale,
+
+        chunk_light_cluster_metadata_by_position,
+        chunk_light_cluster_counts,
+        chunk_directional_lights_iteration_mask,
+        chunk_get_directional_light_info_by_index,
+        chunk_get_point_light_info_by_index,
+        chunk_get_spot_light_info_by_index,
+        chunk_shadowmap_get_light_visibility,
+        chunk_volumetrics_local_light_shadow,
+        chunk_volumetrics_irradiance_sh,
+    ]
+);
+
+/**
+ * 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
+ * spot light with its shadow, at a point jittered through the froxel every frame.
+ *
+ * Its own pass, not a by-product of the fog's lighting pass: particle lighting needs no medium, so it
+ * runs whether or not the scene has any fog, and the frame graph culls it when nothing reads it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_build_irradiance = ComputeShader.from({
+    label: "Volumetrics / build irradiance",
+    resources,
+    body,
+});

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":"AAiDA;;;;;;;;;;;;;;;GAeG;AACH,wDAFU,MAAM,EAAE,CAEiD;AAkanE,8DAIE;8BAnd4B,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;AAiXnE,8DAIE;8BA9Z4B,4BAA4B"}

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

@@ -41,10 +41,6 @@ import {
 import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
 import { chunk_volumetrics_column_jitter } from "./chunk_volumetrics_column_jitter.js";
 import { chunk_volumetrics_local_light_shadow } from "./chunk_volumetrics_local_light_shadow.js";
-import { chunk_volumetrics_irradiance_sh } from "./chunk_volumetrics_irradiance_sh.js";
-import {
-    METRO_L1_IRRADIANCE_STRUCT
-} from "../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
 import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
 
 /**
@@ -87,14 +83,6 @@ for (let cascade = 0; cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT; cascade++)
 
 primary_group.addStorageTexture("tLighting", "rgba16float", "3d", "write-only")
 
-// The froxel irradiance volume (chunk_volumetrics_irradiance_sh): luma SH2 in one, chroma in the
-// .rg of the other. rgba16float for both, because rg16float is not a storage format without
-// texture-formats-tier1. It is what the froxel GI stage (gi/) wrote to tGIY / tGICoCg, plus the lights.
-primary_group.addTexture("tGIY", "float", "3d")
-primary_group.addTexture("tGICoCg", "float", "3d")
-primary_group.addStorageTexture("tIrradianceY", "rgba16float", "3d", "write-only")
-primary_group.addStorageTexture("tIrradianceCoCg", "rgba16float", "3d", "write-only")
-
 // Lighting information
 resources.createGroup()
 
@@ -144,11 +132,6 @@ fn main(
     var inScatteringSum = vec3<f32>(0.0);
     var extinctionSum = 0.0;
 
-    // What a transparent surface at the sample receives from the same lights: their shadowed
-    // colour, attenuated by the medium toward each light, before any scattering by it.
-    var irradianceSum: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
-
-
     // One sample per froxel. The 0.95-blend TAA downstream is a ~39-effective-sample temporal
     // integrator; supersampling here as well spends N times this pass removing variance that filter
     // removes anyway — and spends it at the Monte Carlo rate, because the samples were independent
@@ -313,15 +296,6 @@ fn main(
             );
 
             inScatteringSum += shadow_term * ms * transmittance_atmospheric * sun.color;
-
-            // No atmospheric transmittance: that is the air's, and a surface in the volume is lit
-            // the way the surfaces around it are — the deferred and forward paths light meshes by
-            // sun.color as it stands, and a lit particle beside a lit log has to agree with it.
-            irradianceSum = volumetrics_irradiance_sh_add(
-                irradianceSum,
-                shadow_term * exp(-optical_depth) * sun.color,
-                sun.direction
-            );
         }
 
         // Local lights
@@ -374,12 +348,6 @@ fn main(
             let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
 
             inScatteringSum += shadow_term * ms * direct_light.color;
-
-            irradianceSum = volumetrics_irradiance_sh_add(
-                irradianceSum,
-                shadow_term * exp(-optical_depth) * direct_light.color,
-                direct_light.direction
-            );
         }
 
         for (var k = 0u; k < spot_count; k++) {
@@ -415,12 +383,6 @@ fn main(
             let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
 
             inScatteringSum += shadow_term * ms * direct_light.color;
-
-            irradianceSum = volumetrics_irradiance_sh_add(
-                irradianceSum,
-                shadow_term * exp(-optical_depth) * direct_light.color,
-                direct_light.direction
-            );
         }
     }
 
@@ -435,20 +397,6 @@ fn main(
     let extinction = extinctionSum / f32(SAMPLE_COUNT);
 
     textureStore(tLighting, voxel_coord, vec4<f32>(inScattering, extinction));
-
-    irradianceSum.Y /= f32(SAMPLE_COUNT);
-    irradianceSum.CoCg /= f32(SAMPLE_COUNT);
-
-    // What the renderer's indirect lighting gives this froxel, in the same encoding; the lights add
-    // to it. Written by the froxel GI module the mode selects, which is all this pass knows of GI.
-    irradianceSum.Y += textureLoad(tGIY, voxel_coord, 0);
-    irradianceSum.CoCg += textureLoad(tGICoCg, voxel_coord, 0).xy;
-
-    // nothing TAA-filters this volume, so nothing downstream would stop an Inf or a NaN here
-    let irradiance = volumetrics_irradiance_sh_storable(irradianceSum);
-
-    textureStore(tIrradianceY, voxel_coord, irradiance.Y);
-    textureStore(tIrradianceCoCg, voxel_coord, vec4<f32>(irradiance.CoCg, 0.0, 0.0));
 }
     `, [
         chunk_cluster_depth_from_z_slice,
@@ -469,7 +417,6 @@ fn main(
         chunk_get_spot_light_info_by_index,
         chunk_shadowmap_get_light_visibility,
         chunk_volumetrics_local_light_shadow,
-        chunk_volumetrics_irradiance_sh,
         chunk_sky_lut_compute_uv,
 
         RAY_STRUCT.declaration_chunk,

package/src/shade/renderer/water/GPUWaterRenderer.d.ts

@@ -23,6 +23,21 @@ export class GPUWaterRenderer {
      * @type {import("./medium/GPUWaterBodies.js").GPUWaterBodies|null}
      */
     bodies: import("./medium/GPUWaterBodies.js").GPUWaterBodies | null;
+    /**
+     * What the lattice's per-frame lists may hold (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3). Grown from
+     * each view's totals, read back a frame or two later; a frame over a budget drops its tail until then.
+     */
+    lod_budgets: {
+        candidates: number;
+        interior: number;
+        boundary: number;
+        patches: number;
+    };
+    /**
+     * The lists' totals as the last read back frame needed them: candidates, interior cells, boundary cells, triangles
+     * drawn as themselves, patches.
+     */
+    lod_totals: Uint32Array;
     avboit_is_empty(view: any): boolean;
     /** Optional single-pixel readback on the next rendered water frame. No per-frame readback. */
     request_probe(uv: any): Promise<any>;

package/src/shade/renderer/water/GPUWaterRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAmBA,sFAAsF;AACtF;IACI,WAAa;IACb,mBAAe;IACf,yBAAqB;IACrB,aAAS;IACT,WAAa;IACb;;;;;;;;;;;MAE6B;IAC7B;;;;OAIG;IACH,QAFU,OAAO,4BAA4B,EAAE,cAAc,GAAC,IAAI,CAEpD;IAQd,oCAIC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBAKC;IAED;;;;;;;;;;;;;;;;MAyIC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA4BJ"}
+{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAqBA,sFAAsF;AACtF;IACI,WAAa;IACb,mBAAe;IACf,yBAAqB;IACrB,aAAS;IACT,WAAa;IACb;;;;;;;;;;;MAE6B;IAC7B;;;;OAIG;IACH,QAFU,OAAO,4BAA4B,EAAE,cAAc,GAAC,IAAI,CAEpD;IAOd;;;OAGG;IACH;;;;;MAA8F;IAC9F;;;OAGG;IACH,wBAAyD;IAMzD,oCAIC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBASC;IAuDD;;;;;;;;;;;;;;;;MAgJC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA4BJ"}

package/src/shade/renderer/water/GPUWaterRenderer.js

@@ -3,16 +3,18 @@ import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../depth/DEFAULT_DEPTH_TEXTURE_VIEW.
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
 import { graph_image_pass } from "../shader/graph/graph_image_pass.js";
 import { ShadeIndirectLightingMode } from "../ShadeIndirectLightingMode.js";
-import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
-import { build_indirect_draw_command } from "../gpu_primitive/indirect/build_indirect_draw_command.js";
 import { graph_water_tessellation } from "./surface/graph_water_tessellation.js";
-import { WATER_TESSELLATION_STRUCT, WATER_TILE_VERTEX_COUNT } from "./surface/chunk_water_tessellation.js";
+import { water_lod_view, WATER_LOD_VIEW_STRUCT } from "./surface/lod/WATER_LOD.js";
+import { WATER_LOD_LIMITS_STRUCT, WATER_LOD_PATCH_INDICES, WATER_LOD_STATISTICS_WORDS,
+    WaterLodCommand } from "./surface/lod/shader_water_lod.js";
+import { GEOMETRY_MESHLET_TRIANGLE_LIMIT } from "../geometry/meshlet/GEOMETRY_MESHLET_TRIANGLE_LIMIT.js";
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
 import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
 import { create_water_finalize_pipeline_brick4, create_water_finalize_pipeline_ibl, create_water_pipeline,
     WATER_FINALIZE_RESOURCES_BRICK4, WATER_FINALIZE_RESOURCES_IBL, WATER_RESOURCES,
-    WATER_TRACE_STRUCT, WATER_GRID_STRUCT } from "./shader_water.js";
+    WATER_TRACE_STRUCT } from "./shader_water.js";
+import { WATER_BAND_SAMPLER } from "./surface/GPUWaterSurface.js";
 import { shader_water_background_copy, shader_water_debug, shader_water_draw,
     shader_water_occupancy, shader_water_splat, shader_water_confidence_seed,
     shader_water_confidence_x, shader_water_confidence_y } from "./shader_water_avboit.js";
@@ -39,6 +41,20 @@ export class GPUWaterRenderer {
     #prepared = new WeakMap();
     #inspection = new WeakMap();
     #probe = null;
+    /**
+     * What the lattice's per-frame lists may hold (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3). Grown from
+     * each view's totals, read back a frame or two later; a frame over a budget drops its tail until then.
+     */
+    lod_budgets = { candidates: 1 << 16, interior: 1 << 18, boundary: 1 << 16, patches: 1 << 12 };
+    /**
+     * The lists' totals as the last read back frame needed them: candidates, interior cells, boundary cells, triangles
+     * drawn as themselves, patches.
+     */
+    lod_totals = new Uint32Array(WATER_LOD_STATISTICS_WORDS);
+    /** Readback buffers for the lists' totals, idle ones first. */
+    #readbacks = [];
+    /** The patches' index buffer, one per device. */
+    #patch_indices = null;
 
     avboit_is_empty(view) {
         // the authored state: whether there is water at all, not whether its surface was produced yet
@@ -70,29 +86,100 @@ export class GPUWaterRenderer {
         this.#probe = null;
         this.#prepared = new WeakMap();
         this.#inspection = new WeakMap();
+        for (const readback of this.#readbacks) { readback.buffer.destroy(); }
+        this.#readbacks = [];
+        this.#patch_indices?.buffer.destroy();
+        this.#patch_indices = null;
+    }
+
+    /** The patches' indices on this device, made the first time a frame draws there. */
+    #patch_index_buffer(device) {
+        if (this.#patch_indices?.device !== device) {
+            this.#patch_indices?.buffer.destroy();
+            const buffer = device.createBuffer({ label: 'Water / lod patch indices', size: WATER_LOD_PATCH_INDICES.byteLength,
+                usage: GPUBufferUsage.INDEX, mappedAtCreation: true });
+            new Uint16Array(buffer.getMappedRange()).set(WATER_LOD_PATCH_INDICES);
+            buffer.unmap();
+            this.#patch_indices = { device, buffer };
+        }
+        return this.#patch_indices.buffer;
+    }
+
+    /** Keep a frame's totals and grow the budgets they outran, to the next power of two over a quarter more. */
+    #grow(totals) {
+        this.lod_totals.set(totals);
+        const budgets = this.lod_budgets;
+        // statistics words: candidates, interior, boundary, flat triangles (sized by the scene, not grown), patches
+        const keys = { candidates: 0, interior: 1, boundary: 2, patches: 4 };
+        for (const [key, i] of Object.entries(keys)) {
+            if (totals[i] > budgets[key]) { budgets[key] = 2 ** Math.ceil(Math.log2(totals[i] * 1.25)); }
+        }
+    }
+
+    /** After the lists are built, their totals to the CPU: at most three in flight, none if all are busy. */
+    #record_readback(graph, statistics) {
+        const data = {};
+        const pass = graph.add('Water / lod budgets', data, (d, resources, { encoder, graphics }) => {
+            // buffers of a device that has since been replaced go with it
+            this.#readbacks = this.#readbacks.filter(r => r.device === graphics.device || (r.buffer.destroy(), false));
+            let readback = this.#readbacks.find(r => !r.busy);
+            if (readback === undefined) {
+                if (this.#readbacks.length >= 3) { return; }
+                readback = { busy: false, device: graphics.device, buffer: graphics.device.createBuffer({ label: 'Water / lod budgets readback',
+                    size: WATER_LOD_STATISTICS_WORDS * 4, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST }) };
+                this.#readbacks.push(readback);
+            }
+            readback.busy = true;
+            encoder.copyBufferToBuffer(resources.get(d.statistics), 0, readback.buffer, 0, WATER_LOD_STATISTICS_WORDS * 4);
+            encoder.done.then(async () => {
+                try {
+                    await readback.buffer.mapAsync(GPUMapMode.READ);
+                    this.#grow(new Uint32Array(readback.buffer.getMappedRange()));
+                    readback.buffer.unmap();
+                } catch (error) {
+                    // a device lost or a buffer destroyed with the system: nothing to grow for
+                } finally { readback.busy = false; }
+            });
+        });
+        data.statistics = pass.read(statistics);
+        pass.make_side_effect();
     }
 
     avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture,
         hzb_texture, environment_texture, light_cluster_parameters, light_cluster_lookup, light_cluster_data,
         shadowmap_atlas, indirect_lighting_mode = ShadeIndirectLightingMode.IBL }) {
         const scene = view_ctx.scene;
-        const meshlets = this.bodies.meshlets({ graph, view: view_ctx, camera, meshlet_capacity: this.meshlet_capacity });
         const settings = { ...this.settings };
         const probe = this.#probe;
         this.#probe = null;
         const resolution = Array.from(view_ctx.resolution);
-        const pixels = Math.max(1, settings.tessellation_pixels);
-        // Jitter moves raster samples, not the mesh sampling the simulation. A jittered
-        // reference would change displaced geometry and normals even while waves are paused.
-        const tessellation = { resolution, pixels,
-            view_projection_matrix: Float32Array.from(view_ctx.camera.camera.view_projection_matrix) };
-        const patches = graph_water_tessellation({ graph, scene, camera, meshlets,
-            meshlet_capacity: this.meshlet_capacity, tessellation });
+        const surface = this.waves;
+        // the lattice is chosen from the camera's position and its pixel angle, not its jittered projection's offset:
+        // raster jitter moves samples, not the mesh
+        const lod = water_lod_view(view_ctx.camera.camera.projection_matrix, resolution[1], Math.max(0.5, settings.tessellation_pixels));
+        const { meshlets, lod_bodies } = this.bodies.meshlets({ graph, view: view_ctx, camera, meshlet_capacity: this.meshlet_capacity,
+            visible_rows: surface.visible_rows, lod, steep: surface.steep });
+        const limits = { ...this.lod_budgets, triangles: Math.max(this.meshlet_capacity, 1) * GEOMETRY_MESHLET_TRIANGLE_LIMIT };
+        const patches = graph_water_tessellation({ graph, scene, camera, meshlets, lod_bodies, meshlet_capacity: this.meshlet_capacity,
+            lod, limits, steep: surface.steep });
+        this.#record_readback(graph, patches.statistics);
         const data = { resolution, frame_time: this.time };
-        const wave_state = this.waves.buffer, wave_resolution = this.waves.grid_resolution;
-        const geometry_bindings = () => ({ scene_database: scene.scene_database_buffer,
+        // the surface interface: the band tiles and the frame's particle hash; and the view's lattice
+        const geometry_bindings = (graphics, encoder, resources, d) => ({ scene_database: scene.scene_database_buffer,
             meshlet_metadata: scene.geometries.meshlets.buffer_metadata, meshlet_data: scene.geometries.meshlets.buffer_data,
-            wave_state });
+            water_band_displacement: surface.displacement, water_band_derivatives: surface.derivatives,
+            water_band_sampler: graphics.samplers.obtain(WATER_BAND_SAMPLER),
+            water_particle_offsets: surface.particle_offsets, water_particle_entries: surface.particle_entries,
+            lod: encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod),
+            lod_limits: encoder.allocateTransientValueBuffer(WATER_LOD_LIMITS_STRUCT, limits),
+            water_lod_bodies: resources.get(d.lod_bodies), water_lod_candidates: resources.get(d.candidates),
+            water_lod_cells: resources.get(d.cells) });
+        // the interior, boundary and triangle lists' draws, and the patches'
+        const draw = (render, commands, device) => {
+            for (let list = 0; list < 3; list++) { render.drawIndirect(commands, WaterLodCommand.Draws + 16 * list); }
+            render.setIndexBuffer(this.#patch_index_buffer(device), 'uint16');
+            render.drawIndexedIndirect(commands, WaterLodCommand.PatchDraw);
+        };
         const pipeline = this.#pipeline;
         const pass = graph.add("Water / receivers", data, (data, resources, context) => {
             const { encoder, graphics } = context;
@@ -104,13 +191,7 @@ export class GPUWaterRenderer {
                 tHZB: resources.get(data.hzb).obtainView(),
                 tScene: resources.get(data.color).obtainView(),
             };
-            const command = resources.get(data.command);
-            build_indirect_draw_command(graphics.device, `${WATER_TILE_VERTEX_COUNT}, input, 0, 0`,
-                encoder, resources.get(data.patch_count), command);
-            const bindings = WATER_RESOURCES.generateBindings({ ...shared, ...geometry_bindings(),
-                wave_grid: encoder.allocateTransientValueBuffer(WATER_GRID_STRUCT, { resolution: wave_resolution }),
-                water_tiles: resources.get(data.tiles), water_tile_sums: resources.get(data.sums),
-                tessellation: encoder.allocateTransientValueBuffer(WATER_TESSELLATION_STRUCT, tessellation) }, encoder);
+            const bindings = WATER_RESOURCES.generateBindings({ ...shared, ...geometry_bindings(graphics, encoder, resources, data) }, encoder);
             const render = encoder.constructRenderPass({ label: "Water / receivers", pipeline, bindings: [],
                 colorAttachments: [data.receiver, data.trace_metadata].map(handle => ({
                     view: resources.get(handle).obtainView(), loadOp: "clear", storeOp: "store", clearValue: [0,0,0,0],
@@ -119,7 +200,7 @@ export class GPUWaterRenderer {
                     depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0 },
             });
             graphics.setPipelineBindings(render, pipeline, bindings);
-            render.drawIndirect(command, 0);
+            draw(render, resources.get(data.commands), graphics.device);
             render.end();
         });
         for (const [name, handle] of Object.entries({ camera, color: color_texture, scene_depth: depth_texture,
@@ -128,8 +209,8 @@ export class GPUWaterRenderer {
             resolution, format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
                 | (probe !== null && format !== "depth32float" ? GPUTextureUsage.COPY_SRC : 0),
         }));
-        data.tiles = pass.read(patches.tiles); data.sums = pass.read(patches.sums); data.patch_count = pass.read(patches.count);
-        data.command = pass.create('Water draw command', BufferResourceDescriptor.from(16, GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT));
+        data.lod_bodies = pass.read(lod_bodies); data.candidates = pass.read(patches.candidates); data.cells = pass.read(patches.cells);
+        data.commands = pass.read(patches.commands);
         // Keep the accepted UV and both paths at f32 precision through final shading.
         data.receiver = target("receiver", "rgba32float");
         data.trace_metadata = target("trace metadata", "rgba32float");
@@ -164,9 +245,7 @@ export class GPUWaterRenderer {
                 tScene: resources.get(d.color).obtainView(),
                 receiver: resources.get(d.receiver).obtainView(), trace_metadata: resources.get(d.trace_metadata).obtainView(),
                 visibility_distance: resources.get(d.visibility_distance).obtainView(),
-                ...geometry_bindings(), water_tiles: resources.get(d.tiles), water_tile_sums: resources.get(d.sums),
-                tessellation: encoder.allocateTransientValueBuffer(WATER_TESSELLATION_STRUCT, tessellation),
-                wave_grid: encoder.allocateTransientValueBuffer(WATER_GRID_STRUCT, { resolution: wave_resolution }),
+                ...geometry_bindings(graphics, encoder, resources, d),
                 // the lights, as the transparent meshes bind them
                 light_data: view_ctx.scene.lights.buffer_data,
                 tEnvironment: resources.get(d.environment).obtainView(),
@@ -192,10 +271,11 @@ export class GPUWaterRenderer {
             graphics.setPipelineBindings(render, copy_pipeline, copy_bindings); render.draw(3);
             render.setPipeline(graphics.render_pipelines.obtain(finalize_pipeline)); render.record_pipeline(finalize_pipeline);
             graphics.setPipelineBindings(render, finalize_pipeline, bindings);
-            render.drawIndirect(resources.get(d.command), 0);
+            draw(render, resources.get(d.commands), graphics.device);
             render.end();
         });
-        for (const key of ['camera','scene_depth','normal','hzb','color','receiver','trace_metadata','visibility_distance','interface_depth','tiles','sums','command']) {
+        for (const key of ['camera','scene_depth','normal','hzb','color','receiver','trace_metadata','visibility_distance','interface_depth',
+            'lod_bodies','candidates','cells','commands']) {
             finalize_data[key] = finalize.read(data[key]);
         }
         for (const [key, handle] of Object.entries({ environment: environment_texture, light_cluster_parameters,

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts

@@ -1,15 +1,23 @@
-/** GPU work over the scene's water table; no per-body render commands or transient body uniforms. */
+/** A view's water bodies: which the view draws and how, and their meshlets in row order. */
 export class GPUWaterBodies {
-    record({ graph, scene }: {
-        graph: any;
-        scene: any;
-    }): void;
-    /** Ordered prefix expansion preserves equal-depth ownership, including after holes and reuse. */
-    meshlets({ graph, view, camera, meshlet_capacity }: {
+    /**
+     * Draw culling over the frame's visible list (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §4.3), each drawn
+     * body's lattice frame at its row, and the drawn bodies' meshlets. The expansion is an ordered prefix scan over the
+     * rows, which preserves equal-depth ownership, including after holes and reuse.
+     *
+     * @returns {{meshlets: number, lod_bodies: number}} resources
+     */
+    meshlets({ graph, view, camera, meshlet_capacity, visible_rows, lod, steep }: {
         graph: any;
         view: any;
         camera: any;
         meshlet_capacity: any;
-    }): any;
+        visible_rows: any;
+        lod: any;
+        steep: any;
+    }): {
+        meshlets: number;
+        lod_bodies: number;
+    };
 }
 //# sourceMappingURL=GPUWaterBodies.d.ts.map

package/src/shade/renderer/water/medium/GPUWaterBodies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterBodies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/GPUWaterBodies.js"],"names":[],"mappings":"AAUA,qGAAqG;AACrG;IACI;;;aASC;IAED,iGAAiG;IACjG;;;;;YAsCC;CACJ"}
+{"version":3,"file":"GPUWaterBodies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/medium/GPUWaterBodies.js"],"names":[],"mappings":"AAcA,4FAA4F;AAC5F;IACI;;;;;;OAMG;IACH;;;;;;;;QAFa;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CA8ClD;CACJ"}