@woosh/meep-engine 3.68.0 → 3.70.0

package/src/shade/renderer/trails/shaders/shader_trail_update.js

@@ -0,0 +1,101 @@
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { TRAIL_DESCRIPTOR, TRAIL_STATE_DESCRIPTOR } from "../data/TRAIL_DATABASE_SPEC.js";
+import { chunk_trail_update } from "./chunk_trail_update.js";
+
+/**
+ * Threads per workgroup; one trail row each. The page iterator wants a multiple of 32.
+ * @type {number}
+ */
+export const TRAIL_UPDATE_WORKGROUP_SIZE = 64;
+
+const PG = TRAIL_DESCRIPTOR.page_iterator_symbol_prefix(TRAIL_UPDATE_WORKGROUP_SIZE, true);
+const STATE = TRAIL_STATE_DESCRIPTOR;
+
+export const TRAIL_UPDATE_SETTINGS = WebGPUStruct.from({
+    /** the clock, in ticks */
+    now: u32,
+    /** element capacity of the trail table: the length of the counts list the scan reads */
+    capacity: u32,
+}, "Trail3DUpdateSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", TRAIL_UPDATE_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("trail_database", WebGPUArray.u32, true)
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("knots", WebGPUArray.u32, true)
+    .addStorageBuffer("live_segments", COLLECTION_U32_STRUCT_READ, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${TRAIL_UPDATE_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // the scan reads exactly this many counts; written before the page test so it lands even when the
+    // first page is unallocated
+    if (wg_id.x == 0u && local_id == 0u) {
+        live_segments.count = settings.capacity;
+    }
+
+    if (!${PG}_setup(&trail_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot = ${PG}_slot_in_page(local_id);
+
+    if (slot >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot)) {
+        return;
+    }
+
+    let record = ${PG}_read(&trail_database, slot);
+    let row = ${PG}_slot_to_index(slot);
+
+    var state = ${STATE.marshalling_method_read_rw}(&trail_database, row);
+
+    if (state.seeded_epoch != record.seed_epoch) {
+        // a seed has been asked for and not run yet: nothing to draw until it has
+        live_segments.elements[row] = 0u;
+        return;
+    }
+
+    let head = trail_head_world(scene_read_node(&scene_database, record.node).global, record.offset);
+
+    live_segments.elements[row] = trail_update(record, &state, head, settings.now);
+
+    ${STATE.marshalling_method_write}(&trail_database, row, state);
+}
+`, [
+    TRAIL_DESCRIPTOR.chunk_iterate(TRAIL_UPDATE_WORKGROUP_SIZE, true),
+    STATE.chunk_read_rw,
+    STATE.chunk_write,
+    chunk_scene_database_access,
+    chunk_trail_update,
+]);
+
+/**
+ * One frame of every trail: a thread per row of the trail table, through the table's page iterator.
+ * Each reads its entity's world matrix from the scene database — the hierarchy has composed this
+ * frame's — runs `trail_update`, writes its state back, and writes how many of its segments can be
+ * visible into `live_segments`, the list the scan sums.
+ *
+ * A row whose state has not been seeded for its record's epoch writes zero and waits for its seed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_trail_update = ComputeShader.from({
+    label: "Trail Update",
+    resources,
+    body,
+});

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

@@ -159,7 +159,7 @@ function graph_integrate_participating_media({
 
             // 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);
+            const switches = shader_switches.with(WIND_FIELD_UNIFORM, scene.wind.is_uniform);
 
             shader_volumetrics_build_participating_media.variant(switches).dispatchThreads({
                 encoder,
@@ -355,7 +355,7 @@ function graph_build_sun_shadow_volume({
 
                 scene.wind.bind(bindings);
 
-                const switches = shader_switches.with(WIND_FIELD_UNIFORM, scene.wind.cascade_count === 0);
+                const switches = shader_switches.with(WIND_FIELD_UNIFORM, scene.wind.is_uniform);
 
                 base_shader.variant(switches).dispatch({
                     encoder,

package/src/shade/renderer/water/query/shader_water_surface_query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_surface_query.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/query/shader_water_surface_query.js"],"names":[],"mappings":"AA8BA,gEAAgE;AAChE,mDAAoD;AAEpD;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,iDAFU,YAAY,CAMS;AA+J/B;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;6BApN0B,mCAAmC;8BAVlC,+BAA+B"}
+{"version":3,"file":"shader_water_surface_query.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/query/shader_water_surface_query.js"],"names":[],"mappings":"AA8BA,gEAAgE;AAChE,mDAAoD;AAEpD;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,iDAFU,YAAY,CAMS;AA+J/B;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;6BAtN0B,mCAAmC;8BARlC,+BAA+B"}

package/src/shade/renderer/water/query/shader_water_surface_query.js

@@ -1,227 +1,227 @@
-import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
-import { MESHLET_METADATA_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import { SCENE_DATABASE_RESOURCE } from "../../scene/SCENE_DATABASE_RESOURCE.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
-import { chunk_encode_vertex_normal } from "../../shader/chunk/geometry/normal/chunk_encode_vertex_normal.js";
-import { chunk_ray_query_blas_nearest } from "../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
-import { chunk_point_query_blas_nearest } from "../../shader/chunk/sdf/chunk_point_query_blas_nearest.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { WATER_BODIES_TABLE } from "../medium/chunk_water_bodies.js";
-import { chunk_water_surface_sample } from "../surface/chunk_water_surface_sample.js";
-import {
-    WATER_BAND_DERIVATIVES_RESOURCE,
-    WATER_BAND_DISPLACEMENT_RESOURCE,
-    WATER_BAND_SAMPLER_RESOURCE,
-    WATER_PARTICLE_ENTRIES_RESOURCE,
-    WATER_PARTICLE_OFFSETS_RESOURCE
-} from "../surface/WATER_SURFACE_RESOURCES.js";
-import {
-    WATER_QUERY_DESCRIPTOR,
-    WATER_QUERY_SAMPLE_DESCRIPTOR,
-    WATER_QUERY_SAMPLE_STRUCT
-} from "./WATER_QUERY_DATABASE_SPEC.js";
-
-/** Invocations of a gather workgroup, one query sample each. */
-export const WATER_QUERY_GATHER_WORKGROUP_SIZE = 64;
-
-/**
- * Words of one entry of the gather's list: the request's row in `water_query`, then the flat index
- * of its first sample among the dispatch's.
- * @type {number}
- */
-export const WATER_QUERY_GATHER_ENTRY_WORDS = 2;
-
-/**
- * Per dispatch, 12 bytes, as immediate data.
- *
- * - `query_count`: entries of the list;
- * - `sample_count`: samples of every entry together, one invocation each;
- * - `row_width`: invocations a row of the dispatch holds, its x extent, so sample
- *   `id.y · row_width + id.x` lands past the guaranteed workgroup count along x without
- *   `num_workgroups`.
- *
- * @type {WebGPUStruct}
- */
-export const WATER_QUERY_GATHER_SETTINGS_STRUCT = WebGPUStruct.from({
-    query_count: u32,
-    sample_count: u32,
-    row_width: u32,
-}, 'WaterQueryGatherSettings');
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.setImmediate('settings', WATER_QUERY_GATHER_SETTINGS_STRUCT);
-
-resources.createGroup()
-    .addStorageBuffer("database", WebGPUArray.from(u32), true)
-    .addStorageBuffer("list", WebGPUArray.from(u32), false)
-    .add(SCENE_DATABASE_RESOURCE)
-    .add(WATER_BAND_DISPLACEMENT_RESOURCE)
-    .add(WATER_BAND_DERIVATIVES_RESOURCE)
-    .add(WATER_BAND_SAMPLER_RESOURCE)
-    .add(WATER_PARTICLE_OFFSETS_RESOURCE)
-    .add(WATER_PARTICLE_ENTRIES_RESOURCE)
-    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
-    .addStorageBuffer("blas_lookup", WebGPUArray.u32)
-    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT))
-    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
-    .addStorageBuffer("meshlet_data", WebGPUArray.from(f32));
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const ENTRY_WORDS = ${WATER_QUERY_GATHER_ENTRY_WORDS}u;
-
-// the entry a flat sample belongs to: the last one whose first sample is at or before it. The first
-// entry starts at 0, so one always is; 32 halvings cover any u32 count.
-fn water_query_gather_entry(sample: u32) -> u32 {
-    var low = 0u;
-    var high = settings.query_count;
-
-    for (var step = 0u; step < 32u && high - low > 1u; step++) {
-        let middle = low + ((high - low) >> 1u);
-
-        if (list[middle * ENTRY_WORDS + 1u] <= sample) {
-            low = middle;
-        } else {
-            high = middle;
-        }
-    }
-
-    return low;
-}
-
-@compute @workgroup_size(${WATER_QUERY_GATHER_WORKGROUP_SIZE})
-fn main(@builtin(global_invocation_id) id: vec3<u32>) {
-    let sample = id.y * settings.row_width + id.x;
-
-    if (sample >= settings.sample_count) {
-        return;
-    }
-
-    let entry = water_query_gather_entry(sample);
-
-    let row = list[entry * ENTRY_WORDS];
-    let local = sample - list[entry * ENTRY_WORDS + 1u];
-
-    let query = ${WATER_QUERY_DESCRIPTOR.marshalling_method_read_rw}(&database, row);
-    let sample_row = query.first_sample + local;
-
-    // Input (local_x, local_z) is packed in the transient list buffer right after the query entries.
-    let point_word = (settings.query_count + sample) * ENTRY_WORDS;
-    let input_xz = vec2<f32>(bitcast<f32>(list[point_word]), bitcast<f32>(list[point_word + 1u]));
-
-    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, query.body);
-    if (body.node == 0u || body.node == ~0u) {
-        ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
-            ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(0.0, encode_vertex_normal(vec3<f32>(0.0, 1.0, 0.0))));
-        return;
-    }
-
-    let global = scene_read_node(&scene_database, body.node).global;
-    let c0 = global[0].xyz;
-    let c1 = global[1].xyz;
-    let c2 = global[2].xyz;
-    let cof0 = cross(c1, c2);
-    let cof1 = cross(c2, c0);
-    let cof2 = cross(c0, c1);
-    let det = dot(c0, cof0);
-
-    if (abs(det) < 1e-20) {
-        ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
-            ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(global[3].y, encode_vertex_normal(vec3<f32>(0.0, 1.0, 0.0))));
-        return;
-    }
-
-    let scale = max(vec3<f32>(length(c0), length(c1), length(c2)), vec3<f32>(1e-20));
-    let geometry_index = body.geometry;
-    let box = geometries[geometry_index].bounding_box;
-    let clamped_box_xz = clamp(input_xz, vec2<f32>(box[0], box[2]), vec2<f32>(box[3], box[5]));
-
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
-    var rest_position: vec3<f32>;
-    var inside = false;
-
-    // 1. Inside-outline check via down-ray into the body's BLAS (skipped when already outside the XZ AABB).
-    if (all(input_xz == clamped_box_xz)) {
-        let margin = max(1e-3, (box[4] - box[1]) * 1e-4);
-        let top = box[4] + margin;
-        let hit = ray_query_blas_nearest(
-            Ray(vec3<f32>(input_xz.x, top, input_xz.y), vec3<f32>(0.0, -1.0, 0.0), top - box[1] + margin),
-            geometry_index,
-            &stack,
-            0u
-        );
-        if (hit.t >= 0.0) {
-            rest_position = vec3<f32>(input_xz.x, top - hit.t, input_xz.y);
-            inside = true;
-        }
-    }
-
-    // 2. Outside the shoreline or inside an island hole: clamp continuously to the nearest point on the mesh.
-    if (!inside) {
-        let mid_y = 0.5 * (box[1] + box[4]);
-        let box_diag = length(vec3<f32>(box[3] - box[0], box[4] - box[1], box[5] - box[2]));
-        let max_reach = min(1e18, distance(input_xz, clamped_box_xz) + box_diag + 1.0);
-        let nearest = point_query_blas_nearest(vec3<f32>(input_xz.x, mid_y, input_xz.y), max_reach, geometry_index, &stack, 0u);
-        if (nearest.primitive != 0xFFFFFFFFu) {
-            rest_position = nearest.position;
-        } else {
-            rest_position = vec3<f32>(clamped_box_xz.x, mid_y, clamped_box_xz.y);
-        }
-    }
-
-    // 3. Evaluate water_surface_sample at the clamped metric rest position, with 2 fixed-point steps
-    //    to invert horizontal choppiness (Gerstner / particle horizontal displacement).
-    let target_metric = rest_position.xz * scale.xz;
-    let footprint = max(query.footprint, 1e-6);
-    var sample_p = target_metric;
-    for (var iter = 0u; iter < 2u; iter++) {
-        let step_sample = water_surface_sample(body.wave, sample_p, footprint, 1.0);
-        sample_p = target_metric - step_sample.offset.xz;
-    }
-    let surface = water_surface_sample(body.wave, sample_p, footprint, 1.0);
-
-    // 4. Transform displaced height and normal to world space, and pack normal into u32.
-    let displaced_local = vec3<f32>(rest_position.x, rest_position.y + surface.offset.y / scale.y, rest_position.z);
-    let world_height = (global * vec4<f32>(displaced_local, 1.0)).y;
-
-    let local_normal = normalize(surface.normal * scale);
-    let world_normal = normalize((cof0 * local_normal.x + cof1 * local_normal.y + cof2 * local_normal.z) * (1.0 / det));
-    let packed_normal = encode_vertex_normal(world_normal);
-
-    ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
-        ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(world_height, packed_normal));
-}
-`, [
-        WATER_QUERY_DESCRIPTOR.chunk_read_rw,
-        WATER_QUERY_SAMPLE_DESCRIPTOR.chunk_write,
-        WATER_BODIES_TABLE.chunk_read,
-        chunk_scene_database_access,
-        chunk_water_surface_sample,
-        chunk_ray_query_blas_nearest,
-        chunk_point_query_blas_nearest,
-        chunk_encode_vertex_normal,
-    ]
-);
-
-/**
- * The GPU water surface read API's gather: evaluates the displaced world-space surface height and
- * world-space normal (packed as a single `u32` via `encode_vertex_normal`) at every query point
- * requested this frame, clamping off-outline or island-hole points continuously to the nearest
- * point on the body's authored mesh via `point_query_blas_nearest`.
- *
- * @type {ComputeShader}
- */
-export const shader_water_surface_query = ComputeShader.from({
-    label: "Water / surface query",
-    resources,
-    body,
-});
+import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { SCENE_DATABASE_RESOURCE } from "../../scene/SCENE_DATABASE_RESOURCE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { chunk_encode_vertex_normal } from "../../shader/chunk/geometry/normal/chunk_encode_vertex_normal.js";
+import { chunk_ray_query_blas_nearest } from "../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+import { chunk_point_query_blas_nearest } from "../../shader/chunk/sdf/chunk_point_query_blas_nearest.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { WATER_BODIES_TABLE } from "../medium/chunk_water_bodies.js";
+import { chunk_water_surface_sample } from "../surface/chunk_water_surface_sample.js";
+import {
+    WATER_BAND_DERIVATIVES_RESOURCE,
+    WATER_BAND_DISPLACEMENT_RESOURCE,
+    WATER_BAND_SAMPLER_RESOURCE,
+    WATER_PARTICLE_ENTRIES_RESOURCE,
+    WATER_PARTICLE_OFFSETS_RESOURCE
+} from "../surface/WATER_SURFACE_RESOURCES.js";
+import {
+    WATER_QUERY_DESCRIPTOR,
+    WATER_QUERY_SAMPLE_DESCRIPTOR,
+    WATER_QUERY_SAMPLE_STRUCT
+} from "./WATER_QUERY_DATABASE_SPEC.js";
+import { BVH8_INODE_STRUCT } from "../../shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
+import { BVH8_TRAVERSAL_STACK_SIZE } from "../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
+
+/** Invocations of a gather workgroup, one query sample each. */
+export const WATER_QUERY_GATHER_WORKGROUP_SIZE = 64;
+
+/**
+ * Words of one entry of the gather's list: the request's row in `water_query`, then the flat index
+ * of its first sample among the dispatch's.
+ * @type {number}
+ */
+export const WATER_QUERY_GATHER_ENTRY_WORDS = 2;
+
+/**
+ * Per dispatch, 12 bytes, as immediate data.
+ *
+ * - `query_count`: entries of the list;
+ * - `sample_count`: samples of every entry together, one invocation each;
+ * - `row_width`: invocations a row of the dispatch holds, its x extent, so sample
+ *   `id.y · row_width + id.x` lands past the guaranteed workgroup count along x without
+ *   `num_workgroups`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_QUERY_GATHER_SETTINGS_STRUCT = WebGPUStruct.from({
+    query_count: u32,
+    sample_count: u32,
+    row_width: u32,
+}, 'WaterQueryGatherSettings');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', WATER_QUERY_GATHER_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer("database", WebGPUArray.from(u32), true)
+    .addStorageBuffer("list", WebGPUArray.from(u32), false)
+    .add(SCENE_DATABASE_RESOURCE)
+    .add(WATER_BAND_DISPLACEMENT_RESOURCE)
+    .add(WATER_BAND_DERIVATIVES_RESOURCE)
+    .add(WATER_BAND_SAMPLER_RESOURCE)
+    .add(WATER_PARTICLE_OFFSETS_RESOURCE)
+    .add(WATER_PARTICLE_ENTRIES_RESOURCE)
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer("blas_lookup", WebGPUArray.u32)
+    .addStorageBuffer("blas_data", WebGPUArray.from(BVH8_INODE_STRUCT))
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer("meshlet_data", WebGPUArray.from(f32));
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const ENTRY_WORDS = ${WATER_QUERY_GATHER_ENTRY_WORDS}u;
+
+// the entry a flat sample belongs to: the last one whose first sample is at or before it. The first
+// entry starts at 0, so one always is; 32 halvings cover any u32 count.
+fn water_query_gather_entry(sample: u32) -> u32 {
+    var low = 0u;
+    var high = settings.query_count;
+
+    for (var step = 0u; step < 32u && high - low > 1u; step++) {
+        let middle = low + ((high - low) >> 1u);
+
+        if (list[middle * ENTRY_WORDS + 1u] <= sample) {
+            low = middle;
+        } else {
+            high = middle;
+        }
+    }
+
+    return low;
+}
+
+@compute @workgroup_size(${WATER_QUERY_GATHER_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let sample = id.y * settings.row_width + id.x;
+
+    if (sample >= settings.sample_count) {
+        return;
+    }
+
+    let entry = water_query_gather_entry(sample);
+
+    let row = list[entry * ENTRY_WORDS];
+    let local = sample - list[entry * ENTRY_WORDS + 1u];
+
+    let query = ${WATER_QUERY_DESCRIPTOR.marshalling_method_read_rw}(&database, row);
+    let sample_row = query.first_sample + local;
+
+    // Input (local_x, local_z) is packed in the transient list buffer right after the query entries.
+    let point_word = (settings.query_count + sample) * ENTRY_WORDS;
+    let input_xz = vec2<f32>(bitcast<f32>(list[point_word]), bitcast<f32>(list[point_word + 1u]));
+
+    let body = ${WATER_BODIES_TABLE.marshalling_method_read}(&scene_database, query.body);
+    if (body.node == 0u || body.node == ~0u) {
+        ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
+            ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(0.0, encode_vertex_normal(vec3<f32>(0.0, 1.0, 0.0))));
+        return;
+    }
+
+    let global = scene_read_node(&scene_database, body.node).global;
+    let c0 = global[0].xyz;
+    let c1 = global[1].xyz;
+    let c2 = global[2].xyz;
+    let cof0 = cross(c1, c2);
+    let cof1 = cross(c2, c0);
+    let cof2 = cross(c0, c1);
+    let det = dot(c0, cof0);
+
+    if (abs(det) < 1e-20) {
+        ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
+            ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(global[3].y, encode_vertex_normal(vec3<f32>(0.0, 1.0, 0.0))));
+        return;
+    }
+
+    let scale = max(vec3<f32>(length(c0), length(c1), length(c2)), vec3<f32>(1e-20));
+    let geometry_index = body.geometry;
+    let box = geometries[geometry_index].bounding_box;
+    let clamped_box_xz = clamp(input_xz, vec2<f32>(box[0], box[2]), vec2<f32>(box[3], box[5]));
+
+    var stack: array<vec2u, ${BVH8_TRAVERSAL_STACK_SIZE}>;
+    var rest_position: vec3<f32>;
+    var inside = false;
+
+    // 1. Inside-outline check via down-ray into the body's BLAS (skipped when already outside the XZ AABB).
+    if (all(input_xz == clamped_box_xz)) {
+        let margin = max(1e-3, (box[4] - box[1]) * 1e-4);
+        let top = box[4] + margin;
+        let hit = ray_query_blas_nearest(
+            Ray(vec3<f32>(input_xz.x, top, input_xz.y), vec3<f32>(0.0, -1.0, 0.0), top - box[1] + margin),
+            geometry_index,
+            &stack,
+            0u
+        );
+        if (hit.t >= 0.0) {
+            rest_position = vec3<f32>(input_xz.x, top - hit.t, input_xz.y);
+            inside = true;
+        }
+    }
+
+    // 2. Outside the shoreline or inside an island hole: clamp continuously to the nearest point on the mesh.
+    if (!inside) {
+        let mid_y = 0.5 * (box[1] + box[4]);
+        let box_diag = length(vec3<f32>(box[3] - box[0], box[4] - box[1], box[5] - box[2]));
+        let max_reach = min(1e18, distance(input_xz, clamped_box_xz) + box_diag + 1.0);
+        let nearest = point_query_blas_nearest(vec3<f32>(input_xz.x, mid_y, input_xz.y), max_reach, geometry_index, &stack, 0u);
+        if (nearest.primitive != 0xFFFFFFFFu) {
+            rest_position = nearest.position;
+        } else {
+            rest_position = vec3<f32>(clamped_box_xz.x, mid_y, clamped_box_xz.y);
+        }
+    }
+
+    // 3. Evaluate water_surface_sample at the clamped metric rest position, with 2 fixed-point steps
+    //    to invert horizontal choppiness (Gerstner / particle horizontal displacement).
+    let target_metric = rest_position.xz * scale.xz;
+    let footprint = max(query.footprint, 1e-6);
+    var sample_p = target_metric;
+    for (var iter = 0u; iter < 2u; iter++) {
+        let step_sample = water_surface_sample(body.wave, sample_p, footprint, 1.0);
+        sample_p = target_metric - step_sample.offset.xz;
+    }
+    let surface = water_surface_sample(body.wave, sample_p, footprint, 1.0);
+
+    // 4. Transform displaced height and normal to world space, and pack normal into u32.
+    let displaced_local = vec3<f32>(rest_position.x, rest_position.y + surface.offset.y / scale.y, rest_position.z);
+    let world_height = (global * vec4<f32>(displaced_local, 1.0)).y;
+
+    let local_normal = normalize(surface.normal * scale);
+    let world_normal = normalize((cof0 * local_normal.x + cof1 * local_normal.y + cof2 * local_normal.z) * (1.0 / det));
+    let packed_normal = encode_vertex_normal(world_normal);
+
+    ${WATER_QUERY_SAMPLE_DESCRIPTOR.marshalling_method_write}(&database, sample_row,
+        ${WATER_QUERY_SAMPLE_STRUCT.wgsl_ref}(world_height, packed_normal));
+}
+`, [
+        WATER_QUERY_DESCRIPTOR.chunk_read_rw,
+        WATER_QUERY_SAMPLE_DESCRIPTOR.chunk_write,
+        WATER_BODIES_TABLE.chunk_read,
+        chunk_scene_database_access,
+        chunk_water_surface_sample,
+        chunk_ray_query_blas_nearest,
+        chunk_point_query_blas_nearest,
+        chunk_encode_vertex_normal,
+    ]
+);
+
+/**
+ * The GPU water surface read API's gather: evaluates the displaced world-space surface height and
+ * world-space normal (packed as a single `u32` via `encode_vertex_normal`) at every query point
+ * requested this frame, clamping off-outline or island-hole points continuously to the nearest
+ * point on the body's authored mesh via `point_query_blas_nearest`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_water_surface_query = ComputeShader.from({
+    label: "Water / surface query",
+    resources,
+    body,
+});

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAuN8E;0BAlPvE,uCAAuC"}
+{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CA0N8E;0BArPvE,uCAAuC"}

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.js

@@ -1,10 +1,10 @@
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
 import { chunk_ray_query_blas_nearest } from "../../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
 import { chunk_geometry_read_triangle_positions } from "../../../shader/chunk/geometry/format/chunk_geometry_read_triangle_positions.js";
 import { RAY_HIT_INFO } from "../../../shader/chunk/geometry/ray/RAY_HIT_INFO.js";
 import { WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
 import { chunk_water_particle } from "./chunk_water_particle.js";
+import { BVH8_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
 
 /**
  * Time constant of a dying packet's fade: one that has fallen below the drawing threshold fades to a tenth of it, where
@@ -44,7 +44,7 @@ fn water_particle_over_body(geometry_index: u32, local: vec2<f32>) -> ${RAY_HIT_
     let box = geometries[geometry_index].bounding_box;
     let margin = max(1e-3, (box[4] - box[1]) * 1e-4);
     let top = box[4] + margin;
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+    var stack: array<vec2u, ${BVH8_TRAVERSAL_STACK_SIZE}>;
     return ray_query_blas_nearest(Ray(vec3<f32>(local.x, top, local.y), vec3<f32>(0.0, -1.0, 0.0),
         top - box[1] + margin), geometry_index, &stack, 0u);
 }
@@ -101,8 +101,11 @@ struct WaterOutlineLine {
 }
 
 fn water_outline_line(geometry_index: u32, triangle: u32, point: vec2<f32>, scale: vec2<f32>) -> WaterOutlineLine {
-    let vertices = geometry_read_triangle_vertices(geometries[geometry_index], triangle);
-    let corners = array<vec2<f32>, 3>(vertices.a.position.xz * scale, vertices.b.position.xz * scale, vertices.c.position.xz * scale);
+    var a: vec3<f32>;
+    var b: vec3<f32>;
+    var c: vec3<f32>;
+    geometry_read_triangle_positions(&a, &b, &c, geometries[geometry_index], triangle);
+    let corners = array<vec2<f32>, 3>(a.xz * scale, b.xz * scale, c.xz * scale);
     var nearest = 3.0e38;
     var line = WaterOutlineLine(point, vec2<f32>(0.0));
     for (var edge = 0u; edge < 3u; edge++) {

package/src/shade/renderer/water/surface/particles/shader_water_particles.js

@@ -13,7 +13,6 @@ import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../../gpu_primitive/indirect
 import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
 import { GEOMETRY_METADATA_STRUCT } from "../../../geometry/GEOMETRY_METADATA_STRUCT.js";
 import { MESHLET_METADATA_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import { BVH2_NODE_STRUCT } from "../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
 import { chunk_scene_database_access, chunk_scene_database_access_rw } from "../../../scene/chunk_scene_database_access.js";
 import { WaterActivity } from "../shader_water_cull.js";
@@ -24,6 +23,7 @@ import { WATER_WAVE_IMPULSE_LIMIT } from "../WATER_WAVE_RECORD_STRUCT.js";
 import { chunk_water_particle } from "./chunk_water_particle.js";
 import { chunk_water_particle_step } from "./chunk_water_particle_step.js";
 import { WATER_PARTICLE_GATHER_BUDGET } from "../chunk_water_surface_sample.js";
+import { BVH8_INODE_STRUCT } from "../../../shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
 
 /** A particle array with its live count in front, as the indirect commands read it. */
 export const WATER_PARTICLE_ARRAY_STRUCT = WebGPUStruct.fromFields(
@@ -125,7 +125,7 @@ update_resources.createGroup()
     .addStorageBuffer('scene_database', WebGPUArray.u32)
     .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
     .addStorageBuffer('blas_lookup', WebGPUArray.u32)
-    .addStorageBuffer('blas_data', WebGPUArray.from(BVH2_NODE_STRUCT))
+    .addStorageBuffer('blas_data', WebGPUArray.from(BVH8_INODE_STRUCT))
     .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
     .addStorageBuffer('meshlet_data', WebGPUArray.from(f32));