@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta20

package/src/core/textures/Texture.ts

@@ -22,6 +22,7 @@ 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';
 
 /**
  * Event handler for when a Texture is freed
@@ -44,7 +45,7 @@ export type TextureLoadedEventHandler = (
 /**
  * Represents compressed texture data.
  */
-interface CompressedData {
+export interface CompressedData {
   /**
    * GLenum spcifying compression format
    */
@@ -53,24 +54,33 @@ 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;
+  };
 }
 
 /**
@@ -100,6 +110,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 +150,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: Error | null = null;
 
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners = new Set<unknown>();
+  readonly renderableOwners: any[] = [];
 
   readonly renderable: boolean = false;
 
@@ -155,8 +168,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(): Error | 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 +276,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 +351,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,7 +388,7 @@ 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(
@@ -259,11 +401,32 @@ export abstract class Texture extends EventEmitter {
 
     let payload: Error | 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 Error;
+      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 +452,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

@@ -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,7 +59,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 +67,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 +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;

package/src/main-api/INode.ts

@@ -57,15 +57,16 @@ export interface INode<ShaderNode extends CoreShaderNode = CoreShaderNode>
 /**
  * Properties used to animate() a Node
  */
-export interface INodeAnimateProps<ShNode extends CoreShaderNode>
-  extends Omit<CoreNodeAnimateProps, 'shaderProps'> {
+export interface INodeAnimateProps<
+  ShNode extends CoreShaderNode = CoreShaderNode,
+> extends Omit<CoreNodeAnimateProps, 'shaderProps'> {
   shaderProps: Partial<ShNode['props']>;
 }
 
 /**
  * Properties used to create a new Node
  */
-export interface INodeProps<ShNode extends CoreShaderNode>
+export interface INodeProps<ShNode extends CoreShaderNode = CoreShaderNode>
   extends Omit<CoreNodeProps, 'shader' | 'parent'> {
   shader: ShNode;
   parent: INode | null;