@lightningjs/renderer 3.0.0-beta17 → 3.0.0-beta19

package/src/core/textures/ImageTexture.ts

@@ -109,6 +109,12 @@ export interface ImageTextureProps {
    * @default null
    */
   sy?: number | null;
+  /**
+   * Maximum number of times to retry loading the image if it fails.
+   *
+   * @default 5
+   */
+  maxRetryCount?: number;
 }
 
 /**
@@ -131,11 +137,15 @@ export class ImageTexture extends Texture {
   public props: Required<ImageTextureProps>;
   public override type: TextureType = TextureType.image;
 
-  constructor(txManager: CoreTextureManager, props: ImageTextureProps) {
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<ImageTextureProps>,
+  ) {
     super(txManager);
 
     this.platform = txManager.platform;
-    this.props = ImageTexture.resolveDefaults(props);
+    this.props = props;
+    this.maxRetryCount = props.maxRetryCount as number;
   }
 
   hasAlphaChannel(mimeType: string) {
@@ -152,14 +162,19 @@ export class ImageTexture extends Texture {
     return new Promise<{
       data: HTMLImageElement | null;
       premultiplyAlpha: boolean;
-    }>((resolve) => {
+    }>((resolve, reject) => {
       img.onload = () => {
         resolve({ data: img, premultiplyAlpha: hasAlpha });
       };
 
-      img.onerror = () => {
-        console.warn('Image loading failed, returning fallback object.');
-        resolve({ data: null, premultiplyAlpha: hasAlpha });
+      img.onerror = (err) => {
+        const errorMessage =
+          err instanceof Error
+            ? err.message
+            : err instanceof Event
+            ? `Image loading failed for ${img.src}`
+            : 'Unknown image loading error';
+        reject(new Error(`Image loading failed: ${errorMessage}`));
       };
 
       if (src instanceof Blob) {
@@ -253,17 +268,12 @@ export class ImageTexture extends Texture {
   }
 
   override async getTextureSource(): Promise<TextureData> {
-    let resp;
+    let resp: TextureData;
     try {
       resp = await this.determineImageTypeAndLoadImage();
     } catch (e) {
       this.setState('failed', e as Error);
 
-      // log error only in development
-      if (isProductionEnvironment === false) {
-        console.error('ImageTexture:', e);
-      }
-
       return {
         data: null,
       };
@@ -276,23 +286,6 @@ export class ImageTexture extends Texture {
       };
     }
 
-    let w, h;
-    // check if resp.data is typeof Uint8ClampedArray else
-    // use resp.data.width and resp.data.height
-    if (resp.data instanceof Uint8Array) {
-      w = this.props.w ?? 0;
-      h = this.props.h ?? 0;
-    } else {
-      w = resp.data?.width ?? (this.props.w || 0);
-      h = resp.data?.height ?? (this.props.h || 0);
-    }
-
-    // we're loaded!
-    this.setState('fetched', {
-      w,
-      h,
-    });
-
     return {
       data: resp.data,
       premultiplyAlpha: this.props.premultiplyAlpha ?? true,
@@ -375,26 +368,25 @@ export class ImageTexture extends Texture {
    * @returns The cache key as a string, or `false` if the key cannot be generated.
    */
   static override makeCacheKey(props: ImageTextureProps): string | false {
-    const resolvedProps = ImageTexture.resolveDefaults(props);
     // Only cache key-able textures; prioritise key
-    const key = resolvedProps.key || resolvedProps.src;
+    const key = props.key || props.src;
     if (typeof key !== 'string') {
       return false;
     }
 
-    // if we have source dimensions, cache the texture separately
-    let dimensionProps = '';
-    if (resolvedProps.sh !== null && resolvedProps.sw !== null) {
-      dimensionProps += ',';
-      dimensionProps += resolvedProps.sx ?? '';
-      dimensionProps += resolvedProps.sy ?? '';
-      dimensionProps += resolvedProps.sw || '';
-      dimensionProps += resolvedProps.sh || '';
+    let cacheKey = `ImageTexture,${key},${props.premultiplyAlpha ?? 'true'},${
+      props.maxRetryCount
+    }`;
+
+    if (props.sh !== null && props.sw !== null) {
+      cacheKey += ',';
+      cacheKey += props.sx ?? '';
+      cacheKey += props.sy ?? '';
+      cacheKey += props.sw || '';
+      cacheKey += props.sh || '';
     }
 
-    return `ImageTexture,${key},${
-      resolvedProps.premultiplyAlpha ?? 'true'
-    }${dimensionProps}`;
+    return cacheKey;
   }
 
   static override resolveDefaults(
@@ -411,6 +403,7 @@ export class ImageTexture extends Texture {
       sy: props.sy ?? null,
       sw: props.sw ?? null,
       sh: props.sh ?? null,
+      maxRetryCount: props.maxRetryCount ?? 5,
     };
   }
 

package/src/core/textures/NoiseTexture.ts

@@ -58,9 +58,12 @@ export class NoiseTexture extends Texture {
 
   public override type: TextureType = TextureType.noise;
 
-  constructor(txManager: CoreTextureManager, props: NoiseTextureProps) {
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<NoiseTextureProps>,
+  ) {
     super(txManager);
-    this.props = NoiseTexture.resolveDefaults(props);
+    this.props = props;
   }
 
   override async getTextureSource(): Promise<TextureData> {
@@ -75,8 +78,7 @@ export class NoiseTexture extends Texture {
       pixelData8[i + 3] = 255;
     }
 
-    this.setState('fetched');
-
+    // Noise Texture data ready - dimensions will be set during upload
     return {
       data: new ImageData(pixelData8, w, h),
     };

package/src/core/textures/RenderTexture.ts

@@ -42,9 +42,12 @@ export class RenderTexture extends Texture {
 
   public override type: TextureType = TextureType.renderToTexture;
 
-  constructor(txManager: CoreTextureManager, props?: RenderTextureProps) {
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<RenderTextureProps>,
+  ) {
     super(txManager);
-    this.props = RenderTexture.resolveDefaults(props || {});
+    this.props = props;
   }
 
   get w() {
@@ -64,8 +67,7 @@ export class RenderTexture extends Texture {
   }
 
   override async getTextureSource(): Promise<TextureData> {
-    this.setState('fetched');
-
+    // Render texture data ready - dimensions will be set during upload
     return {
       data: null,
       premultiplyAlpha: null,

package/src/core/textures/SubTexture.ts

@@ -30,6 +30,8 @@ import {
   type TextureState,
 } from './Texture.js';
 
+let subTextureId = 0;
+
 /**
  * Properties of the {@link SubTexture}
  */
@@ -83,10 +85,11 @@ export class SubTexture extends Texture {
   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 +100,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 +110,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 +130,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', {
+    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', {
-      w: this.props.w,
-      h: this.props.h,
-    });
-  };
-
-  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,
       });

package/src/core/textures/Texture.ts

@@ -54,12 +54,12 @@ export 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.
@@ -72,6 +72,15 @@ export interface CompressedData {
    * The height of the compressed texture in pixels.
    **/
   h: number;
+
+  /**
+   * block info compressed texture format
+   */
+  blockInfo: {
+    width: number;
+    height: number;
+    bytes: number;
+  };
 }
 
 /**
@@ -144,16 +153,10 @@ export abstract class Texture extends EventEmitter {
   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'];
-
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners = new Set<unknown>();
+  readonly renderableOwners: any[] = [];
 
   readonly renderable: boolean = false;
 
@@ -165,8 +168,37 @@ 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 {
@@ -177,6 +209,59 @@ export abstract class Texture extends EventEmitter {
     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.
    *
@@ -191,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);
   }
 
@@ -256,6 +351,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.
    *
@@ -281,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(
@@ -308,6 +415,18 @@ export abstract class Texture extends EventEmitter {
     } else if (state === 'failed') {
       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
@@ -333,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/main-api/Renderer.ts

@@ -425,6 +425,20 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * @defaultValue `null`
    */
   platform: typeof Platform | null;
+
+  /**
+   * Number of times to retry loading a failed texture
+   *
+   * @remarks
+   * When a texture fails to load, Lightning will retry up to this many times
+   * before permanently giving up. Each retry will clear the texture ownership
+   * and then re-establish it to trigger a new load attempt.
+   *
+   * Set to null to disable retries. Set to 0 to always try once and never retry.
+   * This is typically only used on ImageTexture instances.
+   *
+   */
+  maxRetryCount?: number;
 };
 
 /**
@@ -493,7 +507,7 @@ export class RendererMain extends EventEmitter {
    */
   constructor(
     settings: Partial<RendererMainSettings>,
-    target: string | HTMLElement,
+    target?: string | HTMLElement,
   ) {
     super();
 
@@ -508,7 +522,7 @@ export class RendererMain extends EventEmitter {
       boundsMargin: settings.boundsMargin || 0,
       deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
       devicePhysicalPixelRatio:
-        settings.devicePhysicalPixelRatio || window.devicePixelRatio,
+        settings.devicePhysicalPixelRatio || window.devicePixelRatio || 1,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
       targetFPS: settings.targetFPS || 0,
@@ -525,6 +539,7 @@ export class RendererMain extends EventEmitter {
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
       platform: settings.platform || null,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     };
 
     const {
@@ -582,24 +597,31 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
       createImageBitmapSupport: settings.createImageBitmapSupport!,
       platform,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     });
 
     // Extract the root node
     this.root = this.stage.root as unknown as INode;
 
     // Get the target element and attach the canvas to it
-    let targetEl: HTMLElement | null;
-    if (typeof target === 'string') {
-      targetEl = document.getElementById(target);
-    } else {
-      targetEl = target;
-    }
+    if (target) {
+      let targetEl: HTMLElement | null;
+      if (typeof target === 'string') {
+        targetEl = document.getElementById(target);
+      } else {
+        targetEl = target;
+      }
 
-    if (!targetEl) {
-      throw new Error('Could not find target element');
-    }
+      if (!targetEl) {
+        throw new Error('Could not find target element');
+      }
 
-    targetEl.appendChild(canvas);
+      targetEl.appendChild(canvas);
+    } else if (settings.canvas !== canvas) {
+      throw new Error(
+        'New canvas element could not be appended to undefined target',
+      );
+    }
 
     // Initialize inspector (if enabled)
     if (inspector && isProductionEnvironment === false) {
@@ -832,8 +854,8 @@ export class RendererMain extends EventEmitter {
    * **NOTE3**: This will not cleanup textures that are marked as `preventCleanup`.
    * **NOTE4**: This has nothing to do with the garbage collection of JavaScript.
    */
-  cleanup(aggressive: boolean = false) {
-    this.stage.cleanup(aggressive);
+  cleanup() {
+    this.stage.cleanup();
   }
 
   /**