@woosh/meep-engine 3.69.0 → 3.70.0

package/src/shade/playground/particle_ecs/bonfire_wind.js

@@ -1,16 +1,14 @@
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { GlobalFluidEffector } from "../../../engine/physics/fluid/effector/GlobalFluidEffector.js";
 
 /**
- * The weather over the fire: a steady wind and a gust on top, written straight onto the scene's
- * published wind field as its far field, `v_far(t)`.
+ * The weather over the fire: a steady wind and its turbulence, written straight onto the scene's
+ * published wind field as its far field.
  *
  * There is no fluid here. The field is the one every `GPUSceneContext` has, with no cascades, so every
- * particle that reads `SAMPLE_WIND` reads `v_far` exactly — the page plays the part a producer plays,
- * through the same `set_far_velocity` it would call. The gust is `GlobalFluidEffector`'s, used on its
- * own as the model it is (three sinusoids per axis, bounded by `gust`, turning as it goes): the page
- * advances it and adds it to the wind, which is what the far field's fold does with one global and
- * no drag.
+ * particle that reads `SAMPLE_WIND` reads the far field exactly — the page plays the part a producer
+ * plays, through the same `set_far_velocity` and `set_turbulence` it would call, and does what the far
+ * field's fold does with one global and no drag: the mean is the wind, the turbulence's rms is the
+ * intensity times its speed, and the mean carries the eddies, `offset += wind · dt`.
  *
  * What reads it is the four effects' own graphs: the flame, the embers and the soot are carried by
  * the air — their positions integrate the wind at the particle on top of their own velocity, the
@@ -31,53 +29,52 @@ export class BonfireWind {
     heading_degrees = -38;
 
     /**
-     * Peak gust on top of the wind, m/s per axis — `GlobalFluidEffector#gust`'s meaning.
+     * Turbulence intensity, `GlobalFluidEffector#turbulence_intensity`'s meaning: the eddies' rms as a
+     * share of the wind's speed. A gusty night.
      * @type {number}
      */
-    gust = 1.5;
+    turbulence_intensity = 0.3;
 
     /**
-     * The gust model, used for nothing else.
-     * @type {GlobalFluidEffector}
+     * The turbulence's length scale, m, `GlobalFluidEffector#turbulence_length`'s meaning: at the
+     * default speed its most energetic wavelength, `4.05·L`, goes by in about three seconds.
+     * @type {number}
      */
-    #weather = new GlobalFluidEffector();
-
-    /** @type {Float64Array} */
-    #gust_now = new Float64Array(3);
+    turbulence_length = 1.5;
 
     /**
-     * `v_far(t)` as last written.
+     * The mean as last written, m/s.
      * @type {Float64Array}
      */
     far_velocity = new Float64Array(3);
 
-    constructor() {
-        // quicker than a cloth's breeze: a fire in a gusty night
-        this.#weather.gust_period = 3;
-    }
+    /**
+     * How far the mean has carried the eddies, m.
+     * @type {Float64Array}
+     */
+    turbulence_offset = new Float64Array(3);
 
     /**
-     * Advance the gust by `dt` and write the wind onto the scene's field. Once a frame, before the
-     * frame renders: the scene context uploads the field's table in its own update.
+     * Advance the weather by `dt` and write it onto the scene's field. Once a frame, before the frame
+     * renders: the scene context uploads the field's table in its own update.
      *
      * @param {number} dt seconds
      * @param {import("../../renderer/wind/GPUSceneWind.js").GPUSceneWind} wind_field
      */
     blow(dt, wind_field) {
-        const weather = this.#weather;
-        const gust = this.#gust_now;
-
-        weather.gust = this.gust;
-        weather.advance(dt);
-        weather.compute_gust(gust);
-
         const heading = this.heading_degrees * DEG_TO_RAD;
         const far = this.far_velocity;
+        const offset = this.turbulence_offset;
+
+        far[0] = this.speed * Math.cos(heading);
+        far[1] = 0;
+        far[2] = this.speed * Math.sin(heading);
 
-        far[0] = this.speed * Math.cos(heading) + gust[0];
-        far[1] = gust[1];
-        far[2] = this.speed * Math.sin(heading) + gust[2];
+        offset[0] += far[0] * dt;
+        offset[1] += far[1] * dt;
+        offset[2] += far[2] * dt;
 
         wind_field.set_far_velocity(far);
+        wind_field.set_turbulence(Math.max(0, this.turbulence_intensity) * Math.abs(this.speed), offset, this.turbulence_length);
     }
 }

