@lightningtv/renderer 2.16.1 → 3.2.3

package/src/core/textures/Texture.ts

@@ -1,27 +1,10 @@
-/*
- * 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 { CoreTextureManager } from '../CoreTextureManager.js';
 import type { SubTextureProps } from './SubTexture.js';
 import type { Dimensions } from '../../common/CommonTypes.js';
 import { EventEmitter } from '../../common/EventEmitter.js';
 import type { CoreContextTexture } from '../renderers/CoreContextTexture.js';
+import type { Bound } from '../lib/utils.js';
+import type { TextureError } from '../TextureError.js';
 
 /**
  * Event handler for when a Texture is freed
@@ -44,7 +27,7 @@ export type TextureLoadedEventHandler = (
 /**
  * Represents compressed texture data.
  */
-interface CompressedData {
+export interface CompressedData {
   /**
    * GLenum spcifying compression format
    */
@@ -53,30 +36,42 @@ interface CompressedData {
   /**
    * All mipmap levels
    */
-  mipmaps?: ArrayBuffer[];
+  mipmaps: ArrayBuffer[];
 
   /**
    * Supported container types ('pvr' or 'ktx').
    */
-  type: 'pvr' | 'ktx';
+  type: 'pvr' | 'ktx' | 'astc';
 
   /**
    * The width of the compressed texture in pixels. Defaults to 0.
    *
    * @default 0
    */
-  width: number;
+  w: number;
 
   /**
    * The height of the compressed texture in pixels.
    **/
-  height: number;
+  h: number;
+
+  /**
+   * block info compressed texture format
+   */
+  blockInfo: {
+    width: number;
+    height: number;
+    bytes: number;
+  };
 }
 
 /**
  * Event handler for when a Texture fails to load
  */
-export type TextureFailedEventHandler = (target: any, error: Error) => void;
+export type TextureFailedEventHandler = (
+  target: any,
+  error: TextureError,
+) => void;
 
 /**
  * TextureData that is used to populate a CoreContextTexture
@@ -100,6 +95,10 @@ export interface TextureData {
    */
   premultiplyAlpha?: boolean | null;
 }
+/**
+ * TextureCoords generally numbers between 0 - 1
+ */
+export type TextureCoords = Bound;
 
 export type TextureState =
   | 'initial' // Before anything is loaded
@@ -137,18 +136,12 @@ export abstract class Texture extends EventEmitter {
    * `null`.
    */
   private _dimensions: Dimensions | null = null;
-  private _error: Error | null = null;
-
-  /**
-   * Texture states that are considered transitional and should be skipped during cleanup
-   */
-  public static readonly TRANSITIONAL_TEXTURE_STATES: readonly TextureState[] =
-    ['fetching', 'fetched', 'loading'];
+  private _error: TextureError | null = null;
 
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners = new Set<unknown>();
+  readonly renderableOwners: any[] = [];
 
   readonly renderable: boolean = false;
 
@@ -160,18 +153,100 @@ export abstract class Texture extends EventEmitter {
 
   public textureData: TextureData | null = null;
 
+  public memUsed = 0;
+
+  /**
+   * Memory used by this texture in bytes
+   *
+   * @remarks
+   * This is tracked by the TextureMemoryManager and updated when the texture
+   * is loaded/freed. Set to 0 when texture is not loaded.
+   */
+  public retryCount = 0;
+  public maxRetryCount: number;
+
+  /**
+   * Timestamp when texture was created (for startup grace period)
+   */
+  private createdAt: number = Date.now();
+
+  /**
+   * Flag to track if grace period has expired to avoid repeated Date.now() calls
+   */
+  private gracePeriodExpired: boolean = false;
+
+  /**
+   * Grace period in milliseconds to prevent premature cleanup during app startup
+   * This helps prevent race conditions when bounds calculation is delayed
+   */
+  private static readonly STARTUP_GRACE_PERIOD = 2000; // 2 seconds
+
   constructor(protected txManager: CoreTextureManager) {
     super();
+    this.maxRetryCount = this.txManager.maxRetryCount;
   }
 
   get dimensions(): Dimensions | null {
     return this._dimensions;
   }
 
-  get error(): Error | null {
+  get error(): TextureError | null {
     return this._error;
   }
 
+  /**
+   * Checks if the texture is within the startup grace period.
+   * During this period, textures are protected from cleanup to prevent
+   * race conditions during app initialization.
+   */
+  isWithinStartupGracePeriod(): boolean {
+    // If grace period already expired, return false immediately
+    if (this.gracePeriodExpired === true) {
+      return false;
+    }
+
+    // Check if grace period has expired now
+    const hasExpired =
+      Date.now() - this.createdAt >= Texture.STARTUP_GRACE_PERIOD;
+
+    if (hasExpired) {
+      // Cache the result to avoid future Date.now() calls
+      this.gracePeriodExpired = true;
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if the texture can be safely cleaned up.
+   * Considers the renderable state, startup grace period, and renderable owners.
+   */
+  canBeCleanedUp(): boolean {
+    // Never cleanup if explicitly prevented
+    if (this.preventCleanup) {
+      return false;
+    }
+
+    // Don't cleanup if still within startup grace period
+    if (this.isWithinStartupGracePeriod()) {
+      return false;
+    }
+
+    // Don't cleanup if not renderable
+    if (this.renderable === true) {
+      return false;
+    }
+
+    // Don't cleanup if there are still renderable owners
+    if (this.renderableOwners.length > 0) {
+      return false;
+    }
+
+    // Safe to cleanup
+    return true;
+  }
+
   /**
    * Add/remove an owner to/from the Texture based on its renderability.
    *
@@ -186,33 +261,43 @@ export abstract class Texture extends EventEmitter {
    * @param owner
    * @param renderable
    */
-  setRenderableOwner(owner: unknown, renderable: boolean): void {
-    const oldSize = this.renderableOwners.size;
+  setRenderableOwner(owner: string | number, renderable: boolean): void {
+    const oldSize = this.renderableOwners.length;
+    const hasOwnerIndex = this.renderableOwners.indexOf(owner);
 
     if (renderable === true) {
-      if (this.renderableOwners.has(owner) === false) {
+      if (hasOwnerIndex === -1) {
         // Add the owner to the set
-        this.renderableOwners.add(owner);
+        this.renderableOwners.push(owner);
       }
 
-      const newSize = this.renderableOwners.size;
-      if (newSize > oldSize && newSize === 1) {
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 1) {
         (this.renderable as boolean) = true;
         this.onChangeIsRenderable?.(true);
         this.load();
       }
     } else {
-      this.renderableOwners.delete(owner);
-      const newSize = this.renderableOwners.size;
-      if (newSize < oldSize && newSize === 0) {
+      if (hasOwnerIndex !== -1) {
+        this.renderableOwners.splice(hasOwnerIndex, 1);
+      }
+
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 0) {
         (this.renderable as boolean) = false;
         this.onChangeIsRenderable?.(false);
-        this.txManager.orphanTexture(this);
+
+        // note, not doing a cleanup here, cleanup is managed by the Stage/TextureMemoryManager
+        // when it deems appropriate based on memory pressure
       }
     }
   }
 
   load(): void {
+    if (this.retryCount > this.maxRetryCount) {
+      // We've exceeded the max retry count, do not attempt to load again
+      return;
+    }
     this.txManager.loadTexture(this);
   }
 
@@ -251,6 +336,18 @@ export abstract class Texture extends EventEmitter {
     this.ctxTexture?.free();
   }
 
+  /**
+   * Release the texture data and core context texture for this Texture without changing state.
+   *
+   * @remarks
+   * The ctxTexture is created by the renderer and lives on the GPU.
+   */
+  release(): void {
+    this.ctxTexture?.release();
+    this.ctxTexture = undefined;
+    this.freeTextureData();
+  }
+
   /**
    * Destroy the texture.
    *
@@ -276,33 +373,45 @@ export abstract class Texture extends EventEmitter {
    * e.g. ImageData that is downloaded from a URL.
    */
   freeTextureData(): void {
-    this.textureData = null;
+    queueMicrotask(this.freeTextureDataTask);
   }
 
   public setState(
     state: TextureState,
-    errorOrDimensions?: Error | Dimensions,
+    errorOrDimensions?: TextureError | Dimensions,
   ): void {
     if (this.state === state) {
       return;
     }
 
-    let payload: Error | Dimensions | null = null;
+    let payload: TextureError | Dimensions | null = null;
     if (state === 'loaded') {
       if (
         errorOrDimensions !== undefined &&
-        'width' in errorOrDimensions === true &&
-        'height' in errorOrDimensions === true &&
-        errorOrDimensions.width !== undefined &&
-        errorOrDimensions.height !== undefined
+        'w' in errorOrDimensions === true &&
+        'h' in errorOrDimensions === true &&
+        errorOrDimensions.w !== undefined &&
+        errorOrDimensions.h !== undefined
       ) {
         this._dimensions = errorOrDimensions;
       }
 
       payload = this._dimensions;
     } else if (state === 'failed') {
-      this._error = errorOrDimensions as Error;
+      this._error = errorOrDimensions as TextureError;
       payload = this._error;
+
+      // increment the retry count for the texture
+      // this is used to compare against maxRetryCount, if set
+      // to determine if we should try loading again
+      this.retryCount += 1;
+
+      queueMicrotask(this.releaseTask);
+    } else if (state === 'loading') {
+      this._error = null;
+      this._dimensions = null;
+    } else {
+      this._error = null;
     }
 
     // emit the new state
@@ -328,6 +437,26 @@ export abstract class Texture extends EventEmitter {
     return this.textureData;
   }
 
+  /**
+   * Task for queueMicrotask to free texture data.
+   *
+   * @remarks
+   * This method is called in a microtask to free the texture data.
+   */
+  private freeTextureDataTask = (): void => {
+    this.textureData = null;
+  };
+
+  /**
+   * Task for queueMicrotask to release the texture.
+   *
+   * @remarks
+   * This method is called in a microtask to release the texture.
+   */
+  private releaseTask = (): void => {
+    this.release();
+  };
+
   /**
    * Get the texture source for this texture.
    *
@@ -370,7 +499,7 @@ export abstract class Texture extends EventEmitter {
   static resolveDefaults(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     props: unknown,
-  ): Record<string, unknown> {
+  ): Record<string, any> {
     return {};
   }
 }

package/src/core/utils.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.
- */
-
 /**
  * Core Utility Functions
  *
@@ -30,6 +11,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,7 +40,7 @@ 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;
@@ -65,7 +48,7 @@ const getTimingBezier = (
   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 +99,13 @@ const getTimingBezier = (
         minT = t;
       }
     }
+
+    return time;
   };
 };
 
 interface TimingFunctionMap {
-  [key: string]: (time: number) => number | undefined;
+  [key: string]: TimingFunction;
 }
 
 type TimingLookupArray = number[];
@@ -174,9 +159,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 +185,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;

package/src/main-api/INode.ts

@@ -1,21 +1,3 @@
-/*
- * 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 type { IAnimationController } from '../common/IAnimationController.js';
 import {
   CoreNode,
@@ -24,7 +6,7 @@ import {
 } from '../core/CoreNode.js';
 import type { CoreTextNode, CoreTextNodeProps } from '../core/CoreTextNode.js';
 import type { AnimationSettings } from '../core/animations/CoreAnimation.js';
-import type { BaseShaderController } from './ShaderController.js';
+import type { CoreShaderNode } from '../core/renderers/CoreShaderNode.js';
 
 /**
  * A visual Node in the Renderer scene graph.
@@ -44,11 +26,11 @@ import type { BaseShaderController } from './ShaderController.js';
  * Users of the Renderer API, should generally interact with INode objects
  * instead of CoreNode objects.
  */
-export interface INode<SC extends BaseShaderController = BaseShaderController>
+export interface INode<ShaderNode extends CoreShaderNode = CoreShaderNode>
   extends Omit<CoreNode, 'shader' | 'animate' | 'parent'> {
-  shader: SC;
+  shader: ShaderNode;
   animate(
-    props: Partial<INodeAnimateProps<SC>>,
+    props: Partial<INodeAnimateProps<ShaderNode>>,
     settings: Partial<AnimationSettings>,
   ): IAnimationController;
   parent: INode | null;
@@ -58,18 +40,17 @@ export interface INode<SC extends BaseShaderController = BaseShaderController>
  * Properties used to animate() a Node
  */
 export interface INodeAnimateProps<
-  SC extends BaseShaderController = BaseShaderController,
+  ShNode extends CoreShaderNode = CoreShaderNode,
 > extends Omit<CoreNodeAnimateProps, 'shaderProps'> {
-  shaderProps: Partial<SC['props']>;
+  shaderProps: Partial<ShNode['props']>;
 }
 
 /**
  * Properties used to create a new Node
  */
-export interface INodeProps<
-  SC extends BaseShaderController = BaseShaderController,
-> extends Omit<CoreNodeProps, 'shader' | 'parent'> {
-  shader: SC;
+export interface INodeProps<ShNode extends CoreShaderNode = CoreShaderNode>
+  extends Omit<CoreNodeProps, 'shader' | 'parent'> {
+  shader: ShNode;
   parent: INode | null;
 }
 
@@ -87,7 +68,7 @@ export interface INodeProps<
  */
 export interface ITextNode extends Omit<CoreTextNode, 'animate' | 'parent'> {
   animate(
-    props: Partial<INodeAnimateProps<BaseShaderController>>,
+    props: Partial<INodeAnimateProps<CoreShaderNode>>,
     settings: Partial<AnimationSettings>,
   ): IAnimationController;
   parent: INode | null;