@woosh/meep-engine 3.0.2 → 3.2.0

package/src/engine/graphics/ecs/light/shadow/compute_view_frustum_aabb_in_space.js

@@ -1,62 +1,62 @@
-import { assert } from "../../../../../core/assert.js";
-import { frustum_compute_corners } from "../../../../../core/geom/3d/frustum/frustum_compute_corners.js";
-import {
-    frustum_from_projection_matrix_array
-} from "../../../../../core/geom/3d/frustum/frustum_from_projection_matrix_array.js";
-import { v3_matrix4_multiply } from "../../../../../core/geom/vec3/v3_matrix4_multiply.js";
-
-const scratch_planes = new Float32Array(24);
-const scratch_corners = new Float32Array(24);
-const scratch_point = new Float32Array(3);
-
-/**
- * Compute the AABB of a camera's view-frustum corners after they are projected
- * into another space (e.g. a shadow camera's local space).
- *
- * The view-projection matrix is fed to Gribb-Hartmann to extract 6 inward-facing
- * planes; the 8 corners are then solved as triple-plane intersections in world
- * space and transformed by the target-space matrix.
- *
- * @param {AABB3} result bounds in target space
- * @param {ArrayLike<number>} view_projection_matrix column-major projection * view of the source camera
- * @param {ArrayLike<number>} target_space_matrix column-major world -> target space transform
- */
-export function compute_view_frustum_aabb_in_space(
-    result,
-    view_projection_matrix,
-    target_space_matrix
-) {
-    assert.defined(result, 'result');
-    assert.isArrayLike(view_projection_matrix, 'view_projection_matrix');
-    assert.greaterThanOrEqual(view_projection_matrix.length, 16, 'view_projection_matrix.length');
-    assert.isArrayLike(target_space_matrix, 'target_space_matrix');
-    assert.greaterThanOrEqual(target_space_matrix.length, 16, 'target_space_matrix.length');
-
-    frustum_from_projection_matrix_array(scratch_planes, view_projection_matrix);
-    frustum_compute_corners(scratch_corners, 0, scratch_planes, 0);
-
-    let x0 = Number.POSITIVE_INFINITY;
-    let y0 = Number.POSITIVE_INFINITY;
-    let z0 = Number.POSITIVE_INFINITY;
-
-    let x1 = Number.NEGATIVE_INFINITY;
-    let y1 = Number.NEGATIVE_INFINITY;
-    let z1 = Number.NEGATIVE_INFINITY;
-
-    for (let i = 0; i < 8; i++) {
-        v3_matrix4_multiply(scratch_point, 0, scratch_corners, i * 3, target_space_matrix);
-
-        const x = scratch_point[0];
-        const y = scratch_point[1];
-        const z = scratch_point[2];
-
-        if (x < x0) x0 = x;
-        if (x > x1) x1 = x;
-        if (y < y0) y0 = y;
-        if (y > y1) y1 = y;
-        if (z < z0) z0 = z;
-        if (z > z1) z1 = z;
-    }
-
-    result.setBounds(x0, y0, z0, x1, y1, z1);
-}
+import { assert } from "../../../../../core/assert.js";
+import { frustum_compute_corners } from "../../../../../core/geom/3d/frustum/frustum_compute_corners.js";
+import {
+    frustum_from_projection_matrix_array
+} from "../../../../../core/geom/3d/frustum/frustum_from_projection_matrix_array.js";
+import { v3_matrix4_multiply } from "../../../../../core/geom/vec3/v3_matrix4_multiply.js";
+
+const scratch_planes = new Float32Array(24);
+const scratch_corners = new Float32Array(24);
+const scratch_point = new Float32Array(3);
+
+/**
+ * Compute the AABB of a camera's view-frustum corners after they are projected
+ * into another space (e.g. a shadow camera's local space).
+ *
+ * The view-projection matrix is fed to Gribb-Hartmann to extract 6 inward-facing
+ * planes; the 8 corners are then solved as triple-plane intersections in world
+ * space and transformed by the target-space matrix.
+ *
+ * @param {AABB3} result bounds in target space
+ * @param {ArrayLike<number>} view_projection_matrix column-major projection * view of the source camera
+ * @param {ArrayLike<number>} target_space_matrix column-major world -> target space transform
+ */
+export function compute_view_frustum_aabb_in_space(
+    result,
+    view_projection_matrix,
+    target_space_matrix
+) {
+    assert.defined(result, 'result');
+    assert.isArrayLike(view_projection_matrix, 'view_projection_matrix');
+    assert.greaterThanOrEqual(view_projection_matrix.length, 16, 'view_projection_matrix.length');
+    assert.isArrayLike(target_space_matrix, 'target_space_matrix');
+    assert.greaterThanOrEqual(target_space_matrix.length, 16, 'target_space_matrix.length');
+
+    frustum_from_projection_matrix_array(scratch_planes, view_projection_matrix);
+    frustum_compute_corners(scratch_corners, 0, scratch_planes, 0);
+
+    let x0 = Number.POSITIVE_INFINITY;
+    let y0 = Number.POSITIVE_INFINITY;
+    let z0 = Number.POSITIVE_INFINITY;
+
+    let x1 = Number.NEGATIVE_INFINITY;
+    let y1 = Number.NEGATIVE_INFINITY;
+    let z1 = Number.NEGATIVE_INFINITY;
+
+    for (let i = 0; i < 8; i++) {
+        v3_matrix4_multiply(scratch_point, 0, scratch_corners, i * 3, target_space_matrix);
+
+        const x = scratch_point[0];
+        const y = scratch_point[1];
+        const z = scratch_point[2];
+
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+        if (z < z0) z0 = z;
+        if (z > z1) z1 = z;
+    }
+
+    result.setBounds(x0, y0, z0, x1, y1, z1);
+}