package/src/shade/playground/skinned_blas_refit/README.md

@@ -44,26 +44,38 @@ It drives frames by hand and compares two **independent** GPU computations of on
 
 - `shader_meshlet_bounds_reduce` merges every deformed vertex into the clone's geometry-metadata
   bounding box. It exists for the rasterizer's culling and knows nothing about trees.
-- `GPUBLASRefitBatch` takes each leaf triangle's box and climbs the tree, so the root node ends up
-  bounding every triangle.
+- `GPUBLASRefitBatch` fits every node of the clone's tree to the triangles under it, so the boxes
+  the root keeps for its slots, together, bound every triangle.
 
-Same vertices, same frame, no shared code. `min` and `max` are exact in floating point, so the two
-should agree to the bit; a stale BLAS cannot make them, because the metadata box tracks the pose
-while the root holds the bind pose.
+Same vertices, same frame, no shared code. A node keeps its slots' boxes on a grid of its own,
+rounded outward, so the two do not agree to the bit: the root's box has to hold the metadata box and
+reach less than one step of the root's grid past it. A stale BLAS cannot do that, because the
+metadata box tracks the pose while the root holds the bind pose.
 
 It takes two samples a third of a second apart. Agreement at each is one half of the answer; the
 box having *moved* between them is the other, and it is what catches a refit that runs but reads
 the source's rest-pose vertices — those boxes would agree at every sample and never move.
 
-Then it reads the clone's whole node region back and holds every internal node against its own two
-children. The root agreeing says the climb reached the top with the right answer; it says nothing
-about the nodes underneath, and traversal descends through *those* — a subtree whose box is too
-small is a hole rays fall through however right the root is. The property the climb establishes is
-local and exact, so this is bit equality rather than a tolerance.
-
-Measured on an NVIDIA Lovelace device: root box bit-identical to the metadata box at every sample,
-moving 0.39–0.80 of its own span between poses, all 28 105 internal nodes exactly their children's
-union, and each clone at its own arena address on a uniform stride.
+Then it reads the clone's whole node region back and holds every slot against the triangles under
+it, fetched the way the ray queries fetch them: a slot that names triangles against those
+triangles, a slot that names a child node against every triangle below that node. The root agreeing
+says nothing about the nodes underneath, and traversal descends through *those* — a slot whose box
+is too small is a hole rays fall through however right the root is. Every triangle has to be named
+by one slot and one only. No frame runs between reading the tree and reading the triangles, so this
+is containment with no slack.
+
+Measured on an NVIDIA Lovelace device: the root holds the metadata box at both samples and reaches
+0.54 and 0.81 of a step past it, moving 0.11 of its own span between poses; all 28,106 triangles
+and all 4,246 child nodes sit inside the slots that name them.
+
+`verify_leaves()` asks the same of a geometry nothing deforms, refitted from its own vertices, and
+`verify_clone_leaves()` of a clone in mid-dance, reporting the nodes that fail as runs and as the
+refit's workgroups.
+
+`verify_traversal_reachability` aims a ray at every triangle's centroid and expects a hit at or
+before it. On this asset it reports just under 1% of rays lost, and it reported the same against
+the binary trees this playground was written for (266 of 28,106 then, 268 now): what it counts
+there is the asset's own triangles, not the tree.
 
 ## Assets
 

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts

