@woosh/meep-engine 2.131.3 → 2.131.6

package/src/engine/animation/curve/AnimationCurve.js

@@ -1,5 +1,4 @@
 import { assert } from "../../../core/assert.js";
-import { binarySearchHighIndex } from "../../../core/collection/array/binarySearchHighIndex.js";
 import { computeHashArray } from "../../../core/collection/array/computeHashArray.js";
 import { isArrayEqual } from "../../../core/collection/array/isArrayEqual.js";
 import { lerp } from "../../../core/math/lerp.js";
@@ -9,16 +8,6 @@ import { invokeObjectToJSON } from "../../../core/model/object/invokeObjectToJSO
 import { evaluate_two_key_curve } from "./evaluate_two_key_curve.js";
 import { Keyframe } from "./Keyframe.js";
 
-/**
- *
- * @param {number} time
- * @param {Keyframe} keyframe
- * @return {number}
- */
-function compareKeyframeToTime(time, keyframe) {
-    return time - keyframe.time;
-}
-
 /**
  * Describes change of a numeric value over time.
  * Values are stored in {@link Keyframe}s, interpolation is defined by tangents on {@link Keyframe}s.
@@ -33,6 +22,13 @@ function compareKeyframeToTime(time, keyframe) {
  *
  *  jump_curve.evaluate(0.1); // what is the height at time 0.1?
  *
+ * @example
+ *  const curve = AnimationCurve.easeInOut();
+ *
+ *  sprite.transparency = curve.evaluate(time); // smoothly animate transparency of the sprite
+ *
+ * @implements Iterable<Keyframe>
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
  */
@@ -61,6 +57,8 @@ export class AnimationCurve {
         const key_count = keys.length;
         const last_key_index = key_count - 1;
 
+        // Optimization: if the curve is empty or the new key is chronologically
+        // after the last key, we can simply push it to the end.
         if (
             last_key_index < 0
             || keys[last_key_index].time <= key.time
@@ -71,17 +69,21 @@ export class AnimationCurve {
 
             return key_count;
 
-        } else {
+        } else if (key_count > 0 && keys[0].time > key.time) {
 
-            // figure out the right place to insert the key
-            // TODO make use of this.getKeyIndexByTime instead
-            const i = binarySearchHighIndex(keys, key.time, compareKeyframeToTime, 0, last_key_index);
+            keys.unshift(key);
 
-            // insert key at the right place
-            keys.splice(i, 0, key);
-
-            return i;
+            return 0;
         }
+
+        // figure out the right place to insert the key
+        const i = this.getKeyIndexLow(key.time) + 1;
+
+        // insert key at the right place
+        keys.splice(i, 0, key);
+
+        return i;
+
     }
 
     /**
@@ -101,7 +103,7 @@ export class AnimationCurve {
     /**
      *
      * @param {Keyframe} key
-     * @returns {boolean}
+     * @returns {boolean} true if the key was removed, false if the key was not found
      */
     remove(key) {
         const i = this.keys.indexOf(key);
@@ -196,21 +198,37 @@ export class AnimationCurve {
 
     /**
      * Returns index of a key that is just before or at the time specified.
+     * Useful for insertion and evaluation logic.
+     * Note: if time is past the end of last key - index of the last key will be returned instead
      * @param {number} time
      * @returns {number} index of the key
      */
-    getKeyIndexByTime(time) {
+    getKeyIndexLow(time) {
+        assert.isNumber(time, 'time');
+        assert.notNaN(time, 'time');
+
         const keys = this.keys;
         const key_count = keys.length;
 
-        let i0 = 0;
-        let i1 = key_count - 1;
+        if (key_count === 0) {
+            // no keys
+            return 0;
+        }
 
         if (time <= keys[0].time) {
             // before start
             return 0;
         }
 
+        if (time >= keys[key_count - 1].time) {
+            // after the end
+            return key_count - 1;
+        }
+
+        let found_index = 0;
+        let i0 = 0;
+        let i1 = key_count - 1;
+
         // binary search
         while (i0 <= i1) {
             const pivot = (i0 + i1) >>> 1;
@@ -218,27 +236,22 @@ export class AnimationCurve {
             const key = keys[pivot];
             const key_time = key.time;
 
-            if (key_time < time) {
+            if (key_time <= time) {
+                found_index = pivot;
                 i0 = pivot + 1;
             } else if (key_time > time) {
                 i1 = pivot - 1;
-            } else {
-                i0 = pivot;
-                break;
             }
         }
 
-        if (i0 > i1) {
-            // swap
-            i0 = i1;
-        }
+        assert.lessThanOrEqual(keys[found_index].time, time, 'keys[found_index].time >= time');
 
         // fast-forward to last matching frame if there are multiple matches
-        while (i0 + 1 < key_count - 1 && keys[i0 + 1].time === time) {
-            i0++;
+        while (found_index + 2 < key_count && keys[found_index + 1].time === time) {
+            found_index++;
         }
 
-        return i0;
+        return found_index;
     }
 
     /**
@@ -262,7 +275,7 @@ export class AnimationCurve {
             return keys[0].value;
         }
 
-        const i = this.getKeyIndexByTime(time);
+        const i = this.getKeyIndexLow(time);
 
         if (i >= key_count - 1) {
             // past last keyframe
@@ -400,12 +413,25 @@ export class AnimationCurve {
 
             keyframe.fromJSON(keys[i]);
 
+            // The 'add' sorts the keys incrementally, we can do this faster if we assume the input is already sorted.
+            // But to be safe we don't make that assumption
+
             this.add(keyframe);
 
         }
 
     }
 
+    * [Symbol.iterator]() {
+
+        for (const key of this.keys) {
+
+            yield key;
+
+        }
+
+    }
+
     /**
      * Utility constructor
      * @param {Keyframe[]} keys
@@ -422,6 +448,7 @@ export class AnimationCurve {
     /**
      * S-shaped curve that starts slowly, ramps up and flattens out again.
      * Useful for pleasing transitions where exit and entry should not be abrupt.
+     *
      * @param {number} [timeStart]
      * @param {number} [valueStart]
      * @param {number} [timeEnd]
@@ -482,4 +509,10 @@ export class AnimationCurve {
  * @readonly
  * @type {boolean}
  */
-AnimationCurve.prototype.isAnimationCurve = true;
+AnimationCurve.prototype.isAnimationCurve = true;
+
+
+/**
+ * @deprecated use `getKeyIndexLow` instead
+ */
+AnimationCurve.prototype.getKeyIndexByTime = AnimationCurve.prototype.getKeyIndexLow;