package/src/engine/graphics/ecs/light/shadow/extend_shadow_camera_near_for_casters.js

@@ -1,77 +1,77 @@
-import { frustum3_matrix4_project_n } from "../../../../../core/geom/3d/frustum/frustum3_matrix4_project_n.js";
-import { frustum3_from_aabb } from "../../../../../core/geom/3d/frustum/frustum3_from_aabb.js";
-import { render_layers_compute_depth_range } from "../../render_layers_compute_depth_range.js";
-
-const scratch_local_planes = new Float32Array(24);
-const scratch_world_planes = new Float32Array(24);
-const scratch_range = { near: 0, far: 0 };
-
-// Half-extent of the z range used for the caster query. We want any object in
-// the column above the receivers regardless of how far it sits along the light
-// direction, so the query volume is effectively unbounded in z; the BVH walk's
-// AABB-vs-frustum test is happy with a wide-but-finite range and avoids
-// infinities propagating through plane math.
-const CASTER_QUERY_HALF_RANGE = 1e7;
-
-/**
- * Push the shadow camera's near plane back toward the light to include any
- * occluder whose shadow would fall within the camera's x/y bounds, even when
- * the occluder itself sits outside the main view frustum.
- *
- * Without this step the textbook "fit shadow camera to view frustum" leaves
- * the near plane at the closest receiver — a brick floating just above the
- * view frustum gets clipped out of the shadow map and casts no shadow on the
- * ground below.
- *
- * Algorithm:
- *   1. Take the shadow camera's existing left/right/top/bottom (already fit
- *      to receivers) as the x/y extents of a light-local query box. Extend z
- *      to a wide range so any caster along the light direction is captured.
- *   2. Transform the 6 box planes to world space via the shadow camera's
- *      matrixWorld.
- *   3. Walk every render layer's BVH through `compute_depth_range` against
- *      this world-space volume, measured along the shadow camera's view
- *      direction.
- *   4. If the closest depth found is smaller than the camera's current near,
- *      replace near with it.
- *
- * Far is intentionally left alone: casters behind the farthest receiver (in
- * light direction) can't shadow anything in the view.
- *
- * @param {THREE.OrthographicCamera} shadow_camera
- * @param {RenderLayerManager} layers
- */
-export function extend_shadow_camera_near_for_casters(shadow_camera, layers) {
-    if (layers === null) {
-        return;
-    }
-
-    const x0 = shadow_camera.left;
-    const x1 = shadow_camera.right;
-    const y0 = shadow_camera.bottom;
-    const y1 = shadow_camera.top;
-
-    frustum3_from_aabb(
-        scratch_local_planes, 0,
-        x0, y0, -CASTER_QUERY_HALF_RANGE,
-        x1, y1, CASTER_QUERY_HALF_RANGE
-    );
-
-    frustum3_matrix4_project_n(
-        scratch_world_planes, 0,
-        scratch_local_planes, 0,
-        6,
-        shadow_camera.matrixWorld.elements
-    );
-
-    render_layers_compute_depth_range(
-        scratch_range,
-        layers,
-        scratch_world_planes,
-        shadow_camera.matrixWorld.elements
-    );
-
-    if (isFinite(scratch_range.near) && scratch_range.near < shadow_camera.near) {
-        shadow_camera.near = scratch_range.near;
-    }
-}
+import { frustum3_matrix4_project_n } from "../../../../../core/geom/3d/frustum/frustum3_matrix4_project_n.js";
+import { frustum3_from_aabb } from "../../../../../core/geom/3d/frustum/frustum3_from_aabb.js";
+import { render_layers_compute_depth_range } from "../../render_layers_compute_depth_range.js";
+
+const scratch_local_planes = new Float32Array(24);
+const scratch_world_planes = new Float32Array(24);
+const scratch_range = { near: 0, far: 0 };
+
+// Half-extent of the z range used for the caster query. We want any object in
+// the column above the receivers regardless of how far it sits along the light
+// direction, so the query volume is effectively unbounded in z; the BVH walk's
+// AABB-vs-frustum test is happy with a wide-but-finite range and avoids
+// infinities propagating through plane math.
+const CASTER_QUERY_HALF_RANGE = 1e7;
+
+/**
+ * Push the shadow camera's near plane back toward the light to include any
+ * occluder whose shadow would fall within the camera's x/y bounds, even when
+ * the occluder itself sits outside the main view frustum.
+ *
+ * Without this step the textbook "fit shadow camera to view frustum" leaves
+ * the near plane at the closest receiver — a brick floating just above the
+ * view frustum gets clipped out of the shadow map and casts no shadow on the
+ * ground below.
+ *
+ * Algorithm:
+ *   1. Take the shadow camera's existing left/right/top/bottom (already fit
+ *      to receivers) as the x/y extents of a light-local query box. Extend z
+ *      to a wide range so any caster along the light direction is captured.
+ *   2. Transform the 6 box planes to world space via the shadow camera's
+ *      matrixWorld.
+ *   3. Walk every render layer's BVH through `compute_depth_range` against
+ *      this world-space volume, measured along the shadow camera's view
+ *      direction.
+ *   4. If the closest depth found is smaller than the camera's current near,
+ *      replace near with it.
+ *
+ * Far is intentionally left alone: casters behind the farthest receiver (in
+ * light direction) can't shadow anything in the view.
+ *
+ * @param {THREE.OrthographicCamera} shadow_camera
+ * @param {RenderLayerManager} layers
+ */
+export function extend_shadow_camera_near_for_casters(shadow_camera, layers) {
+    if (layers === null) {
+        return;
+    }
+
+    const x0 = shadow_camera.left;
+    const x1 = shadow_camera.right;
+    const y0 = shadow_camera.bottom;
+    const y1 = shadow_camera.top;
+
+    frustum3_from_aabb(
+        scratch_local_planes, 0,
+        x0, y0, -CASTER_QUERY_HALF_RANGE,
+        x1, y1, CASTER_QUERY_HALF_RANGE
+    );
+
+    frustum3_matrix4_project_n(
+        scratch_world_planes, 0,
+        scratch_local_planes, 0,
+        6,
+        shadow_camera.matrixWorld.elements
+    );
+
+    render_layers_compute_depth_range(
+        scratch_range,
+        layers,
+        scratch_world_planes,
+        shadow_camera.matrixWorld.elements
+    );
+
+    if (isFinite(scratch_range.near) && scratch_range.near < shadow_camera.near) {
+        shadow_camera.near = scratch_range.near;
+    }
+}