@@ -1,24 +1,29 @@
 export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
 /**
- * Which tree, and where it lives — one tree at a time, which is what an audit is.
+ * Triangle ids a meshlet can hold, used or not: the audit asks about every one of them, so that a
+ * thread's index says which triangle it is without a table. `(meshlet << 8) | triangle` is the id;
+ * a thread's index is `meshlet * BLAS_AUDIT_MESHLET_STRIDE + triangle`.
  *
+ * @type {number}
+ */
+export const BLAS_AUDIT_MESHLET_STRIDE: number;
+/**
  * @type {WebGPUStruct}
  */
 export const BLAS_AUDIT_SETTINGS_STRUCT: WebGPUStruct;
 /**
- * Read every leaf's triangle back through the path the *intersector* uses.
+ * Read every triangle of a geometry back through the path the *intersector* uses.
  *
- * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
- * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
- * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
+ * The refit computes a slot's box with `geometry_read_triangle_bounds`; the ray queries fetch the
+ * triangles they test with `geometry_read_triangle_positions`. Those are two different functions over
+ * the same encoded payload.
  *
  * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
  * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
- * failure that survived every structural test of the tree.
+ * failure that survives every structural test of a tree.
  *
- * Writes the intersector's view of each leaf's triangle so the host can compare it against the box
- * the tree is carrying.
+ * Writes the intersector's view of each triangle, by triangle id, so the host can hold it against the
+ * slot of the tree that names it.
  *
  * @type {ComputeShader}
  */

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAmBA,2CAA4C;AAE5C;;;;GAIG;AACH,yCAFU,YAAY,CAmBE;AA8DxB;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;6BA7G0B,4CAA4C;8BAd3C,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAkBA,2CAA4C;AAE5C;;;;;;GAMG;AACH,wCAFU,MAAM,CAEyD;AAEzE;;GAEG;AACH,yCAFU,YAAY,CAWE;AAgExB;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,aAAa,CAMpB;6BA3H0B,4CAA4C;8BAE3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js

