@woosh/meep-engine 3.3.0 → 3.4.0

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

@@ -1,39 +1,87 @@
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-import { chunk_max4 } from "../../math/chunk_max4.js";
-import { chunk_min4 } from "../../math/chunk_min4.js";
-
-/**
- * Tests Ray/AABB intersection
- * `ray_direction_inverse` is `1.0 / ray_direction`
- * @see https://github.com/microsoft/DirectX-Graphics-Samples/blob/7aa24663f26e547a5bc437db028dfcfdb4b3c8f3/Libraries/D3D12RaytracingFallback/src/TraverseFunction.hlsli#L174
- * @type {CodeChunk}
- */
-export const chunk_aabb3_intersects_ray = CodeChunk.from(
-    //language=WGSL
-    `
-fn aabb3_intersects_ray(
-    bounds:array<f32, 6>,
-    ray_origin:vec3<f32>,
-    ray_direction_inverse:vec3<f32>,
-    max_distance: f32,
-) -> bool{
-    let aabb_min = vec3(bounds[0], bounds[1], bounds[2]);
-    let aabb_max = vec3(bounds[3], bounds[4], bounds[5]);
-
-    // move aabb into ray space
-    let t0 = (aabb_min - ray_origin) * ray_direction_inverse;
-    let t1 = (aabb_max - ray_origin) * ray_direction_inverse;
-    
-    let tmin = min(t0, t1);
-    let tmax = max(t0, t1);
-    
-    let hit_max = min4(max_distance, tmax.x, tmax.y, tmax.z);
-    let hit_min = max4(0.0, tmin.x, tmin.y, tmin.z);
-    
-    return hit_max >= hit_min;
-
-}`, [
-        chunk_max4,
-        chunk_min4,
-    ]);
-
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { F32_MAX_DEFINITION } from "../../math/F32_MAX_DEFINITION.js";
+import { chunk_max4 } from "../../math/chunk_max4.js";
+import { chunk_min4 } from "../../math/chunk_min4.js";
+
+/**
+ * The distances at which a ray enters and leaves one slab, as `(near, far)`.
+ *
+ * `low` and `high` are the slab's two planes relative to the ray origin, and `inverse_direction` is
+ * the reciprocal of the ray's direction on this axis.
+ *
+ * The reciprocal is infinite when the direction component is exactly zero, and `low` or `high` is
+ * exactly zero when the origin sits exactly on one of the planes. Multiplying those together is
+ * `0 * inf`, which is NaN — and WGSL leaves `min` and `max` **indeterminate** when either operand
+ * is NaN, so the axis then contributes a value the shader cannot predict and the caller's
+ * comparison answers whichever way it fell. Measured on the CPU emulator as an asymmetry: a ray
+ * running along the slab's low plane came back a hit and the same ray along its high plane a miss.
+ *
+ * That arrangement is not exotic. It is what a ray travelling parallel to a flat surface meets, and
+ * bounds fitted exactly to flat geometry put a box face in the plane of that surface — so a bounce
+ * or shadow ray leaving one, and any axis-aligned probe ray, lands on it.
+ *
+ * Handling the parallel case on its own terms keeps the NaN from being formed rather than hoping
+ * `min`/`max` discard it. A ray parallel to a slab never crosses either plane: it is inside the slab
+ * for its whole length or outside it for its whole length, which is what the origin's own position
+ * says. The two returns are the same open and empty intervals the finite path produces, written as
+ * the largest finite float so nothing downstream has to reason about infinities either.
+ *
+ * @type {CodeChunk}
+ */
+const chunk_aabb3_slab_span = CodeChunk.from(
+    //language=WGSL
+    `
+fn aabb3_slab_span(low: f32, high: f32, inverse_direction: f32) -> vec2<f32> {
+    if (abs(inverse_direction) > F32_MAX) {
+        // parallel to this slab — inside it forever, or outside it forever
+        if (low <= 0.0 && high >= 0.0) {
+            return vec2(-F32_MAX, F32_MAX);
+        }
+
+        return vec2(F32_MAX, -F32_MAX);
+    }
+
+    let t0 = low * inverse_direction;
+    let t1 = high * inverse_direction;
+
+    return vec2(min(t0, t1), max(t0, t1));
+}`, [
+        F32_MAX_DEFINITION,
+    ]);
+
+/**
+ * Tests Ray/AABB intersection
+ * `ray_direction_inverse` is `1.0 / ray_direction`
+ * @see https://github.com/microsoft/DirectX-Graphics-Samples/blob/7aa24663f26e547a5bc437db028dfcfdb4b3c8f3/Libraries/D3D12RaytracingFallback/src/TraverseFunction.hlsli#L174
+ * @type {CodeChunk}
+ */
+export const chunk_aabb3_intersects_ray = CodeChunk.from(
+    //language=WGSL
+    `
+fn aabb3_intersects_ray(
+    bounds:array<f32, 6>,
+    ray_origin:vec3<f32>,
+    ray_direction_inverse:vec3<f32>,
+    max_distance: f32,
+) -> bool{
+    let aabb_min = vec3(bounds[0], bounds[1], bounds[2]);
+    let aabb_max = vec3(bounds[3], bounds[4], bounds[5]);
+
+    // move aabb into ray space
+    let low = aabb_min - ray_origin;
+    let high = aabb_max - ray_origin;
+
+    let span_x = aabb3_slab_span(low.x, high.x, ray_direction_inverse.x);
+    let span_y = aabb3_slab_span(low.y, high.y, ray_direction_inverse.y);
+    let span_z = aabb3_slab_span(low.z, high.z, ray_direction_inverse.z);
+
+    let hit_max = min4(max_distance, span_x.y, span_y.y, span_z.y);
+    let hit_min = max4(0.0, span_x.x, span_y.x, span_z.x);
+
+    return hit_max >= hit_min;
+
+}`, [
+        chunk_aabb3_slab_span,
+        chunk_max4,
+        chunk_min4,
+    ]);

