@lightningtv/renderer 3.0.0-beta1 → 3.2.4

package/src/core/textures/SubTexture.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 type { Dimensions } from '../../common/CommonTypes.js';
 import { assertTruthy } from '../../utils.js';
 import type { CoreTextureManager } from '../CoreTextureManager.js';
@@ -30,6 +11,8 @@ import {
   type TextureState,
 } from './Texture.js';
 
+let subTextureId = 0;
+
 /**
  * Properties of the {@link SubTexture}
  */
@@ -60,12 +43,12 @@ export interface SubTextureProps {
    *
    * @default 0
    */
-  width?: number;
+  w?: number;
 
   /**
    * The height of the sub-texture in pixels
    **/
-  height?: number;
+  h?: number;
 }
 
 /**
@@ -75,18 +58,19 @@ export interface SubTextureProps {
  * The parent texture can be a Sprite Sheet/Texture Atlas and set using the
  * {@link SubTextureProps.texture} prop. The sub-region relative to the parent
  * texture is defined with the {@link SubTextureProps.x},
- * {@link SubTextureProps.y}, {@link SubTextureProps.width}, and
- * {@link SubTextureProps.height} pixel values.
+ * {@link SubTextureProps.y}, {@link SubTextureProps.w}, and
+ * {@link SubTextureProps.h} pixel values.
  */
 export class SubTexture extends Texture {
   props: Required<SubTextureProps>;
   parentTexture: Texture;
 
   public override type: TextureType = TextureType.subTexture;
+  public subtextureId = `subtexture-${subTextureId++}`;
 
-  constructor(txManager: CoreTextureManager, props: SubTextureProps) {
+  constructor(txManager: CoreTextureManager, props: Required<SubTextureProps>) {
     super(txManager);
-    this.props = SubTexture.resolveDefaults(props || {});
+    this.props = props;
 
     assertTruthy(this.props.texture, 'SubTexture requires a parent texture');
     assertTruthy(
@@ -97,8 +81,8 @@ export class SubTexture extends Texture {
     // Resolve parent texture from cache or fallback to provided texture
     this.parentTexture = txManager.resolveParentTexture(this.props.texture);
 
-    if (this.renderableOwners.size > 0) {
-      this.parentTexture.setRenderableOwner(this, true);
+    if (this.renderableOwners.length > 0) {
+      this.parentTexture.setRenderableOwner(this.subtextureId, true);
     }
 
     // If parent texture is already loaded / failed, trigger loaded event manually
@@ -107,23 +91,17 @@ export class SubTexture extends Texture {
     // synchronous task after calling loadTexture()
     queueMicrotask(() => {
       const parentTx = this.parentTexture;
-      if (parentTx.state === 'loaded') {
-        this.onParentTxLoaded(parentTx, parentTx.dimensions!);
-      } else if (parentTx.state === 'fetching') {
-        this.onParentTxFetching();
-      } else if (parentTx.state === 'fetched') {
-        this.onParentTxFetched();
+      if (parentTx.state === 'loaded' && parentTx.dimensions !== null) {
+        this.onParentTxLoaded(parentTx, parentTx.dimensions);
       } else if (parentTx.state === 'loading') {
         this.onParentTxLoading();
-      } else if (parentTx.state === 'failed') {
-        this.onParentTxFailed(parentTx, parentTx.error!);
+      } else if (parentTx.state === 'failed' && parentTx.error !== null) {
+        this.onParentTxFailed(parentTx, parentTx.error);
       } else if (parentTx.state === 'freed') {
         this.onParentTxFreed();
       }
 
-      parentTx.on('fetched', this.onParentTxFetched);
       parentTx.on('loading', this.onParentTxLoading);
-      parentTx.on('fetching', this.onParentTxFetching);
       parentTx.on('loaded', this.onParentTxLoaded);
       parentTx.on('failed', this.onParentTxFailed);
       parentTx.on('freed', this.onParentTxFreed);
@@ -133,51 +111,33 @@ export class SubTexture extends Texture {
   private onParentTxLoaded: TextureLoadedEventHandler = () => {
     // We ignore the parent's passed dimensions, and simply use the SubTexture's
     // configured dimensions (because that's all that matters here)
-    this.forwardParentTxState('loaded', {
-      width: this.props.width,
-      height: this.props.height,
+    this.setState('loaded', {
+      w: this.props.w,
+      h: this.props.h,
     });
   };
 
   private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
-    this.forwardParentTxState('failed', error);
-  };
-
-  private onParentTxFetched = () => {
-    this.forwardParentTxState('fetched', {
-      width: this.props.width,
-      height: this.props.height,
-    });
-  };
-
-  private onParentTxFetching = () => {
-    this.forwardParentTxState('fetching');
+    this.retryCount = this.parentTexture.retryCount - 1;
+    this.setState('failed', error);
   };
 
   private onParentTxLoading = () => {
-    this.forwardParentTxState('loading');
+    this.setState('loading');
   };
 
   private onParentTxFreed = () => {
-    this.forwardParentTxState('freed');
+    this.setState('freed');
   };
 
-  private forwardParentTxState(
-    state: TextureState,
-    errorOrDimensions?: Error | Dimensions,
-  ) {
-    this.setState(state, errorOrDimensions);
-  }
-
   override onChangeIsRenderable(isRenderable: boolean): void {
     // Propagate the renderable owner change to the parent texture
-    this.parentTexture.setRenderableOwner(this, isRenderable);
+    this.parentTexture.setRenderableOwner(this.subtextureId, isRenderable);
   }
 
   override async getTextureSource(): Promise<TextureData> {
     // Check if parent texture is loaded
     return new Promise((resolve, reject) => {
-      this.setState('fetched');
       resolve({
         data: this.props,
       });
@@ -196,8 +156,8 @@ export class SubTexture extends Texture {
       texture: props.texture,
       x: props.x || 0,
       y: props.y || 0,
-      width: props.width || 0,
-      height: props.height || 0,
+      w: props.w || 0,
+      h: props.h || 0,
     };
   }
 

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
@@ -136,14 +135,13 @@ export abstract class Texture extends EventEmitter {
    * Until the texture data is loaded for the first time the value will be
    * `null`.
    */
-  readonly dimensions: Readonly<Dimensions> | null = null;
-
-  readonly error: Error | null = null;
+  private _dimensions: Dimensions | null = null;
+  private _error: TextureError | null = null;
 
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners = new Set<unknown>();
+  readonly renderableOwners: any[] = [];
 
   readonly renderable: boolean = false;
 
@@ -155,8 +153,98 @@ 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(): 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;
   }
 
   /**
@@ -173,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);
   }
 
@@ -238,6 +336,35 @@ 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.
+   *
+   * @remarks
+   * This method is called when the texture is no longer needed and should be
+   * cleaned up.
+   */
+  destroy(): void {
+    // Only free GPU resources if we're in a state where they exist
+    if (this.state === 'loaded') {
+      this.free();
+    }
+
+    // Always free texture data regardless of state
+    this.freeTextureData();
+  }
+
   /**
    * Free the source texture data for this Texture.
    *
@@ -246,24 +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') {
-      (this.dimensions as Dimensions) = errorOrDimensions as Dimensions;
-      payload = this.dimensions;
+      if (
+        errorOrDimensions !== 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 as Error) = errorOrDimensions as Error;
-      payload = this.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
@@ -289,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.
    *

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,