feat: Allow custom timing functions for easing (#639)

Allows specifying a timing function instead of selecting from predefined
easings or a cubic-bezier ease.

I've reused the `easing` property to set the timing function, so you can
specify a function or a string as before.

Author: jfboeve

examples/tests/animation.ts

@@ -17,12 +17,15 @@
  * limitations under the License.
  */
 
-import type { IAnimationController } from '@lightningjs/renderer';
-
+import type {
+  IAnimationController,
+  TimingFunction,
+} from '@lightningjs/renderer';
 import type { ExampleSettings } from '../common/ExampleSettings.js';
+
 interface AnimationExampleSettings {
   duration: number;
-  easing: string;
+  easing: string | TimingFunction;
   delay: number;
   loop: boolean;
   stopMethod: 'reverse' | 'reset' | false;
@@ -87,6 +90,7 @@ export default async function ({ renderer, testRoot }: ExampleSettings) {
     'ease-in-out-back',
     'cubic-bezier(0,1.35,.99,-0.07)',
     'cubic-bezier(.41,.91,.99,-0.07)',
+    'loopCustomTiming',
     'loopStopMethodReverse',
     'loopStopMethodReset',
     'loop',
@@ -121,6 +125,12 @@ export default async function ({ renderer, testRoot }: ExampleSettings) {
     } else if (easing === 'loop') {
       animationSettings.easing = 'linear';
       animationSettings.loop = true;
+    } else if (easing === 'loopCustomTiming') {
+      animationSettings.easing = (t: number) => {
+        return Math.round(t * 5) / 5;
+      };
+      animationSettings.loop = true;
+      animationSettings.stopMethod = 'reverse';
     } else {
       animationSettings.loop = false;
       animationSettings.stopMethod = false;

exports/index.ts

@@ -50,6 +50,7 @@ export {
 } from '../src/core/CoreTextureManager.js';
 export type { MemoryInfo } from '../src/core/TextureMemoryManager.js';
 export type { AnimationSettings } from '../src/core/animations/CoreAnimation.js';
+export type { TimingFunction } from '../src/core/utils.js';
 export type { Inspector } from '../src/main-api/Inspector.js';
 export type { CoreNodeRenderState } from '../src/core/CoreNode.js';
 

src/core/animations/CoreAnimation.ts

@@ -18,14 +18,14 @@
  */
 
 import { type CoreNode, type CoreNodeAnimateProps } from '../CoreNode.js';
-import { getTimingFunction } from '../utils.js';
+import { getTimingFunction, type TimingFunction } from '../utils.js';
 import { mergeColorProgress } from '../../utils.js';
 import { EventEmitter } from '../../common/EventEmitter.js';
 
 export interface AnimationSettings {
   duration: number;
   delay: number;
-  easing: string;
+  easing: string | TimingFunction;
   loop: boolean;
   repeat: number;
   repeatDelay: number;
@@ -43,7 +43,7 @@ export class CoreAnimation extends EventEmitter {
   private progress = 0;
   private delayFor = 0;
   private delay = 0;
-  private timingFunction: (t: number) => number | undefined;
+  private timingFunction: TimingFunction;
 
   propValuesMap: PropValuesMap = {};
 
@@ -92,7 +92,8 @@ export class CoreAnimation extends EventEmitter {
       repeatDelay: settings.repeatDelay ?? 0,
       stopMethod: settings.stopMethod ?? false,
     };
-    this.timingFunction = getTimingFunction(easing);
+    this.timingFunction =
+      typeof easing === 'string' ? getTimingFunction(easing) : easing;
     this.delayFor = delay;
     this.delay = delay;
   }
@@ -162,14 +163,14 @@ export class CoreAnimation extends EventEmitter {
   }
 
   private applyEasing(p: number, s: number, e: number): number {
-    return (this.timingFunction(p) || p) * (e - s) + s;
+    return this.timingFunction(p) * (e - s) + s;
   }
 
   updateValue(
     propName: string,
     propValue: number,
     startValue: number,
-    easing: string | undefined,
+    easing: string | TimingFunction | undefined,
   ): number {
     if (this.progress === 1) {
       return propValue;
@@ -201,7 +202,7 @@ export class CoreAnimation extends EventEmitter {
   private updateValues(
     target: Record<string, number>,
     valueMap: Record<string, PropValues>,
-    easing: string | undefined,
+    easing: string | TimingFunction | undefined,
   ) {
     const entries = Object.entries(valueMap);
     const eLength = entries.length;

src/core/utils.ts

@@ -30,6 +30,8 @@ export const RANDOM = Math.random;
 export const ANGLE_ORDER = 'zyx';
 const degree = Math.PI / 180;
 
+export type TimingFunction = (t: number) => number;
+
 export const setMatrixArrayType = (
   type: Float32ArrayConstructor | ArrayConstructor,
 ) => {
@@ -57,15 +59,15 @@ const getTimingBezier = (
   b: number,
   c: number,
   d: number,
-): ((time: number) => number | undefined) => {
+): TimingFunction => {
   const xc = 3.0 * a;
   const xb = 3.0 * (c - a) - xc;
   const xa = 1.0 - xc - xb;
   const yc = 3.0 * b;
   const yb = 3.0 * (d - b) - yc;
   const ya = 1.0 - yc - yb;
 
-  return function (time: number): number | undefined {
+  return function (time) {
     if (time >= 1.0) {
       return 1;
     }
@@ -116,11 +118,13 @@ const getTimingBezier = (
         minT = t;
       }
     }
+
+    return time;
   };
 };
 
 interface TimingFunctionMap {
-  [key: string]: (time: number) => number | undefined;
+  [key: string]: TimingFunction;
 }
 
 type TimingLookupArray = number[];
@@ -174,9 +178,7 @@ const parseCubicBezier = (str: string) => {
   return defaultTiming;
 };
 
-export const getTimingFunction = (
-  str: string,
-): ((time: number) => number | undefined) => {
+export const getTimingFunction = (str: string): TimingFunction => {
   if (str === 'linear') {
     return defaultTiming;
   }
@@ -202,7 +204,7 @@ export const getTimingFunction = (
     const [a, b, c, d] = lookup;
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore - TS doesn't understand that we've checked for undefined
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+
     const timing = getTimingBezier(a, b, c, d);
     timingMapping[str] = timing;
     return timing;