package/src/shade/renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The AABB of the triangle a BLAS leaf names.
+ *
+ * `meshlet_triangle_id` is the leaf's `child_2` verbatim — `(meshlet << 8) | triangle`, the payload
+ * encoding that is serialized to disk with geometry. Taking it straight off the node is what lets a
+ * refit pass work without any side table saying which triangle each leaf holds: the tree already
+ * says so.
+ *
+ * The geometry-level counterpart of {@link chunk_read_meshlet_triangle_bounds}, and the same shape
+ * as {@link chunk_geometry_read_triangle_vertices} beside it — meshlet ids in a leaf payload are
+ * local to the geometry, and `meshlets_address` is what makes them global.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_geometry_read_triangle_bounds: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_geometry_read_triangle_bounds.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_geometry_read_triangle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,kDAFU,SAAS,CAqBhB;0BArCuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.js

@@ -0,0 +1,40 @@
+import { GEOMETRY_METADATA_STRUCT } from "../../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { AABB3_STRUCT } from "../aabb3/AABB3_STRUCT.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_decode_meshlet_element } from "../meshlet/chunk_decode_meshlet_element.js";
+import { chunk_read_meshlet_triangle_bounds } from "../meshlet/chunk_read_meshlet_triangle_bounds.js";
+
+/**
+ * The AABB of the triangle a BLAS leaf names.
+ *
+ * `meshlet_triangle_id` is the leaf's `child_2` verbatim — `(meshlet << 8) | triangle`, the payload
+ * encoding that is serialized to disk with geometry. Taking it straight off the node is what lets a
+ * refit pass work without any side table saying which triangle each leaf holds: the tree already
+ * says so.
+ *
+ * The geometry-level counterpart of {@link chunk_read_meshlet_triangle_bounds}, and the same shape
+ * as {@link chunk_geometry_read_triangle_vertices} beside it — meshlet ids in a leaf payload are
+ * local to the geometry, and `meshlets_address` is what makes them global.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_geometry_read_triangle_bounds = CodeChunk.from(
+    //language=WGSL
+    `
+fn geometry_read_triangle_bounds(
+    geometry: ${GEOMETRY_METADATA_STRUCT.wgsl_ref},
+    meshlet_triangle_id: u32,
+) -> ${AABB3_STRUCT.wgsl_ref} {
+    let decoded = decode_meshlet_element(meshlet_triangle_id);
+
+    return read_meshlet_triangle_bounds(
+        geometry.meshlets_address + decoded[0],
+        decoded[1]
+    );
+}
+`, [
+    GEOMETRY_METADATA_STRUCT.declaration_chunk,
+    AABB3_STRUCT.declaration_chunk,
+    chunk_decode_meshlet_element,
+    chunk_read_meshlet_triangle_bounds,
+]);

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The AABB of one triangle of a meshlet, from positions alone.
+ *
+ * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
+ * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A bounds pass wants
+ * none of that, and runs over every triangle of a deformed mesh every frame, so it reads the three
+ * positions and stops. The index addressing, the attribute-section offset and the vertex clamp are
+ * the shared chunks either way, which is where a disagreement between the two would actually hurt:
+ * bounds that do not contain the triangle the ray query goes on to intersect.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_read_meshlet_triangle_bounds: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_read_meshlet_triangle_bounds.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_read_meshlet_triangle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,iDAFU,SAAS,CAkChB;0BAjDuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_bounds.js

@@ -0,0 +1,52 @@
+import { AABB3_STRUCT } from "../aabb3/AABB3_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_meshlet_compute_attribute_section_offset } from "./chunk_meshlet_compute_attribute_section_offset.js";
+import { chunk_read_meshlet_attribute_vec3f } from "./chunk_read_meshlet_attribute_vec3f.js";
+import { chunk_read_meshlet_resolved_index } from "./chunk_read_meshlet_resolved_index.js";
+
+/**
+ * The AABB of one triangle of a meshlet, from positions alone.
+ *
+ * {@link chunk_read_meshlet_triangle_vertices} answers the same addressing question and then decodes
+ * every attribute a shaded hit needs — normal, tangent, two UV sets, colour. A bounds pass wants
+ * none of that, and runs over every triangle of a deformed mesh every frame, so it reads the three
+ * positions and stops. The index addressing, the attribute-section offset and the vertex clamp are
+ * the shared chunks either way, which is where a disagreement between the two would actually hurt:
+ * bounds that do not contain the triangle the ray query goes on to intersect.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_read_meshlet_triangle_bounds = CodeChunk.from(
+    //language=WGSL
+    `
+fn read_meshlet_triangle_bounds(
+    meshlet_id: u32,
+    triangle_id: u32
+) -> ${AABB3_STRUCT.wgsl_ref} {
+    let header = meshlet_metadata[meshlet_id];
+
+    let attribute_offset = meshlet_compute_attribute_section_offset(header);
+
+    let index_offset = triangle_id * 3u;
+
+    // position is the first attribute of the section, three floats per vertex
+    let a = read_meshlet_attribute_vec3f(
+        attribute_offset + min(read_meshlet_resolved_index(header, index_offset), header.vertex_count - 1u) * 3u
+    );
+    let b = read_meshlet_attribute_vec3f(
+        attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 1u), header.vertex_count - 1u) * 3u
+    );
+    let c = read_meshlet_attribute_vec3f(
+        attribute_offset + min(read_meshlet_resolved_index(header, index_offset + 2u), header.vertex_count - 1u) * 3u
+    );
+
+    return ${AABB3_STRUCT.wgsl_ref}(min(min(a, b), c), max(max(a, b), c));
+}
+`, [
+    AABB3_STRUCT.declaration_chunk,
+    MESHLET_METADATA_STRUCT.declaration_chunk,
+    chunk_meshlet_compute_attribute_section_offset,
+    chunk_read_meshlet_attribute_vec3f,
+    chunk_read_meshlet_resolved_index,
+]);

package/src/shade/renderer/shader/chunk/geometry/ray/RAY_STRUCT.d.ts

@@ -1,5 +1,14 @@
 /**
  * `tmin` is implied and is equal to 0
+ *
+ * `direction` is **unit length**, and `tmax` is therefore a *distance* rather than a multiple of
+ * the direction — the two readings coincide only while the direction is normalised, and the
+ * traversal mixes them freely: `ray_query_nearest` writes `tmax` from `distance(...)`, hands it to
+ * `aabb3_intersects_ray` as a bound on a parametric `t`, and `ray_shaded_query_occluded` subtracts
+ * a hit distance from it. Every producer normalises — `camera_ray_from_uv`, `ray_transform_m4`,
+ * and the callers sampling `sphere_fibonacci_point` — and one that did not would shorten or
+ * lengthen every reach downstream of it by its own length.
+ *
  * @type {WebGPUStruct}
  */
 export const RAY_STRUCT: WebGPUStruct;

