@woosh/meep-engine 2.78.1 → 2.80.0

package/build/meep.cjs

@@ -1980,10 +1980,15 @@ function v3_length(x, y, z) {
  * @param {number} z1
  * @returns {number}
  */
-function v3_angle_between(x0, y0, z0, x1, y1, z1) {
+function v3_angle_between(
+    x0, y0, z0,
+    x1, y1, z1
+) {
+
     const theta = v3_angle_cos_between(x0, y0, z0, x1, y1, z1);
 
     return Math.acos(theta);
+
 }
 
 /**
@@ -1994,9 +1999,13 @@ function v3_angle_between(x0, y0, z0, x1, y1, z1) {
  * @param {number} x1
  * @param {number} y1
  * @param {number} z1
- * @returns {number}
+ * @returns {number} value between -1 and 1, cosine of the angle between vectors
  */
-function v3_angle_cos_between(x0, y0, z0, x1, y1, z1){
+function v3_angle_cos_between(
+    x0, y0, z0,
+    x1, y1, z1
+) {
+
     const d = v3_dot(x0, y0, z0, x1, y1, z1);
 
     const magnitude_0 = v3_length(x0, y0, z0);
@@ -2006,10 +2015,12 @@ function v3_angle_cos_between(x0, y0, z0, x1, y1, z1){
 
     if (l === 0) {
         // collective magnitude is 0, provide arbitrary angle
+        // avoid division by 0
         return 0;
     }
 
     return clamp$1(d / l, -1, 1);
+
 }
 
 /**
@@ -2211,7 +2222,7 @@ let Vector3$1 = class Vector3 {
 
     /**
      *
-     * @param {number[]} array
+     * @param {number[]|Float32Array} array
      * @param {number} offset
      */
     readFromArray(array, offset = 0) {
@@ -2224,7 +2235,7 @@ let Vector3$1 = class Vector3 {
 
     /**
      *
-     * @param {number[]} array
+     * @param {number[]|Float32Array} array
      * @param {number} offset
      */
     writeToArray(array, offset = 0) {
@@ -4708,7 +4719,7 @@ let Quaternion$1 = class Quaternion {
      * @param {Quaternion} result
      * @param {Quaternion} from
      * @param {Quaternion} to
-     * @param {number} max_delta
+     * @param {number} max_delta in radians
      */
     static rotateTowards(result, from, to, max_delta) {
 
@@ -72960,6 +72971,7 @@ class TransformAttachment {
 
     /**
      * transform relative to the attachment target
+     * Think of it as "local transform"
      * @type {Transform}
      */
     transform = new Transform();
@@ -73573,7 +73585,10 @@ class UpdateContext {
     }
 
     update() {
-        this.transform.multiplyTransforms(this.parent_transform, this.attachment.transform);
+        this.transform.multiplyTransforms(
+            this.parent_transform,
+            this.attachment.transform
+        );
     }
 
     /**
@@ -73596,51 +73611,51 @@ class UpdateContext {
     link() {
         const t_parent = this.parent_transform;
 
-        t_parent.position.onChanged.add(this.update, this);
-        t_parent.rotation.onChanged.add(this.update, this);
-        t_parent.scale.onChanged.add(this.update, this);
+        t_parent.subscribe(this.update, this);
 
         const t_attachment = this.attachment.transform;
-        t_attachment.position.onChanged.add(this.update,this);
-        t_attachment.rotation.onChanged.add(this.update,this);
-        t_attachment.scale.onChanged.add(this.update,this);
+
+        t_attachment.subscribe(this.update, this);
     }
 
     unlink() {
         const transform = this.parent_transform;
 
-        transform.position.onChanged.remove(this.update, this);
-        transform.rotation.onChanged.remove(this.update, this);
-        transform.scale.onChanged.remove(this.update, this);
+        transform.unsubscribe(this.update, this);
 
         const t_attachment = this.attachment.transform;
-        t_attachment.position.onChanged.remove(this.update,this);
-        t_attachment.rotation.onChanged.remove(this.update,this);
-        t_attachment.scale.onChanged.remove(this.update,this);
+
+        t_attachment.unsubscribe(this.update, this);
     }
 }
 
 class TransformAttachmentSystem extends System {
+
+    /**
+     *
+     * @type {UpdateContext[]}
+     * @private
+     */
+    __contexts = [];
+
+    /**
+     *
+     * @type {UpdateContext[]}
+     * @private
+     */
+    __queue = [];
+    __queue_size = 0;
+    __queue_cursor = 0;
+
     constructor() {
         super();
 
         this.dependencies = [TransformAttachment, Transform];
 
-        /**
-         *
-         * @type {UpdateContext[]}
-         * @private
-         */
-        this.__contexts = [];
-
-        /**
-         *
-         * @type {UpdateContext[]}
-         * @private
-         */
-        this.__queue = [];
-        this.__queue_size = 0;
-        this.__queue_cursor = 0;
+        this.components_used = [
+            ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ];
     }
 
     /**
@@ -73668,6 +73683,12 @@ class TransformAttachmentSystem extends System {
         this.__queue[this.__queue_size++] = ctx;
     }
 
+    /**
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     * @private
+     */
     __dequeue_entity(entity) {
         for (let i = 0; i < this.__queue_size; i++) {
             const ctx = this.__queue[i];
@@ -73696,9 +73717,7 @@ class TransformAttachmentSystem extends System {
         ctx.entity = entity;
 
 
-        const ecd = this.entityManager.dataset;
-
-        ctx.ecd = ecd;
+        ctx.ecd = this.entityManager.dataset;
 
         if (ctx.bind_parent()) {
             this.__finalize_link(ctx);
@@ -73733,12 +73752,14 @@ class TransformAttachmentSystem extends System {
 
     update(timeDelta) {
         const step_count = min2(this.__queue_size, QUEUE_ITERATION_COUNT);
+
         for (let i = 0; i < step_count; i++) {
             const index = this.__queue_cursor % this.__queue_size;
 
             const ctx = this.__queue[index];
 
             if (ctx.bind_parent()) {
+                // parent obtained
                 this.__finalize_link(ctx);
 
                 this.__queue.splice(index, 1);
@@ -73748,6 +73769,7 @@ class TransformAttachmentSystem extends System {
                 this.__queue_cursor++;
             }
         }
+
     }
 }
 
@@ -77599,10 +77621,11 @@ class ShadedGeometrySystem extends System {
 }
 
 /**
- *
+ * Given an object and a value, find the first property with matching value and returns name of that property
+ * Useful for working with ENUM-like objects
  * @param {Object<T>} object
  * @param {T} value
- * @returns {string|undefined}
+ * @returns {string|undefined} name of the property, or undefined if property not found
  */
 function objectKeyByValue(object, value) {
     for (let i in object) {
@@ -79210,46 +79233,6 @@ Stats.Panel = function ( name, fg, bg ) {
 
 };
 
-/**
- *
- * @param {number} ax0
- * @param {number} ay0
- * @param {number} ax1
- * @param {number} ay1
- * @param {number} bx0
- * @param {number} by0
- * @param {number} bx1
- * @param {number} by1
- * @param {AABB2} result
- * @returns {boolean} true if overlap exists, false if no overlap
- */
-function aabb2_compute_overlap(
-    ax0, ay0, ax1, ay1,
-    bx0, by0, bx1, by1,
-    result
-) {
-
-    const x0 = max2(ax0, bx0);
-    const x1 = min2(ax1, bx1);
-
-    if (x0 >= x1) {
-        //no overlap
-        return false;
-    }
-
-    const y0 = max2(ay0, by0);
-    const y1 = min2(ay1, by1);
-
-    if (y0 >= y1) {
-        //no overlap
-        return false;
-    }
-
-    result.set(x0, y0, x1, y1);
-
-    return true;
-}
-
 /**
  *
  * Find intersection point between two line segments if they intersect at all
@@ -79334,6 +79317,46 @@ function line_segment_compute_line_segment_intersection_2d(
     return collision;
 }
 
+/**
+ *
+ * @param {number} ax0
+ * @param {number} ay0
+ * @param {number} ax1
+ * @param {number} ay1
+ * @param {number} bx0
+ * @param {number} by0
+ * @param {number} bx1
+ * @param {number} by1
+ * @param {AABB2} result
+ * @returns {boolean} true if overlap exists, false if no overlap
+ */
+function aabb2_compute_overlap(
+    ax0, ay0, ax1, ay1,
+    bx0, by0, bx1, by1,
+    result
+) {
+
+    const x0 = max2(ax0, bx0);
+    const x1 = min2(ax1, bx1);
+
+    if (x0 >= x1) {
+        //no overlap
+        return false;
+    }
+
+    const y0 = max2(ay0, by0);
+    const y1 = min2(ay1, by1);
+
+    if (y0 >= y1) {
+        //no overlap
+        return false;
+    }
+
+    result.set(x0, y0, x1, y1);
+
+    return true;
+}
+
 /**
  * Created by Alex on 08/08/2016.
  * @copyright Alex Goldring 2016
@@ -79462,7 +79485,7 @@ class AABB2 {
     /**
      *
      * @param {AABB2} other
-     * @returns {number}
+     * @returns {boolean}
      */
     overlapExists(other) {
         const ax0 = this.x0;
@@ -79489,6 +79512,7 @@ class AABB2 {
     _expandToFit(x0, y0, x1, y1) {
         this.x0 = min2(this.x0, x0);
         this.y0 = min2(this.y0, y0);
+
         this.x1 = max2(this.x1, x1);
         this.y1 = max2(this.y1, y1);
     }
@@ -79499,21 +79523,8 @@ class AABB2 {
      * @param {number} y
      */
     _expandToFitPoint(x, y) {
-        if (x < this.x0) {
-            this.x0 = x;
-        }
-
-        if (x > this.x1) {
-            this.x1 = x;
-        }
-
-        if (y < this.y0) {
-            this.y0 = y;
-        }
-
-        if (y > this.y1) {
-            this.y1 = y;
-        }
+        // shortcut, use a 0-size box
+        this._expandToFit(x, y, x, y);
     }
 
     /**
@@ -95323,23 +95334,38 @@ class Clock {
  * Created by Alex on 06/05/2015.
  */
 
+/**
+ * Simulation tick generator
+ * Dispatches "tick" every animation frame or "maxDelay" time, whichever happens to be soonest
+ * This is essentially the timing bus that all the simulation systems subscribe to for their step advancement
+ */
 class Ticker {
     /**
      * @readonly
      * @type {Clock}
      */
     clock = new Clock();
+
     /**
      * @private
      * @type {boolean}
      */
-    isRunning = false;
+    #isRunning = false;
+
 
     /**
-     *
-     * @type {SignalHandler[]}
+     * Dispatches time delta in seconds since last tick
+     * @readonly
+     * @type {Signal<number>}
      */
-    callbacks = [];
+    onTick = new Signal();
+
+    /**
+     * @deprecated
+     */
+    get callbacks() {
+        throw new Error('deprecated, use onTick signal instead');
+    }
 
     /**
      *
@@ -95350,78 +95376,43 @@ class Ticker {
     }
 
     /**
-     *
+     * @deprecated use onTick signal directly instead
      * @param {function} callback
      * @param {*} [thisArg]
      */
     subscribe(callback, thisArg) {
-        const handler = new SignalHandler(callback, thisArg);
-
-        this.callbacks.push(handler);
+        this.onTick.add(callback, thisArg);
     }
 
     /**
-     *
+     * @deprecated use onTick signal directly instead
      * @param {function} callback
      * @param {*} [thisArg]
      */
     unsubscribe(callback, thisArg) {
-
-        const callbacks = this.callbacks;
-        const n = callbacks.length;
-        for (let i = 0; i < n; i++) {
-            const cb = callbacks[i];
-
-            if (cb.handle === callback) {
-                if (thisArg !== undefined) {
-                    if (thisArg === cb.context) {
-                        callbacks.splice(i, 1);
-                        return;
-                    }
-                } else {
-                    callbacks.splice(i, 1);
-                    return;
-                }
-            }
-        }
-
+        this.onTick.remove(callback, thisArg);
     }
 
     /**
      *
-     * @param {number} maxTimeout
+     * @param {number} [maxTimeout]
      */
     start({ maxTimeout = 100 } = {}) {
 
-
-        const self = this;
         let timeout = null;
         let animationFrame = null;
 
-        this.isRunning = true;
-
-        function update() {
-            if (self.isRunning) {
-
-                const delta = self.clock.getDelta();
-
-                const callbacks = self.callbacks;
-
-                for (let i = 0; i < callbacks.length; i++) {
-                    const callback = callbacks[i];
-
-                    try {
-                        callback.handle.call(callback.context, delta);
-                    } catch (e) {
-                    }
+        this.#isRunning = true;
 
-                }
+        const update = () => {
+            if (!this.#isRunning) {
+                return;
             }
-        }
 
-        function cycle() {
-            update();
-        }
+            const delta = this.clock.getDelta();
+
+            this.onTick.send1(delta);
+        };
 
         function timeoutCallback() {
             cancelAnimationFrame(animationFrame);
@@ -95437,22 +95428,22 @@ class Ticker {
 
         function animate() {
             animationFrame = requestAnimationFrame(animationFrameCallback);
-            cycle();
+            update();
             timeout = setTimeout(timeoutCallback, maxTimeout);
         }
 
-        self.clock.getDelta(); //purge delta
-        self.clock.start();
+        this.clock.getDelta(); //purge delta
+        this.clock.start();
 
         requestAnimationFrame(animationFrameCallback);
     }
 
     pause() {
-        this.isRunning = false;
+        this.#isRunning = false;
     }
 
     resume() {
-        this.isRunning = true;
+        this.#isRunning = true;
     }
 }
 
@@ -106077,76 +106068,6 @@ class QuadTreeNode extends AABB2 {
 
 }
 
-/**
- * Remove all rectangles that are fully contained within others
- * @param {QuadTreeNode} boxes
- */
-function removeRedundantBoxes(boxes) {
-    const removals = [];
-
-
-    let datum;
-
-    /**
-     *
-     * @param {QuadTreeDatum} intersection
-     */
-    function visitDatumIntersection(intersection) {
-        if (datum === intersection) {
-            //skip self
-            return;
-        }
-
-        const ax0 = intersection.x0;
-        const ay0 = intersection.y0;
-        const ax1 = intersection.x1;
-        const ay1 = intersection.y1;
-
-        const bx0 = datum.x0;
-        const by0 = datum.y0;
-        const bx1 = datum.x1;
-        const by1 = datum.y1;
-
-        //question is now whether it is containment
-        if (ax0 >= bx0 && ax1 <= bx1 && ay0 >= by0 && ay1 <= by1) {
-            //b contains a
-            removals.push(intersection);
-        } else if (bx0 >= ax0 && bx1 <= ax1 && by0 >= ay0 && by1 <= ay1) {
-            //a contains b
-            removals.push(datum);
-
-            //scheduled removal of the datum, prevent further traversal
-            return false;
-        }
-    }
-
-    /**
-     *
-     * @param {QuadTreeNode} node
-     */
-    function visitTreeNode(node) {
-        const data = node.data;
-        const dataCount = data.length;
-
-        for (let i = 0; i < dataCount; i++) {
-            /**
-             *
-             * @type {QuadTreeDatum}
-             */
-            datum = data[i];
-
-            node.traverseRectangleIntersections(datum.x0, datum.y0, datum.x1, datum.y1, visitDatumIntersection);
-        }
-    }
-
-    boxes.traversePreOrder(visitTreeNode);
-
-    for (let i = 0; i < removals.length; i++) {
-        const removal = removals[i];
-        removal.disconnect();
-    }
-}
-
 /**
  *
  * @param {number} containerWidth
@@ -106382,6 +106303,81 @@ function packOneBox(box, free) {
     return true;
 }
 
+/**
+ * Remove all rectangles that are fully contained within others
+ * @param {QuadTreeNode} boxes
+ */
+function removeRedundantBoxes(boxes) {
+    const removals = [];
+
+
+    let datum;
+
+    /**
+     *
+     * @param {QuadTreeDatum} intersection
+     */
+    function visitDatumIntersection(intersection) {
+        if (datum === intersection) {
+            //skip self
+            return;
+        }
+
+        const ax0 = intersection.x0;
+        const ay0 = intersection.y0;
+        const ax1 = intersection.x1;
+        const ay1 = intersection.y1;
+
+        const bx0 = datum.x0;
+        const by0 = datum.y0;
+        const bx1 = datum.x1;
+        const by1 = datum.y1;
+
+        //question is now whether it is containment
+        if (ax0 >= bx0 && ax1 <= bx1 && ay0 >= by0 && ay1 <= by1) {
+            //b contains a
+            removals.push(intersection);
+        } else if (bx0 >= ax0 && bx1 <= ax1 && by0 >= ay0 && by1 <= ay1) {
+            //a contains b
+            removals.push(datum);
+
+            //scheduled removal of the datum, prevent further traversal
+            return false;
+        }
+    }
+
+    /**
+     *
+     * @param {QuadTreeNode} node
+     */
+    function visitTreeNode(node) {
+        const data = node.data;
+        const dataCount = data.length;
+
+        for (let i = 0; i < dataCount; i++) {
+            /**
+             *
+             * @type {QuadTreeDatum}
+             */
+            datum = data[i];
+
+            node.traverseRectangleIntersections(datum.x0, datum.y0, datum.x1, datum.y1, visitDatumIntersection);
+        }
+    }
+
+    boxes.traversePreOrder(visitTreeNode);
+
+    for (let i = 0; i < removals.length; i++) {
+        const removal = removals[i];
+        removal.disconnect();
+    }
+}
+
+/**
+ * Packs rectangles into a finite area, packer is incremental and supports both insertions and removals of rectangles
+ * Implementation of "max rectangles" packing algorithm.
+ * Useful for packing texture atlases
+ */
 class MaxRectanglesPacker {
     /**
      *
@@ -106396,6 +106392,8 @@ class MaxRectanglesPacker {
          * @type {QuadTreeNode}
          */
         this.free = new QuadTreeNode(0, 0, width, height);
+
+        // initialize a with a free space occupying the entire area
         this.free.add(null, 0, 0, width, height);
 
         /**
@@ -106470,7 +106468,8 @@ class MaxRectanglesPacker {
     }
 
     /**
-     *
+     * Tests whether a rectangle of given dimensions can be packed into remaining space
+     * Essentially, if this method succeeds - insertion will succeed as well, and if it fails - insertion will fail too
      * @param {number} w
      * @param {number} h
      * @return {boolean}
@@ -106554,9 +106553,10 @@ class MaxRectanglesPacker {
     }
 
     /**
-     * Resize the packer canvas
+     * Resize the packer canvas, may trigger repacking if new dimensions are smaller than the existing ones
      * @param {number} width
      * @param {number} height
+     * @returns {boolean} false if packing fails after resize, true otherwise
      */
     resize(width, height) {
 
@@ -106569,18 +106569,20 @@ class MaxRectanglesPacker {
 
         if (oldWidth > width || oldHeight > height) {
             //canvas was made smaller in at least one dimension, re-pack is required
-            this.repack();
-        } else {
-            //canvas was enlarged, we can simply add new free areas
-            if (width > oldWidth) {
-                this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
-            }
-            if (height > oldHeight) {
-                this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height));
-            }
+            return this.repack();
+        }
+
+        //canvas was enlarged, we can simply add new free areas
+        if (width > oldWidth) {
+            this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
+        }
+        if (height > oldHeight) {
+            this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height));
         }
 
         // assert.ok(this.validate());
+
+        return true;
     }
 
     validate() {