@lightningtv/renderer 3.0.0-beta1 → 3.2.4

package/src/core/TextureError.ts

@@ -0,0 +1,46 @@
+export enum TextureErrorCode {
+  MEMORY_THRESHOLD_EXCEEDED = 'MEMORY_THRESHOLD_EXCEEDED',
+  TEXTURE_DATA_NULL = 'TEXTURE_DATA_NULL',
+  TEXTURE_TYPE_NOT_REGISTERED = 'TEXTURE_TYPE_NOT_REGISTERED',
+}
+
+const defaultMessages: Record<TextureErrorCode, string> = {
+  [TextureErrorCode.MEMORY_THRESHOLD_EXCEEDED]: 'Memory threshold exceeded',
+  [TextureErrorCode.TEXTURE_DATA_NULL]: 'Texture data is null',
+  [TextureErrorCode.TEXTURE_TYPE_NOT_REGISTERED]:
+    'Texture type is not registered',
+};
+
+export class TextureError extends Error {
+  code?: TextureErrorCode;
+
+  constructor(message: string);
+  constructor(code: TextureErrorCode, message?: string);
+  constructor(codeOrMessage: TextureErrorCode | string, maybeMessage?: string) {
+    const isCode = Object.values(TextureErrorCode).includes(
+      codeOrMessage as TextureErrorCode,
+    );
+
+    const code = isCode ? (codeOrMessage as TextureErrorCode) : undefined;
+    let message: string;
+    if (isCode && code) {
+      message = maybeMessage ?? defaultMessages[code];
+    } else {
+      message = String(codeOrMessage);
+    }
+
+    super(message);
+    this.name = new.target.name;
+    if (code) this.code = code;
+  }
+}
+
+export function isTextureError(err: unknown): err is TextureError {
+  return (
+    err instanceof TextureError ||
+    (typeof err === 'object' &&
+      err !== null &&
+      (err as { name?: unknown }).name === 'TextureError' &&
+      typeof (err as { code?: unknown }).code === 'string')
+  );
+}

package/src/core/TextureMemoryManager.ts

@@ -1,25 +1,6 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2024 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 import { isProductionEnvironment } from '../utils.js';
-import { getTimeStamp } from './platform.js';
 import type { Stage } from './Stage.js';