package/src/shade/renderer/shader/chunk/geometry/ray/RAY_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RAY_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/ray/RAY_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,yBAFU,YAAY,CAMZ;6BAVmB,+BAA+B"}
+{"version":3,"file":"RAY_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/ray/RAY_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,yBAFU,YAAY,CAMZ;6BAnBmB,+BAA+B"}

package/src/shade/renderer/shader/chunk/geometry/ray/RAY_STRUCT.js

@@ -3,6 +3,15 @@ import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
 
 /**
  * `tmin` is implied and is equal to 0
+ *
+ * `direction` is **unit length**, and `tmax` is therefore a *distance* rather than a multiple of
+ * the direction — the two readings coincide only while the direction is normalised, and the
+ * traversal mixes them freely: `ray_query_nearest` writes `tmax` from `distance(...)`, hands it to
+ * `aabb3_intersects_ray` as a bound on a parametric `t`, and `ray_shaded_query_occluded` subtracts
+ * a hit distance from it. Every producer normalises — `camera_ray_from_uv`, `ray_transform_m4`,
+ * and the callers sampling `sphere_fibonacci_point` — and one that did not would shorten or
+ * lengthen every reach downstream of it by its own length.
+ *
  * @type {WebGPUStruct}
  */
 export const RAY_STRUCT = WebGPUStruct.from({

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_transform_m4.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Move a ray into the space `transform` maps into — the trip `ray_query_nearest` makes at every
+ * TLAS leaf, from world space into the instance's geometry space.
+ *
+ * `tmax` is a distance on both sides (see {@link RAY_STRUCT}), and the two spaces measure distance
+ * differently: a transform carrying a scale stretches the ray, so the same reach is a different
+ * number of units at the other end. The stretch is the length of the direction under the
+ * transform's linear part, which is what the direction has to be divided by to come out unit — so
+ * the factor is already in hand and `tmax` is scaled by it.
+ *
+ * This used to be derived by transforming the ray's far end point and measuring back to the new
+ * origin. That is the same number for an affine transform, but it is arrived at through
+ * `origin + direction * tmax`, and a primary ray carries `tmax = F32_MAX`: the far end is then a
+ * vector of order 1e38, a transform with any scale above one overflows it to infinity component by
+ * component, and a rotation mixing those infinities with opposite signs produces NaN. `tmax` then
+ * arrives in geometry space as NaN, and WGSL leaves `min`/`max` indeterminate on NaN — so the box
+ * test that gates the whole instance answers unpredictably. Scaling the number directly never
+ * forms the intermediate; the worst it does at `F32_MAX` is saturate to infinity, which the slab
+ * test already reads as "no limit".
+ */
 export const chunk_ray_transform_m4: CodeChunk;
 import { CodeChunk } from "../../../compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_ray_transform_m4.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_transform_m4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_ray_transform_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_transform_m4.js"],"names":[],"mappings":"AAKA,+CA4BE;0BAjCwB,gCAAgC"}
