@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/scene/movers/shader_scene_skinned_movers.js

@@ -0,0 +1,112 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { SKINNING_BINDING_STRUCT } from "../../animation/skinning/SKINNING_BINDING_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { chunk_scene_database_access } from "../chunk_scene_database_access.js";
+import { chunk_scene_append_mover } from "./chunk_scene_append_mover.js";
+import { SCENE_MOVERS_STRUCT } from "./SCENE_MOVER_LAYOUT.js";
+
+export const SCENE_SKINNED_MOVERS_WORKGROUP_SIZE = 64;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const SCENE_SKINNED_MOVERS_SETTINGS_STRUCT = WebGPUStruct.from({
+    binding_count: u32,
+    capacity: u32,
+}, "SceneSkinnedMoversSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', SCENE_SKINNED_MOVERS_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('bindings', WebGPUArray.from(SKINNING_BINDING_STRUCT), false)
+    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('prev_skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('movers', SCENE_MOVERS_STRUCT, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const LANES = ${SCENE_SKINNED_MOVERS_WORKGROUP_SIZE}u;
+
+// set by the first lane to find a joint that moved: that lane alone lists the mesh
+var<workgroup> claimed: atomic<u32>;
+
+fn scene_matrix_differs(a: mat4x4f, b: mat4x4f) -> bool {
+    return any(a[0] != b[0]) || any(a[1] != b[1]) || any(a[2] != b[2]) || any(a[3] != b[3]);
+}
+
+@compute @workgroup_size(${SCENE_SKINNED_MOVERS_WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let index = workgroup_id.x;
+
+    // the whole workgroup's binding, so the whole workgroup leaves
+    if (index >= settings.binding_count) {
+        return;
+    }
+
+    let binding = bindings[index];
+
+    // a lane's joints, a workgroup's width apart: as many as the skin has, over the lanes
+    var moved = false;
+
+    for (var j = lane; j < binding.skin_matrix_count; j += LANES) {
+        let row = binding.skin_matrix_offset + j;
+
+        moved = moved || scene_matrix_differs(skin_matrices[row], prev_skin_matrices[row]);
+    }
+
+    let first = moved && atomicExchange(&claimed, 1u) == 0u;
+
+    var box_min = vec3f(0.0);
+    var box_max = vec3f(0.0);
+
+    if (first) {
+        let mesh = scene_read_mesh(&scene_database, binding.mesh_instance_index);
+
+        box_min = vec3f(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        box_max = vec3f(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+    }
+
+    // a pose that changed is the animation's alone; a move of the mesh as well is listed by the
+    // mover pass, as any row's move is
+    scene_append_mover(first && all(box_min <= box_max), box_min, box_max, true, settings.capacity);
+}
+`, [
+    SKINNING_BINDING_STRUCT.declaration_chunk,
+    chunk_scene_database_access,
+    chunk_scene_append_mover,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * List every skinned mesh whose pose changed since last frame: a joint's skin matrix differs from
+ * the one the animation manager kept from the frame before. A pose can change inside bounds that
+ * stay put — an arm swinging inside the box its feet and head set — which neither the row's
+ * transform nor its box would show; a skin held still is no mover. Every box it lists is
+ * {@link SCENE_MOVER_POSE_ONLY}.
+ *
+ * The mesh's box is this frame's, after the bounds refresh: a pose that changed it is also caught by
+ * {@link shader_scene_movers}, with where the mesh was.
+ *
+ * One workgroup per skinning binding, its lanes over the skin's joints, after
+ * {@link shader_scene_movers} into the same list.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_scene_skinned_movers = ComputeShader.from({
+    label: "Scene/SkinnedMovers",
+    body,
+    resources,
+});

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts

@@ -108,6 +108,19 @@ export class GPUSceneRows {
      * @type {Signal<number>} the entity
      */
     onMeshReleased: any;
+    /**
+     * An entity's `meshes` row has been written: the first time, and every time what it draws was
+     * replaced ({@link attach_mesh}) — not when only its entity moved. Sent once the record is in the
+     * table, with what the record says: the entity, the geometry it draws (the source, for a row that
+     * draws a skinned clone), its material, and the {@link MESH_FLAG_SDF_WORLD} and
+     * {@link MESH_FLAG_SKINNED} bits of its `flags`.
+     *
+     * A row attached and detached between two flushes is never written, so {@link onMeshReleased}
+     * can come for an entity this never named.
+     *
+     * @type {Signal<number, MeshletGeometry, ShadeMaterial, number>} entity, geometry, material, flags
+     */
+    onMeshWritten: any;
     /**
      * Whether the entity holds a `meshes` row.
      *
@@ -120,10 +133,14 @@ export class GPUSceneRows {
      * scene's primitives on this side (a CPU bake, a verifier) iterates. The order is the order
      * the meshes were attached in.
      *
-     * @param {function(number, MeshletGeometry, ShadeMaterial, boolean): void} visitor entity,
-     *        geometry, material, whether the row draws a skinned clone
+     * The last argument is the row's `flags` as {@link onMeshWritten} sends them, worked out from
+     * what the entity asks for now: a row whose write is still pending gets the event when it is
+     * written, with the same.
+     *
+     * @param {function(number, MeshletGeometry, ShadeMaterial, boolean, number): void} visitor entity,
+     *        geometry, material, whether the row draws a skinned clone, flags
      */
-    for_each_mesh(visitor: (arg0: number, arg1: MeshletGeometry, arg2: ShadeMaterial, arg3: boolean) => void): void;
+    for_each_mesh(visitor: (arg0: number, arg1: MeshletGeometry, arg2: ShadeMaterial, arg3: boolean, arg4: number) => void): void;
     /**
      * The box around everything the rows draw, as this side can compose it: each mesh entry's
      * geometry box projected under its entity's own `Transform64` — the ECS's world pose, exact
@@ -209,14 +226,19 @@ export class GPUSceneRows {
      * against whatever skin the entity is bound to; the clone is made when the row is written and
      * given back with the row.
      *
+     * A primitive in the SDF world is seen by the rays that trace the scene's distance field, unless
+     * its material is transparent; one out of it is drawn and nothing else. See
+     * {@link MESH_FLAG_SDF_WORLD}.
+     *
      * The mesh is one hold on the `transforms` row, released by {@link detach_mesh}.
      *
      * @param {number} entity
      * @param {MeshletGeometry} geometry
      * @param {ShadeMaterial} material
      * @param {boolean} [skinned]
+     * @param {boolean} [sdf_world] in by default, as a `ShadedGeometry` is
      */
-    attach_mesh(entity: number, geometry: MeshletGeometry, material: ShadeMaterial, skinned?: boolean): void;
+    attach_mesh(entity: number, geometry: MeshletGeometry, material: ShadeMaterial, skinned?: boolean, sdf_world?: boolean): void;
     /**
      * Take the entity's `meshes` row back, and let go of the hold the mesh had on its
      * `transforms` row — which stays if anything else holds it. Safe on an entity that has none.

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA+KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,oBAA8B;IAE9B;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,MAAM,QA0ChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA4BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;OAaG;IACH,sBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IA4BD;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QAgDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAwCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAyND;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;;;;;;;;OASG;IACH,gBAgBC;;CACJ;qCA3vCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}
+{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAqMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,oBAA8B;IAE9B;;;;;;;;;;;OAWG;IACH,mBAA6B;IAE7B;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,QAAE,MAAM,KAAG,IAAI,QASjF;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,MAAM,QA0ChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA4BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;OAaG;IACH,sBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IA4BD;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBANW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,cACP,OAAO,QAkDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAwCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAgOD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;;;;;;;;OASG;IACH,gBAgBC;;CACJ;qCAjzCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}

package/src/shade/renderer/scene/rows/GPUSceneRows.js

@@ -9,7 +9,11 @@ import { m4_linear_determinant } from "../../../../core/geom/3d/mat4/m4_linear_d
 import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import { TRANSFORM64_EVENT_PLACED } from "../../../../engine/ecs/transform/TRANSFORM64_EVENT_PLACED.js";
 import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
-import { MESH_INSTANCE_METADATA_STRUCT } from "../MESH_INSTANCE_METADATA_STRUCT.js";
+import {
+    MESH_FLAG_SDF_WORLD,
+    MESH_FLAG_SKINNED,
+    MESH_INSTANCE_METADATA_STRUCT
+} from "../MESH_INSTANCE_METADATA_STRUCT.js";
 import { NODE3D_GLOBAL_FLAG_MIRRORED, NODE3D_SCENE_ID, NODE3D_STRUCT } from "../NODE3D_STRUCT.js";
 import { TransparencyMode } from "../../material/TransparencyMode.js";
 
@@ -123,6 +127,7 @@ const MESH_RECORD = {
     geometry: 0,
     material: 0,
     node: NODE3D_SCENE_ID,
+    flags: 0,
     bounding_box: UNDERIVED_BOUNDING_BOX,
     bounding_sphere: UNDERIVED_BOUNDING_SPHERE,
     lightmap_uvs: EMPTY_LIGHTMAP_CHART,
@@ -207,6 +212,14 @@ class MeshEntry {
      */
     skinned = false;
 
+    /**
+     * Whether the primitive asks to be in the SDF world. The row is, written as
+     * {@link MESH_FLAG_SDF_WORLD}, when its material is not transparent as well.
+     *
+     * @type {boolean}
+     */
+    sdf_world = true;
+
     /**
      * Whether the row has been written — and therefore whether the TLAS knows the row.
      *
@@ -223,6 +236,19 @@ class MeshEntry {
     held = null;
 }
 
+/**
+ * The `flags` word of the row an entry writes. Glass does not stop a GI ray, so a transparent row is
+ * out of the SDF world whatever it asks.
+ *
+ * @param {MeshEntry} entry
+ * @returns {number}
+ */
+function mesh_entry_flags(entry) {
+    const sdf_world = entry.sdf_world && entry.material.transparency_mode !== TransparencyMode.Transparent;
+
+    return (sdf_world ? MESH_FLAG_SDF_WORLD : 0) | (entry.skinned ? MESH_FLAG_SKINNED : 0);
+}
+
 /**
  * Entities as rows of the scene database.
  *
@@ -461,6 +487,20 @@ export class GPUSceneRows {
      */
     onMeshReleased = new Signal();
 
+    /**
+     * An entity's `meshes` row has been written: the first time, and every time what it draws was
+     * replaced ({@link attach_mesh}) — not when only its entity moved. Sent once the record is in the
+     * table, with what the record says: the entity, the geometry it draws (the source, for a row that
+     * draws a skinned clone), its material, and the {@link MESH_FLAG_SDF_WORLD} and
+     * {@link MESH_FLAG_SKINNED} bits of its `flags`.
+     *
+     * A row attached and detached between two flushes is never written, so {@link onMeshReleased}
+     * can come for an entity this never named.
+     *
+     * @type {Signal<number, MeshletGeometry, ShadeMaterial, number>} entity, geometry, material, flags
+     */
+    onMeshWritten = new Signal();
+
     /**
      * Whether the entity holds a `meshes` row.
      *
@@ -476,14 +516,18 @@ export class GPUSceneRows {
      * scene's primitives on this side (a CPU bake, a verifier) iterates. The order is the order
      * the meshes were attached in.
      *
-     * @param {function(number, MeshletGeometry, ShadeMaterial, boolean): void} visitor entity,
-     *        geometry, material, whether the row draws a skinned clone
+     * The last argument is the row's `flags` as {@link onMeshWritten} sends them, worked out from
+     * what the entity asks for now: a row whose write is still pending gets the event when it is
+     * written, with the same.
+     *
+     * @param {function(number, MeshletGeometry, ShadeMaterial, boolean, number): void} visitor entity,
+     *        geometry, material, whether the row draws a skinned clone, flags
      */
     for_each_mesh(visitor) {
         assert.isFunction(visitor, 'visitor');
 
         for (const [entity, entry] of this.#mesh_entries) {
-            visitor(entity, entry.geometry, entry.material, entry.skinned);
+            visitor(entity, entry.geometry, entry.material, entry.skinned, mesh_entry_flags(entry));
         }
     }
 
@@ -745,19 +789,25 @@ export class GPUSceneRows {
      * against whatever skin the entity is bound to; the clone is made when the row is written and
      * given back with the row.
      *
+     * A primitive in the SDF world is seen by the rays that trace the scene's distance field, unless
+     * its material is transparent; one out of it is drawn and nothing else. See
+     * {@link MESH_FLAG_SDF_WORLD}.
+     *
      * The mesh is one hold on the `transforms` row, released by {@link detach_mesh}.
      *
      * @param {number} entity
      * @param {MeshletGeometry} geometry
      * @param {ShadeMaterial} material
      * @param {boolean} [skinned]
+     * @param {boolean} [sdf_world] in by default, as a `ShadedGeometry` is
      */
-    attach_mesh(entity, geometry, material, skinned = false) {
+    attach_mesh(entity, geometry, material, skinned = false, sdf_world = true) {
         assert.isNonNegativeInteger(entity, 'entity');
         assert.defined(geometry, 'geometry');
         assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
         assert.defined(material, 'material');
         assert.isBoolean(skinned, 'skinned');
+        assert.isBoolean(sdf_world, 'sdf_world');
 
         if (geometry.isVirtualGeometry === true
             && material.transparency_mode !== TransparencyMode.Opaque) {
@@ -796,6 +846,7 @@ export class GPUSceneRows {
         entry.geometry = geometry;
         entry.material = material;
         entry.skinned = skinned;
+        entry.sdf_world = sdf_world;
 
         this.#mark(entity, MARK_MESH);
     }
@@ -1037,11 +1088,16 @@ export class GPUSceneRows {
             entry.held = entry.material;
         }
 
+        const material = entry.material;
+
+        const flags = mesh_entry_flags(entry);
+
         MESH_RECORD.geometry = entry.skinned
             ? this.#skinning().obtain_clone(entity, geometry).index
             : this.#geometries.getAddress(geometry);
-        MESH_RECORD.material = entry.material.id;
+        MESH_RECORD.material = material.id;
         MESH_RECORD.node = row;
+        MESH_RECORD.flags = flags;
 
         this.#meshes.set_record(row, MESH_RECORD, MESH_RECORD_WRITER);
 
@@ -1055,6 +1111,8 @@ export class GPUSceneRows {
             this.#mesh_rows_version++;
         }
 
+        this.onMeshWritten.send4(entity, geometry, material, flags);
+
         return 1;
     }
 

package/src/shade/renderer/shader/chunk/geometry/aabb3/chunk_aabb3_nearest_point_on_surface.js

@@ -9,7 +9,7 @@ fn aabb3_nearest_point_on_surface(
     p: vec3<f32>
 ) -> vec3<f32>{
     // clamp the reference to the box; for exterior points this is already the nearest surface point
-    // (mirrors the engine CPU twin: core/geom/3d/aabb/aabb3_nearest_point_on_surface.js)
+    // (mirrors the engine CPU twin: core/geom/3d/aabb/aabb3_closest_point_on_surface.js)
     let c = clamp(p, aabb_min, aabb_max);
 
     if (any(c != p)) {

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_decompose_transform.d.ts

@@ -2,7 +2,7 @@
  * Inverse of {@link chunk_mat4_compose_transform}: split a TRS matrix into its
  * translation, rotation (quaternion) and scale components.
  *
- * Ported from meep's `decompose_matrix_4_array`. Per-component writes to the
+ * Ported from meep's `m4_decompose`. Per-component writes to the
  * deref'd output pointers are intentional — the emulator used by unit tests
  * models `*ptr = X` as a local rebind, but indexed/component writes mutate
  * the underlying typed array.

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_decompose_transform.js

@@ -4,7 +4,7 @@ import { CodeChunk } from "../../../compiler/CodeChunk.js";
  * Inverse of {@link chunk_mat4_compose_transform}: split a TRS matrix into its
  * translation, rotation (quaternion) and scale components.
  *
- * Ported from meep's `decompose_matrix_4_array`. Per-component writes to the
+ * Ported from meep's `m4_decompose`. Per-component writes to the
  * deref'd output pointers are intentional — the emulator used by unit tests
  * models `*ptr = X` as a local rebind, but indexed/component writes mutate
  * the underlying typed array.
@@ -26,7 +26,7 @@ fn mat4_decompose_transform(
     let scale_y = length(col1);
     let scale_z = length(col2);
 
-    // Match decompose_matrix_4_array: when a column has zero length we substitute a
+    // Match m4_decompose: when a column has zero length we substitute a
     // very large reciprocal so the rotation extraction stays finite (inexact, but
     // doesn't poison downstream NaNs).
     let is1 = select(1e7, 1.0 / scale_x, scale_x != 0.0);

package/src/shade/renderer/shader/chunk/geometry/quaternion/chunk_quat_decode_u32.d.ts

@@ -1,6 +1,6 @@
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
- * see meep code {@link quat_decode_from_uint32}
+ * see meep code {@link quat3_decode_from_uint32}
  * @type {CodeChunk}
  */
 export const chunk_quat_decode_u32: CodeChunk;

package/src/shade/renderer/shader/chunk/geometry/quaternion/chunk_quat_decode_u32.js

@@ -3,7 +3,7 @@ import { SQRT1_2_DECLARATION } from "../../math/SQRT1_2_DECLARATION.js";
 
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
- * see meep code {@link quat_decode_from_uint32}
+ * see meep code {@link quat3_decode_from_uint32}
  * @type {CodeChunk}
  */
 export const chunk_quat_decode_u32 = CodeChunk.from(

package/src/shade/renderer/shader/chunk/geometry/quaternion/chunk_quat_encode_u32.d.ts

@@ -1,6 +1,6 @@
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
- * see meep code {@link quat_encode_to_uint32}
+ * see meep code {@link quat3_encode_to_uint32}
  * @type {CodeChunk}
  */
 export const chunk_quat_encode_u32: CodeChunk;

package/src/shade/renderer/shader/chunk/geometry/quaternion/chunk_quat_encode_u32.js

@@ -4,7 +4,7 @@ import { chunk_v4_max_axis } from "../vec4/chunk_v4_max_axis.js";
 
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
- * see meep code {@link quat_encode_to_uint32}
+ * see meep code {@link quat3_encode_to_uint32}
  * @type {CodeChunk}
  */
 export const chunk_quat_encode_u32 = CodeChunk.from(

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_mat2x4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sample_discrete_wrs_mat2x4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_mat2x4.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,+CAFU,SAAS,CA6FlB;0BApGyB,gCAAgC"}
+{"version":3,"file":"chunk_sample_discrete_wrs_mat2x4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_mat2x4.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,+CAFU,SAAS,CAgGlB;0BAvGyB,gCAAgC"}

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_mat2x4.js

@@ -18,12 +18,15 @@ fn sample_discrete_wrs_mat2x4(
     var selected_idx = 0;
     var sum_wt = weights[0].x; // Start with first weight
 
+    // while every weight so far is zero so is the sum, and its share would be NaN, which would turn the
+    // noise to NaN and leave the first item drawn whatever its weight: such a step takes nothing
+
     // Note: The loop effectively starts checking from the second item (index 1),
     // because the first item (index 0) initializes the reservoir.
     
     // Check index 1
     sum_wt += weights[0].y;
-    var p = weights[0].y / sum_wt;
+    var p = select(0.0, weights[0].y / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 1;
         *u = *u / p;
@@ -33,7 +36,7 @@ fn sample_discrete_wrs_mat2x4(
 
     // Check index 2
     sum_wt += weights[0].z;
-    p = weights[0].z / sum_wt;
+    p = select(0.0, weights[0].z / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 2;
         *u = *u / p;
@@ -43,7 +46,7 @@ fn sample_discrete_wrs_mat2x4(
 
     // Check index 3
     sum_wt += weights[0].w;
-    p = weights[0].w / sum_wt;
+    p = select(0.0, weights[0].w / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 3;
         *u = *u / p;
@@ -57,7 +60,7 @@ fn sample_discrete_wrs_mat2x4(
     
     // Check index 4
     sum_wt += weights[1].x;
-    p = weights[1].x / sum_wt;
+    p = select(0.0, weights[1].x / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 4;
         *u = *u / p;
@@ -67,7 +70,7 @@ fn sample_discrete_wrs_mat2x4(
     
     // Check index 5
     sum_wt += weights[1].y;
-    p = weights[1].y / sum_wt;
+    p = select(0.0, weights[1].y / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 5;
         *u = *u / p;
@@ -77,7 +80,7 @@ fn sample_discrete_wrs_mat2x4(
 
     // Check index 6
     sum_wt += weights[1].z;
-    p = weights[1].z / sum_wt;
+    p = select(0.0, weights[1].z / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 6;
         *u = *u / p;
@@ -87,7 +90,7 @@ fn sample_discrete_wrs_mat2x4(
 
     // Check index 7
     sum_wt += weights[1].w;
-    p = weights[1].w / sum_wt;
+    p = select(0.0, weights[1].w / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 7;
         *u = *u / p;

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_vec4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sample_discrete_wrs_vec4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_vec4.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,6CAFU,SAAS,CA8ClB;0BArDyB,gCAAgC"}
+{"version":3,"file":"chunk_sample_discrete_wrs_vec4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_vec4.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,6CAFU,SAAS,CAiDlB;0BAxDyB,gCAAgC"}

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_sample_discrete_wrs_vec4.js

@@ -15,12 +15,15 @@ fn sample_discrete_wrs_vec4(weights: vec4<f32>, u: ptr<function,f32>) -> i32 {
     var selected_idx = 0;
     var sum_wt = weights.x; // Start with first weight
 
+    // while every weight so far is zero so is the sum, and its share would be NaN, which would turn the
+    // noise to NaN and leave the first item drawn whatever its weight: such a step takes nothing
+
     // Note: The loop effectively starts checking from the second item (index 1),
     // because the first item (index 0) initializes the reservoir.
     
     // Check index 1
     sum_wt += weights.y;
-    var p = weights.y / sum_wt;
+    var p = select(0.0, weights.y / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 1;
         *u = *u / p;
@@ -30,7 +33,7 @@ fn sample_discrete_wrs_vec4(weights: vec4<f32>, u: ptr<function,f32>) -> i32 {
 
     // Check index 2
     sum_wt += weights.z;
-    p = weights.z / sum_wt;
+    p = select(0.0, weights.z / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 2;
         *u = *u / p;
@@ -40,7 +43,7 @@ fn sample_discrete_wrs_vec4(weights: vec4<f32>, u: ptr<function,f32>) -> i32 {
 
     // Check index 3
     sum_wt += weights.w;
-    p = weights.w / sum_wt;
+    p = select(0.0, weights.w / sum_wt, sum_wt > 0.0);
     if (*u < p) {
         selected_idx = 3;
         *u = *u / p;

package/src/shade/renderer/shader/chunk/sdf/chunk_scene_sdf_raymarch.d.ts

@@ -1,3 +1,25 @@
+/**
+ * The nearest hit of a ray through the meshes' fields, and the `meshes` row it is on:
+ *
+ * ```wgsl
+ * fn scene_sdf_raymarch_hit(ray: Ray) -> SceneSDFHit // t = F32_MAX for none
+ * ```
+ *
+ * The TLAS is walked nearest box first; in every instance it meets, the ray marches that geometry's
+ * sparse field at level 0 in its local space, whose t is the world one.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_scene_sdf_raymarch_hit: CodeChunk;
+/**
+ * {@link chunk_scene_sdf_raymarch_hit}'s distance alone:
+ *
+ * ```wgsl
+ * fn scene_sdf_raymarch(ray: Ray) -> f32 // F32_MAX for no hit
+ * ```
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_scene_sdf_raymarch: CodeChunk;
 import { CodeChunk } from "../../compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_scene_sdf_raymarch.d.ts.map

package/src/shade/renderer/shader/chunk/sdf/chunk_scene_sdf_raymarch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_scene_sdf_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/sdf/chunk_scene_sdf_raymarch.js"],"names":[],"mappings":"AAkBA,iDAiGE;0BAjHwB,6BAA6B"}
+{"version":3,"file":"chunk_scene_sdf_raymarch.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/sdf/chunk_scene_sdf_raymarch.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH,2CAFU,SAAS,CAiGjB;AAEF;;;;;;;;GAQG;AACH,uCAFU,SAAS,CAYjB;0BA5IwB,6BAA6B"}