package/src/engine/graphics/ecs/make_bvh_depth_range_computer.js

@@ -1,33 +1,33 @@
-import { assert } from "../../../core/assert.js";
-import {
-    bvh_query_depth_range_in_frustum
-} from "../../../core/bvh2/bvh3/query/bvh_query_depth_range_in_frustum.js";
-
-/**
- * Build the `RenderLayer.compute_depth_range` hook for a layer whose contents
- * are indexed by a BVH.
- *
- * WHY THIS EXISTS
- *
- * Every renderable system wrote the same four lines into its `startup` —
- * capture `this.bvh` into a local, then assign a six-argument arrow that
- * forwards straight to `bvh_query_depth_range_in_frustum`. `MeshSystem`,
- * `ShadedGeometrySystem`, `Trail2DSystem`, `Trail3DSystem`, `WaterSystem`,
- * `ParticleEmitterSystem` and `engine/ecs/renderable/RenderSystem` all carried a
- * byte-identical copy. The sibling half of the same chore,
- * `make_bvh_visibility_builder`, was already factored out; this is the other
- * half.
- *
- * The returned function runs once per camera per frame, not per object, and
- * adds one call frame in front of a BVH walk — its own cost is not measurable.
- *
- * @param {BVH|BinaryUint32BVH} bvh spatial index holding the layer's content
- * @returns {(result: {near: number, far: number}, frustum: Float32Array, nx: number, ny: number, nz: number, plane_constant: number) => void}
- */
-export function make_bvh_depth_range_computer(bvh) {
-    assert.defined(bvh, 'bvh');
-
-    return (result, frustum, nx, ny, nz, plane_constant) => {
-        bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, plane_constant);
-    };
-}
+import { assert } from "../../../core/assert.js";
+import {
+    bvh_query_depth_range_in_frustum
+} from "../../../core/bvh2/bvh3/query/bvh_query_depth_range_in_frustum.js";
+
+/**
+ * Build the `RenderLayer.compute_depth_range` hook for a layer whose contents
+ * are indexed by a BVH.
+ *
+ * WHY THIS EXISTS
+ *
+ * Every renderable system wrote the same four lines into its `startup` —
+ * capture `this.bvh` into a local, then assign a six-argument arrow that
+ * forwards straight to `bvh_query_depth_range_in_frustum`. `MeshSystem`,
+ * `ShadedGeometrySystem`, `Trail2DSystem`, `Trail3DSystem`, `WaterSystem`,
+ * `ParticleEmitterSystem` and `engine/ecs/renderable/RenderSystem` all carried a
+ * byte-identical copy. The sibling half of the same chore,
+ * `make_bvh_visibility_builder`, was already factored out; this is the other
+ * half.
+ *
+ * The returned function runs once per camera per frame, not per object, and
+ * adds one call frame in front of a BVH walk — its own cost is not measurable.
+ *
+ * @param {BVH|BinaryUint32BVH} bvh spatial index holding the layer's content
+ * @returns {(result: {near: number, far: number}, frustum: Float32Array, nx: number, ny: number, nz: number, plane_constant: number) => void}
+ */
+export function make_bvh_depth_range_computer(bvh) {
+    assert.defined(bvh, 'bvh');
+
+    return (result, frustum, nx, ny, nz, plane_constant) => {
+        bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, plane_constant);
+    };
+}