+{"version":3,"file":"chunk_ray_transform_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_transform_m4.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+CA2BE;0BAnDwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_transform_m4.js

@@ -1,34 +1,52 @@
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-import { chunk_v3_matrix4_project } from "../vec3/chunk_v3_matrix4_project.js";
-import { chunk_v3_matrix4_rotate } from "../vec3/chunk_v3_matrix4_rotate.js";
-import { RAY_STRUCT } from "./RAY_STRUCT.js";
-
-export const chunk_ray_transform_m4 = CodeChunk.from(
-    //language=WGSL
-    `
-fn ray_transform_m4(
-    ray: ${RAY_STRUCT.wgsl_ref},
-    transform: mat4x4<f32>
-) -> ${RAY_STRUCT.wgsl_ref} {
-
-    let ray_length = ray.tmax;
-
-    let new_origin = v3_matrix4_project( ray.origin, transform );
-    let new_direction = v3_matrix4_rotate( ray.direction, transform );
-    
-    let new_end = v3_matrix4_project( ray.origin + ray.direction * ray_length, transform );
-    
-    let new_ray_length = distance(new_end, new_origin);
-
-    return ${RAY_STRUCT.make({
-        origin: 'new_origin',
-        direction: 'new_direction',
-        tmax: 'new_ray_length'
-    })};
-}`,
-    [
-        chunk_v3_matrix4_rotate,
-        chunk_v3_matrix4_project,
-        RAY_STRUCT.declaration_chunk
-    ]
-);
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_v3_matrix4_project } from "../vec3/chunk_v3_matrix4_project.js";
+import { RAY_STRUCT } from "./RAY_STRUCT.js";
+
+/**
+ * Move a ray into the space `transform` maps into — the trip `ray_query_nearest` makes at every
+ * TLAS leaf, from world space into the instance's geometry space.
+ *
+ * `tmax` is a distance on both sides (see {@link RAY_STRUCT}), and the two spaces measure distance
+ * differently: a transform carrying a scale stretches the ray, so the same reach is a different
+ * number of units at the other end. The stretch is the length of the direction under the
+ * transform's linear part, which is what the direction has to be divided by to come out unit — so
+ * the factor is already in hand and `tmax` is scaled by it.
+ *
+ * This used to be derived by transforming the ray's far end point and measuring back to the new
+ * origin. That is the same number for an affine transform, but it is arrived at through
+ * `origin + direction * tmax`, and a primary ray carries `tmax = F32_MAX`: the far end is then a
+ * vector of order 1e38, a transform with any scale above one overflows it to infinity component by
+ * component, and a rotation mixing those infinities with opposite signs produces NaN. `tmax` then
+ * arrives in geometry space as NaN, and WGSL leaves `min`/`max` indeterminate on NaN — so the box
+ * test that gates the whole instance answers unpredictably. Scaling the number directly never
+ * forms the intermediate; the worst it does at `F32_MAX` is saturate to infinity, which the slab
+ * test already reads as "no limit".
+ */
+export const chunk_ray_transform_m4 = CodeChunk.from(
+    //language=WGSL
+    `
+fn ray_transform_m4(
+    ray: ${RAY_STRUCT.wgsl_ref},
+    transform: mat4x4<f32>
+) -> ${RAY_STRUCT.wgsl_ref} {
+
+    let new_origin = v3_matrix4_project( ray.origin, transform );
+
+    // the direction under the transform's linear part, before it is made unit again
+    let stretched = transform[0].xyz * ray.direction.x
+        + transform[1].xyz * ray.direction.y
+        + transform[2].xyz * ray.direction.z;
+
+    let stretch = length(stretched);
+
+    return ${RAY_STRUCT.make({
+        origin: 'new_origin',
+        direction: 'stretched / stretch',
+        tmax: 'ray.tmax * stretch'
+    })};
+}`,
+    [
+        chunk_v3_matrix4_project,
+        RAY_STRUCT.declaration_chunk
+    ]
+);