-import { TextureType, type Texture } from './textures/Texture.js';
+import { Texture, TextureType } from './textures/Texture.js';
 import { bytesToMb } from './utils.js';
 
 export interface TextureMemoryManagerSettings {
@@ -116,17 +97,21 @@ export interface MemoryInfo {
  */
 export class TextureMemoryManager {
   private memUsed = 0;
-  private loadedTextures: Map<Texture, number> = new Map();
-  private orphanedTextures: Texture[] = [];
-  private criticalThreshold: number;
-  private targetThreshold: number;
-  private cleanupInterval: number;
-  private debugLogging: boolean;
+  private loadedTextures: Set<Texture> = new Set();
+  private orphanedTextures: Set<Texture> = new Set();
+  private criticalThreshold: number = 124e6;
+  private targetThreshold: number = 0.5;
+  private cleanupInterval: number = 5000;
+  private debugLogging: boolean = false;
+  private loggingID: ReturnType<typeof setInterval> =
+    0 as unknown as ReturnType<typeof setInterval>;
   private lastCleanupTime = 0;
-  private baselineMemoryAllocation: number;
+  private baselineMemoryAllocation: number = 26e6;
+
+  private hasWarnedAboveCritical = false;
 
   public criticalCleanupRequested = false;
-  public doNotExceedCriticalThreshold: boolean;
+  public doNotExceedCriticalThreshold: boolean = false;
 
   /**
    * The current frame time in milliseconds
@@ -139,46 +124,7 @@ export class TextureMemoryManager {
   public frameTime = 0;
 
   constructor(private stage: Stage, settings: TextureMemoryManagerSettings) {
-    const { criticalThreshold, doNotExceedCriticalThreshold } = settings;
-    this.doNotExceedCriticalThreshold = doNotExceedCriticalThreshold || false;
-    this.criticalThreshold = Math.round(criticalThreshold);
-    const targetFraction = Math.max(
-      0,
-      Math.min(1, settings.targetThresholdLevel),
-    );
-    this.cleanupInterval = settings.cleanupInterval;
-    this.debugLogging = settings.debugLogging;
-    this.baselineMemoryAllocation = Math.round(
-      settings.baselineMemoryAllocation,
-    );
-    this.targetThreshold = Math.max(
-      Math.round(criticalThreshold * targetFraction),
-      this.baselineMemoryAllocation,
-    );
-    this.memUsed = Math.round(settings.baselineMemoryAllocation);
-
-    if (settings.debugLogging) {
-      let lastMemUse = 0;
-      setInterval(() => {
-        if (lastMemUse !== this.memUsed) {
-          lastMemUse = this.memUsed;
-          console.log(
-            `[TextureMemoryManager] Memory used: ${bytesToMb(
-              this.memUsed,
-            )} mb / ${bytesToMb(this.criticalThreshold)} mb (${(
-              (this.memUsed / this.criticalThreshold) *
-              100
-            ).toFixed(1)}%)`,
-          );
-        }
-      }, 1000);
-    }
-
-    // If the threshold is 0, we disable the memory manager by replacing the
-    // setTextureMemUse method with a no-op function.
-    if (criticalThreshold === 0) {
-      this.setTextureMemUse = () => {};
-    }
+    this.updateSettings(settings);
   }
 
   /**
@@ -188,13 +134,13 @@ export class TextureMemoryManager {
    */
   addToOrphanedTextures(texture: Texture) {
     // if the texture is already in the orphaned textures list add it at the end
-    if (this.orphanedTextures.includes(texture)) {
-      this.removeFromOrphanedTextures(texture);
+    if (this.orphanedTextures.has(texture)) {
+      this.orphanedTextures.delete(texture);
     }
 
     // If the texture can be cleaned up, add it to the orphaned textures list
     if (texture.preventCleanup === false) {
-      this.orphanedTextures.push(texture);
+      this.orphanedTextures.add(texture);
     }
   }
 
@@ -204,10 +150,7 @@ export class TextureMemoryManager {
    * @param texture - The texture to remove from the orphaned textures list
    */
   removeFromOrphanedTextures(texture: Texture) {
-    const index = this.orphanedTextures.indexOf(texture);
-    if (index !== -1) {
-      this.orphanedTextures.splice(index, 1);
-    }
+    this.orphanedTextures.delete(texture);
   }
 
   /**
@@ -217,17 +160,19 @@ export class TextureMemoryManager {
    * @param byteSize - The size of the texture in bytes
    */
   setTextureMemUse(texture: Texture, byteSize: number) {
-    if (this.loadedTextures.has(texture)) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.memUsed -= this.loadedTextures.get(texture)!;
-    }
+    // Update global memory counter by subtracting old value
+    this.memUsed -= texture.memUsed;
 
     if (byteSize === 0) {
+      // PERFORMANCE: Mark for deletion, slot will be reused later
       this.loadedTextures.delete(texture);
+      texture.memUsed = 0;
       return;
     } else {
+      // Update texture memory and add to tracking if not already present
+      texture.memUsed = byteSize;
       this.memUsed += byteSize;
-      this.loadedTextures.set(texture, byteSize);
+      this.loadedTextures.add(texture);
     }
 
     if (this.memUsed > this.criticalThreshold) {
@@ -247,82 +192,33 @@ export class TextureMemoryManager {
     return this.memUsed > this.criticalThreshold;
   }
 
-  cleanupQuick(critical: boolean) {
-    // Free non-renderable textures until we reach the target threshold
-    const memTarget = this.targetThreshold;
-    const txManager = this.stage.txManager;
-    const timestamp = getTimeStamp();
-
-    while (
-      this.memUsed >= memTarget &&
-      this.orphanedTextures.length > 0 &&
-      (critical || getTimeStamp() - timestamp < 10)
-    ) {
-      const texture = this.orphanedTextures.shift();
-
-      if (texture === undefined) {
-        continue;
-      }
-
-      if (texture.renderable === true) {
-        // If the texture is renderable, we can't free it up
-        continue;
-      }
-
-      texture.free();
-      txManager.removeTextureFromCache(texture);
-    }
-  }
-
-  cleanupDeep(critical: boolean) {
-    // Free non-renderable textures until we reach the target threshold
-    const memTarget = critical ? this.criticalThreshold : this.targetThreshold;
-    const txManager = this.stage.txManager;
-
-    // sort by renderability
-    const filteredAndSortedTextures: Texture[] = [];
-    const textures = [...this.loadedTextures.keys()];
-    for (let i = 0; i < textures.length; i++) {
-      const texture = textures[i];
-      if (texture === undefined) {
-        continue;
-      }
-
-      if (
-        texture.type === TextureType.image ||
-        texture.type === TextureType.noise ||
-        texture.type === TextureType.renderToTexture
-      ) {
-        if (texture.renderable === true) {
-          filteredAndSortedTextures.push(texture);
-        } else {
-          filteredAndSortedTextures.unshift(texture);
-        }
-      }
+  /**
+   * Destroy a texture and remove it from the memory manager
+   *
+   * @param texture - The texture to destroy
+   */
+  destroyTexture(texture: Texture) {
+    if (this.debugLogging === true) {
+      console.log(
+        `[TextureMemoryManager] Destroying texture. State: ${texture.state}`,
+      );
     }
 
-    while (this.memUsed >= memTarget && filteredAndSortedTextures.length > 0) {
-      const texture = filteredAndSortedTextures.shift();
-      if (texture === undefined) {
-        continue;
-      }
+    // PERFORMANCE: Null out array position, slot will be reused later
+    this.loadedTextures.delete(texture);
 
-      if (texture.preventCleanup === true) {
-        continue;
-      }
+    // Destroy texture and update memory counters
+    const txManager = this.stage.txManager;
+    txManager.removeTextureFromCache(texture);
 
-      if (texture.renderable === true) {
-        break;
-      }
+    texture.destroy();
 
-      texture.free();
-      this.removeFromOrphanedTextures(texture);
-      txManager.removeTextureFromCache(texture);
-      txManager.removeTextureFromQueue(texture);
-    }
+    // Update memory counters
+    this.memUsed -= texture.memUsed;
+    texture.memUsed = 0;
   }
 
-  cleanup(aggressive: boolean = false) {
+  cleanup(full: boolean = false) {
     const critical = this.criticalCleanupRequested;
     this.lastCleanupTime = this.frameTime;
 
@@ -335,16 +231,38 @@ export class TextureMemoryManager {
 
     if (this.debugLogging === true) {
       console.log(
-        `[TextureMemoryManager] Cleaning up textures. Critical: ${critical}. Aggressive: ${aggressive}`,
+        `[TextureMemoryManager] Cleaning up textures. Critical: ${critical}. Full: ${full}`,
       );
     }
 
-    // try a quick cleanup first
-    this.cleanupQuick(critical);
+    // Free non-renderable textures until we reach the target threshold
+    const memTarget = critical ? this.criticalThreshold : this.targetThreshold;
 
-    // if we're still above the target threshold, do a deep cleanup
-    if (aggressive === true && this.memUsed >= this.criticalThreshold) {
-      this.cleanupDeep(critical);
+    // PERFORMANCE: Zero-overhead cleanup with null marking
+    // Skip null entries, mark cleaned textures as null for later defrag
+    let currentMemUsed = this.memUsed;
+
+    for (const texture of this.loadedTextures) {
+      // Early exit: target memory reached
+      if (full === false && currentMemUsed < memTarget) {
+        break;
+      }
+
+      // Fast type check for cleanable textures
+      const isCleanableType =
+        texture.type === TextureType.image ||
+        texture.type === TextureType.noise ||
+        texture.type === TextureType.renderToTexture;
+
+      // Immediate cleanup if eligible
+      if (isCleanableType && texture.canBeCleanedUp() === true) {
+        // Get memory before destroying
+        const textureMemory = texture.memUsed;
+
+        // Destroy texture (which will null out the array position)
+        this.destroyTexture(texture);
+        currentMemUsed -= textureMemory;
+      }
     }
 
     if (this.memUsed >= this.criticalThreshold) {
@@ -352,14 +270,20 @@ export class TextureMemoryManager {
         memUsed: this.memUsed,
         criticalThreshold: this.criticalThreshold,
       });
-
-      if (this.debugLogging === true || isProductionEnvironment() === false) {
+      // Only emit the warning once per over-threshold period
+      if (
+        !this.hasWarnedAboveCritical &&
+        (this.debugLogging === true || isProductionEnvironment === false)
+      ) {
         console.warn(
           `[TextureMemoryManager] Memory usage above critical threshold after cleanup: ${this.memUsed}`,
         );
+
+        this.hasWarnedAboveCritical = true;
       }
     } else {
       this.criticalCleanupRequested = false;
+      this.hasWarnedAboveCritical = false;
     }
   }
 
@@ -372,15 +296,17 @@ export class TextureMemoryManager {
    */
   getMemoryInfo(): MemoryInfo {
     let renderableTexturesLoaded = 0;
-    const renderableMemUsed = [...this.loadedTextures.keys()].reduce(
-      (acc, texture) => {
-        renderableTexturesLoaded += texture.renderable ? 1 : 0;
-        return (
-          acc + (texture.renderable ? this.loadedTextures.get(texture)! : 0)
-        );
-      },
-      this.baselineMemoryAllocation,
-    );
+    let renderableMemUsed = this.baselineMemoryAllocation;
+
+    for (const texture of this.loadedTextures) {
+      if (texture && texture.renderable) {
+        renderableTexturesLoaded += 1;
+        renderableMemUsed += texture.memUsed;
+      }
+    }
+
+    // Count non-null entries for accurate loaded texture count
+    const actualLoadedTextures = this.loadedTextures.size;
 
     return {
       criticalThreshold: this.criticalThreshold,
@@ -388,8 +314,65 @@ export class TextureMemoryManager {
       renderableMemUsed,
       memUsed: this.memUsed,
       renderableTexturesLoaded,
-      loadedTextures: this.loadedTextures.size,
+      loadedTextures: actualLoadedTextures,
       baselineMemoryAllocation: this.baselineMemoryAllocation,
     };
   }
+
+  public updateSettings(settings: TextureMemoryManagerSettings): void {
+    const { criticalThreshold, doNotExceedCriticalThreshold } = settings;
+
+    this.doNotExceedCriticalThreshold = doNotExceedCriticalThreshold || false;
+    this.criticalThreshold = Math.round(criticalThreshold);
+
+    if (this.memUsed === 0) {
+      this.memUsed = Math.round(settings.baselineMemoryAllocation);
+    } else {
+      const memUsedExBaseline = this.memUsed - this.baselineMemoryAllocation;
+      this.memUsed = Math.round(
+        settings.baselineMemoryAllocation + memUsedExBaseline,
+      );
+    }
+    this.baselineMemoryAllocation = Math.round(
+      settings.baselineMemoryAllocation,
+    );
+    const targetFraction = Math.max(
+      0,
+      Math.min(1, settings.targetThresholdLevel),
+    );
+    this.targetThreshold = Math.max(
+      Math.round(criticalThreshold * targetFraction),
+      this.baselineMemoryAllocation,
+    );
+
+    this.cleanupInterval = settings.cleanupInterval;
+    this.debugLogging = settings.debugLogging;
+
+    if (this.loggingID && !settings.debugLogging) {
+      clearInterval(this.loggingID);
+      this.loggingID = 0 as unknown as ReturnType<typeof setInterval>;
+    }
+    if (settings.debugLogging && !this.loggingID) {
+      let lastMemUse = 0;
+      this.loggingID = setInterval(() => {
+        if (lastMemUse !== this.memUsed) {
+          lastMemUse = this.memUsed;
+          console.log(
+            `[TextureMemoryManager] Memory used: ${bytesToMb(
+              this.memUsed,
+            )} mb / ${bytesToMb(this.criticalThreshold)} mb (${(
+              (this.memUsed / this.criticalThreshold) *
+              100
+            ).toFixed(1)}%)`,
+          );
+        }
+      }, 1000);
+    }
+
+    // If the threshold is 0, we disable the memory manager by replacing the
+    // setTextureMemUse method with a no-op function.
+    if (criticalThreshold === 0) {
+      this.setTextureMemUse = () => {};
+    }
+  }
 }

package/src/core/animations/AnimationManager.ts

@@ -1,22 +1,3 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import { CoreAnimation } from './CoreAnimation.js';
 
 export class AnimationManager {

package/src/core/animations/CoreAnimation.ts

@@ -1,34 +1,14 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 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;
   stopMethod: 'reverse' | 'reset' | false;
 }
 
@@ -43,7 +23,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 = {};
 
@@ -89,10 +69,10 @@ export class CoreAnimation extends EventEmitter {
       easing,
       loop: settings.loop ?? false,
       repeat: settings.repeat ?? 0,
-      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 +142,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 +181,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;
@@ -215,6 +195,13 @@ export class CoreAnimation extends EventEmitter {
   update(dt: number) {
     const { duration, loop, easing, stopMethod } = this.settings;
     const { delayFor } = this;
+
+    if (this.node.destroyed) {
+      // cleanup
+      this.emit('destroyed', {});
+      return;
+    }
+
     if (duration === 0 && delayFor === 0) {
       this.emit('finished', {});
       return;
@@ -273,10 +260,6 @@ export class CoreAnimation extends EventEmitter {
       );
     }
 
-    if (this.progress < 1) {
-      this.emit('tick', { progress: this.progress });
-    }
-
     if (this.progress === 1) {
       this.emit('finished', {});
     }

package/src/core/animations/CoreAnimationController.ts

@@ -1,23 +1,3 @@
-/* eslint-disable @typescript-eslint/unbound-method */
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import type {
   AnimationControllerState,
   IAnimationController,
@@ -52,6 +32,7 @@ export class CoreAnimationController
     this.onAnimating = this.onAnimating.bind(this);
     this.onFinished = this.onFinished.bind(this);
     this.onTick = this.onTick.bind(this);
+    this.onDestroy = this.onDestroy.bind(this);
   }
 
   start(): IAnimationController {
@@ -96,6 +77,7 @@ export class CoreAnimationController
     this.animation.once('finished', this.onFinished);
     this.animation.on('animating', this.onAnimating);
     this.animation.on('tick', this.onTick);
+    this.animation.on('destroyed', this.onDestroy);
     // Then register the animation
     this.manager.registerAnimation(this.animation);
   }
@@ -107,6 +89,7 @@ export class CoreAnimationController
     this.animation.off('finished', this.onFinished);
     this.animation.off('animating', this.onAnimating);
     this.animation.off('tick', this.onTick);
+    this.animation.off('destroy', this.onDestroy);
   }
 
   private makeStoppedPromise(): void {
@@ -117,8 +100,12 @@ export class CoreAnimationController
     }
   }
 
+  private onDestroy(this: CoreAnimationController): void {
+    this.unregisterAnimation();
+    this.state = 'stopped';
+  }
+
   private onFinished(this: CoreAnimationController): void {
-    assertTruthy(this.stoppedResolve);
     // If the animation is looping, then we need to restart it.
     const { loop, stopMethod } = this.animation.settings;
 
@@ -136,8 +123,11 @@ export class CoreAnimationController
     this.unregisterAnimation();
 
     // resolve promise
-    this.stoppedResolve();
-    this.stoppedResolve = null;
+    if (this.stoppedResolve !== null) {
+      this.stoppedResolve();
+      this.stoppedResolve = null;
+    }
+
     this.emit('stopped', this);
     this.state = 'stopped';
   }