package/src/engine/graphics/ecs/mesh-v2/DeferredBoundsQueue.js

@@ -1,88 +1,88 @@
-/**
- * Collects {@link ShadedGeometry} components whose bounding box has gone stale under
- * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, until the owner of the BVH is ready
- * to take the updates.
- *
- * WHY THIS EXISTS
- *
- * A {@link Transform} signals `position`, `rotation` and `scale` separately, so one
- * logical move produces several change notifications: two when a caller sets position
- * and rotation, three when the transform is written as a matrix (which is what
- * {@link TransformAttachmentSystem} does for every entity in a hierarchy, and what
- * `Transform.copy` does). Updating bounds on each of those recomputes the same box and
- * walks the same path to the BVH root several times over. Parking the component here
- * instead collapses the batch into one update per component per flush.
- *
- * Entries are appended without a membership test; {@link ShadedGeometry} carries the
- * "already queued" bit so enqueueing stays O(1) and a component appears at most once.
- */
-export class DeferredBoundsQueue {
-    /**
-     * Retained between flushes and overwritten in place rather than re-allocated.
-     * Only the first {@link #size} entries are live.
-     * @type {ShadedGeometry[]}
-     */
-    #items = [];
-
-    /**
-     * @type {number}
-     */
-    #size = 0;
-
-    /**
-     * Number of components waiting for their bounds to be applied.
-     * @returns {number}
-     */
-    get size() {
-        return this.#size;
-    }
-
-    /**
-     * Park a component whose bounds have gone stale.
-     *
-     * The caller must not add a component that is already queued — see
-     * {@link ShadedGeometry.updateTransform}, which owns that bit.
-     * @param {ShadedGeometry} sg
-     * @returns {void}
-     */
-    add(sg) {
-        this.#items[this.#size++] = sg;
-    }
-
-    /**
-     * Apply every parked update, leaving the BVH consistent with the current transforms.
-     *
-     * Components that were unlinked while queued, or whose bounds were already settled by
-     * a read, are skipped.
-     *
-     * Must not be re-entered: nothing reached from here writes to a {@link Transform},
-     * so no component can go dirty while the batch is being applied.
-     * @returns {number} how many components actually had an update applied, which is a
-     * useful profiling signal — it is the number of BVH refits the batch cost
-     */
-    flush() {
-        const items = this.#items;
-        const size = this.#size;
-
-        let applied = 0;
-
-        for (let i = 0; i < size; i++) {
-            if (items[i].applyDeferredBoundsUpdate()) {
-                applied++;
-            }
-        }
-
-        // Drop the references so components unlinked while queued are not held alive
-        // until their slot happens to be overwritten — after a teardown the slots may
-        // never be reused, and each entry retains a geometry and a material.
-        //
-        // Done in one sweep rather than per entry inside the loop above: clearing each
-        // slot as it was consumed measured ~25% slower per tick on a 2000-mover scene,
-        // the store into the object array carrying a GC write barrier each time.
-        items.fill(null, 0, size);
-
-        this.#size = 0;
-
-        return applied;
-    }
-}
+/**
+ * Collects {@link ShadedGeometry} components whose bounding box has gone stale under
+ * {@link ShadedGeometryFlags.DeferredBoundsUpdate}, until the owner of the BVH is ready
+ * to take the updates.
+ *
+ * WHY THIS EXISTS
+ *
+ * A {@link Transform} signals `position`, `rotation` and `scale` separately, so one
+ * logical move produces several change notifications: two when a caller sets position
+ * and rotation, three when the transform is written as a matrix (which is what
+ * {@link TransformAttachmentSystem} does for every entity in a hierarchy, and what
+ * `Transform.copy` does). Updating bounds on each of those recomputes the same box and
+ * walks the same path to the BVH root several times over. Parking the component here
+ * instead collapses the batch into one update per component per flush.
+ *
+ * Entries are appended without a membership test; {@link ShadedGeometry} carries the
+ * "already queued" bit so enqueueing stays O(1) and a component appears at most once.
+ */
+export class DeferredBoundsQueue {
+    /**
+     * Retained between flushes and overwritten in place rather than re-allocated.
+     * Only the first {@link #size} entries are live.
+     * @type {ShadedGeometry[]}
+     */
+    #items = [];
+
+    /**
+     * @type {number}
+     */
+    #size = 0;
+
+    /**
+     * Number of components waiting for their bounds to be applied.
+     * @returns {number}
+     */
+    get size() {
+        return this.#size;
+    }
+
+    /**
+     * Park a component whose bounds have gone stale.
+     *
+     * The caller must not add a component that is already queued — see
+     * {@link ShadedGeometry.updateTransform}, which owns that bit.
+     * @param {ShadedGeometry} sg
+     * @returns {void}
+     */
+    add(sg) {
+        this.#items[this.#size++] = sg;
+    }
+
+    /**
+     * Apply every parked update, leaving the BVH consistent with the current transforms.
+     *
+     * Components that were unlinked while queued, or whose bounds were already settled by
+     * a read, are skipped.
+     *
+     * Must not be re-entered: nothing reached from here writes to a {@link Transform},
+     * so no component can go dirty while the batch is being applied.
+     * @returns {number} how many components actually had an update applied, which is a
+     * useful profiling signal — it is the number of BVH refits the batch cost
+     */
+    flush() {
+        const items = this.#items;
+        const size = this.#size;
+
+        let applied = 0;
+
+        for (let i = 0; i < size; i++) {
+            if (items[i].applyDeferredBoundsUpdate()) {
+                applied++;
+            }
+        }
+
+        // Drop the references so components unlinked while queued are not held alive
+        // until their slot happens to be overwritten — after a teardown the slots may
+        // never be reused, and each entry retains a geometry and a material.
+        //
+        // Done in one sweep rather than per entry inside the loop above: clearing each
+        // slot as it was consumed measured ~25% slower per tick on a 2000-mover scene,
+        // the store into the object array carrying a GC write barrier each time.
+        items.fill(null, 0, size);
+
+        this.#size = 0;
+
+        return applied;
+    }
+}