@@ -1,127 +1,126 @@
-import { f32, u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    BVH_NODE_CHILD_2_WORD,
-    BVH_NODE_STRIDE_WORDS
-} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import {
-    chunk_geometry_read_triangle_vertices
-} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
-import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
-
-export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
-
-/**
- * Which tree, and where it lives — one tree at a time, which is what an audit is.
- *
- * @type {WebGPUStruct}
- */
-export const BLAS_AUDIT_SETTINGS_STRUCT = WebGPUStruct.from({
-    /**
-     * Leaves in this tree — one triangle each, so also its triangle count.
-     */
-    leaf_count: u32,
-    /**
-     * u32 word the tree's node 0 starts at inside the shared node arena.
-     */
-    node_word_offset: u32,
-    /**
-     * Word this tree's leaf list starts at inside the shared leaf-node arena.
-     */
-    leaf_nodes_offset: u32,
-    /**
-     * Row in the geometry table whose meshlets the leaves index into.
-     */
-    geometry_index: u32,
-}, "BlasAuditSettings");
-
-const resources = new ShaderResourceSetDescriptor();
-
-// per-dispatch, 16 bytes, read-only: immediate data rather than a uniform buffer
-resources.setImmediate("settings", BLAS_AUDIT_SETTINGS_STRUCT);
-resources.createGroup()
-    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
-    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
-    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
-    // six floats per leaf: the AABB of the triangle as the *intersection* path sees it
-    .addStorageBuffer("out_bounds", WebGPUArray.from(f32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
-const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
-
-@compute @workgroup_size(${BLAS_AUDIT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
-    let i = gid.x;
-
-    if (i >= settings.leaf_count) {
-        return;
-    }
-
-    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
-
-    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
-
-    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
-
-    // The reader the ray-triangle test uses, not the one the refit used. If the two ever name
-    // different triangles for one payload, the tree bounds a triangle the intersector never tests.
-    let triangle = geometry_read_triangle_vertices(
-        geometries[settings.geometry_index],
-        meshlet_triangle_id
-    );
-
-    let a = triangle.a.position;
-    let b = triangle.b.position;
-    let c = triangle.c.position;
-
-    let low = min(a, min(b, c));
-    let high = max(a, max(b, c));
-
-    let base = i * 6u;
-
-    out_bounds[base] = low.x;
-    out_bounds[base + 1u] = low.y;
-    out_bounds[base + 2u] = low.z;
-    out_bounds[base + 3u] = high.x;
-    out_bounds[base + 4u] = high.y;
-    out_bounds[base + 5u] = high.z;
-}
-`, [
-    chunk_geometry_read_triangle_vertices,
-]);
-
-/**
- * Read every leaf's triangle back through the path the *intersector* uses.
- *
- * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
- * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
- * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
- *
- * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
- * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
- * failure that survived every structural test of the tree.
- *
- * Writes the intersector's view of each leaf's triangle so the host can compare it against the box
- * the tree is carrying.
- *
- * @type {ComputeShader}
- */
-export const shader_blas_audit_leaf_triangles = ComputeShader.from({
-    label: "BLAS/AuditLeafTriangles",
-    resources,
-    body,
-});
+import { f32, u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    chunk_geometry_read_triangle_positions
+} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_positions.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import {
+    GEOMETRY_MESHLET_TRIANGLE_LIMIT
+} from "../../renderer/geometry/meshlet/GEOMETRY_MESHLET_TRIANGLE_LIMIT.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
+
+/**
+ * Triangle ids a meshlet can hold, used or not: the audit asks about every one of them, so that a
+ * thread's index says which triangle it is without a table. `(meshlet << 8) | triangle` is the id;
+ * a thread's index is `meshlet * BLAS_AUDIT_MESHLET_STRIDE + triangle`.
+ *
+ * @type {number}
+ */
+export const BLAS_AUDIT_MESHLET_STRIDE = GEOMETRY_MESHLET_TRIANGLE_LIMIT;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_AUDIT_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Meshlets of the geometry.
+     */
+    meshlet_count: u32,
+    /**
+     * Row in the geometry table whose meshlets hold the triangles.
+     */
+    geometry_index: u32,
+}, "BlasAuditSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 8 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", BLAS_AUDIT_SETTINGS_STRUCT);
+resources.createGroup()
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
+    // six floats per triangle id: the AABB of the triangle as the *intersection* path sees it, or a
+    // box turned inside out — its low above its high — for an id the meshlet does not hold
+    .addStorageBuffer("out_bounds", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const MESHLET_STRIDE = ${BLAS_AUDIT_MESHLET_STRIDE}u;
+
+@compute @workgroup_size(${BLAS_AUDIT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    let meshlet = i / MESHLET_STRIDE;
+    let triangle = i % MESHLET_STRIDE;
+
+    if (meshlet >= settings.meshlet_count) {
+        return;
+    }
+
+    let geometry = geometries[settings.geometry_index];
+
+    let base = i * 6u;
+
+    if (triangle >= meshlet_metadata[geometry.meshlets_address + meshlet].primitive_count) {
+        // not a triangle
+        out_bounds[base] = 1.0;
+        out_bounds[base + 3u] = -1.0;
+
+        return;
+    }
+
+    // The reader the ray-triangle test uses, not the one the refit used. If the two ever name
+    // different triangles for one id, the tree bounds a triangle the intersector never tests.
+    var a: vec3<f32>;
+    var b: vec3<f32>;
+    var c: vec3<f32>;
+
+    geometry_read_triangle_positions(&a, &b, &c, geometry, (meshlet << 8u) | triangle);
+
+    let low = min(a, min(b, c));
+    let high = max(a, max(b, c));
+
+    out_bounds[base] = low.x;
+    out_bounds[base + 1u] = low.y;
+    out_bounds[base + 2u] = low.z;
+    out_bounds[base + 3u] = high.x;
+    out_bounds[base + 4u] = high.y;
+    out_bounds[base + 5u] = high.z;
+}
+`, [
+    chunk_geometry_read_triangle_positions,
+]);
+
+/**
+ * Read every triangle of a geometry back through the path the *intersector* uses.
+ *
+ * The refit computes a slot's box with `geometry_read_triangle_bounds`; the ray queries fetch the
+ * triangles they test with `geometry_read_triangle_positions`. Those are two different functions over
+ * the same encoded payload.
+ *
+ * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
+ * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
+ * failure that survives every structural test of a tree.
+ *
+ * Writes the intersector's view of each triangle, by triangle id, so the host can hold it against the
+ * slot of the tree that names it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_audit_leaf_triangles = ComputeShader.from({
+    label: "BLAS/AuditLeafTriangles",
+    resources,
+    body,
+});