@lightningjs/renderer 2.17.0 → 2.18.0

package/src/core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.ts

@@ -412,7 +412,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
         this.setStatus(state, 'failed', new Error(msg));
         return;
       }
-      trFontFace.texture.setRenderableOwner(state, true);
+      trFontFace.texture.setRenderableOwner(state.props.fontFamily, true);
     }
 
     // If the font hasn't been loaded yet, stop here.
@@ -787,13 +787,16 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
     renderable: boolean,
   ): void {
     super.setIsRenderable(state, renderable);
-    state.trFontFace?.texture.setRenderableOwner(state, renderable);
+    state.trFontFace?.texture.setRenderableOwner(
+      state.props.fontFamily,
+      renderable,
+    );
   }
 
   override destroyState(state: SdfTextRendererState): void {
     super.destroyState(state);
     // If there's a Font Face assigned we must free the owner relation to its texture
-    state.trFontFace?.texture.setRenderableOwner(state, false);
+    state.trFontFace?.texture.setRenderableOwner(state.props.fontFamily, false);
   }
   //#endregion Overrides
 
@@ -813,7 +816,10 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
   protected releaseFontFace(state: SdfTextRendererState) {
     state.resLineHeight = undefined;
     if (state.trFontFace) {
-      state.trFontFace.texture.setRenderableOwner(state, false);
+      state.trFontFace.texture.setRenderableOwner(
+        state.props.fontFamily,
+        false,
+      );
       state.trFontFace = undefined;
     }
   }

package/src/core/textures/ColorTexture.ts

@@ -45,13 +45,12 @@ export interface ColorTextureProps {
  * a Node are.
  */
 export class ColorTexture extends Texture {
-  public override type: TextureType = TextureType.color;
+  override readonly type = TextureType.color as const;
+  public props: Required<ColorTextureProps>;
 
-  props: Required<ColorTextureProps>;
-
-  constructor(txManager: CoreTextureManager, props?: ColorTextureProps) {
+  constructor(txManager: CoreTextureManager, props: ColorTextureProps) {
     super(txManager);
-    this.props = ColorTexture.resolveDefaults(props || {});
+    this.props = ColorTexture.resolveDefaults(props);
   }
 
   get color() {
@@ -77,8 +76,6 @@ export class ColorTexture extends Texture {
       pixelData[3] = (this.color >>> 24) & 0xff; // Alpha
     }
 
-    this.setState('fetched', { width: 1, height: 1 });
-
     return {
       data: pixelData,
       premultiplyAlpha: true,

package/src/core/textures/ImageTexture.ts

@@ -107,6 +107,13 @@ export interface ImageTextureProps {
    * @default null
    */
   sy?: number | null;
+
+  /**
+   * Maximum number of times to retry loading the image if it fails.
+   *
+   * @default 5
+   */
+  maxRetryCount?: number | null;
 }
 
 /**
@@ -124,13 +131,14 @@ export interface ImageTextureProps {
  * {@link ImageTextureProps.premultiplyAlpha} prop to `false`.
  */
 export class ImageTexture extends Texture {
+  override readonly type = TextureType.image as const;
   public props: Required<ImageTextureProps>;
 
-  public override type: TextureType = TextureType.image;
-
   constructor(txManager: CoreTextureManager, props: ImageTextureProps) {
+    const resolvedProps = ImageTexture.resolveDefaults(props);
     super(txManager);
-    this.props = ImageTexture.resolveDefaults(props);
+    this.props = resolvedProps;
+    this.maxRetryCount = props.maxRetryCount as number;
   }
 
   hasAlphaChannel(mimeType: string) {
@@ -147,14 +155,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) {
@@ -181,28 +194,40 @@ export class ImageTexture extends Texture {
 
     if (imageBitmapSupported.full === true && sw !== null && sh !== null) {
       // createImageBitmap with crop
-      const bitmap = await createImageBitmap(blob, sx || 0, sy || 0, sw, sh, {
-        premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
-        colorSpaceConversion: 'none',
-        imageOrientation: 'none',
-      });
-      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+      try {
+        const bitmap = await createImageBitmap(blob, sx || 0, sy || 0, sw, sh, {
+          premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+          colorSpaceConversion: 'none',
+          imageOrientation: 'none',
+        });
+        return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+      } catch (error) {
+        throw new Error(`Failed to create image bitmap with crop: ${error}`);
+      }
     } else if (imageBitmapSupported.basic === true) {
       // basic createImageBitmap without options or crop
       // this is supported for Chrome v50 to v52/54 that doesn't support options
-      return {
-        data: await createImageBitmap(blob),
-        premultiplyAlpha: hasAlphaChannel,
-      };
+      try {
+        return {
+          data: await createImageBitmap(blob),
+          premultiplyAlpha: hasAlphaChannel,
+        };
+      } catch (error) {
+        throw new Error(`Failed to create basic image bitmap: ${error}`);
+      }
     }
 
     // default createImageBitmap without crop but with options
-    const bitmap = await createImageBitmap(blob, {
-      premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
-      colorSpaceConversion: 'none',
-      imageOrientation: 'none',
-    });
-    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    try {
+      const bitmap = await createImageBitmap(blob, {
+        premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+        colorSpaceConversion: 'none',
+        imageOrientation: 'none',
+      });
+      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    } catch (error) {
+      throw new Error(`Failed to create image bitmap with options: ${error}`);
+    }
   }
 
   async loadImage(src: string) {
@@ -214,14 +239,18 @@ export class ImageTexture extends Texture {
         this.txManager.hasWorker === true &&
         this.txManager.imageWorkerManager !== null
       ) {
-        return this.txManager.imageWorkerManager.getImage(
-          src,
-          premultiplyAlpha,
-          sx,
-          sy,
-          sw,
-          sh,
-        );
+        try {
+          return this.txManager.imageWorkerManager.getImage(
+            src,
+            premultiplyAlpha,
+            sx,
+            sy,
+            sw,
+            sh,
+          );
+        } catch (error) {
+          throw new Error(`Failed to load image via worker: ${error}`);
+        }
       }
 
       let blob;
@@ -229,9 +258,11 @@ export class ImageTexture extends Texture {
       if (isBase64Image(src) === true) {
         blob = dataURIToBlob(src);
       } else {
-        blob = await fetchJson(src, 'blob').then(
-          (response) => response as Blob,
-        );
+        try {
+          blob = (await fetchJson(src, 'blob')) as Blob;
+        } catch (error) {
+          throw new Error(`Failed to fetch image blob from ${src}: ${error}`);
+        }
       }
 
       return this.createImageBitmap(blob, premultiplyAlpha, sx, sy, sw, sh);
@@ -258,23 +289,6 @@ export class ImageTexture extends Texture {
       };
     }
 
-    let width, height;
-    // check if resp.data is typeof Uint8ClampedArray else
-    // use resp.data.width and resp.data.height
-    if (resp.data instanceof Uint8Array) {
-      width = this.props.width ?? 0;
-      height = this.props.height ?? 0;
-    } else {
-      width = resp.data?.width ?? (this.props.width || 0);
-      height = resp.data?.height ?? (this.props.height || 0);
-    }
-
-    // we're loaded!
-    this.setState('fetched', {
-      width,
-      height,
-    });
-
     return {
       data: resp.data,
       premultiplyAlpha: this.props.premultiplyAlpha ?? true,
@@ -393,6 +407,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

@@ -75,7 +75,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, width, height),

package/src/core/textures/RenderTexture.ts

@@ -64,7 +64,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,

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,6 +85,7 @@ export class SubTexture extends Texture {
   parentTexture: Texture;
 
   public override type: TextureType = TextureType.subTexture;
+  public subtextureId = `subtexture-${subTextureId++}`;
 
   constructor(txManager: CoreTextureManager, props: SubTextureProps) {
     super(txManager);
@@ -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) {
+        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) {
+        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);
@@ -143,17 +140,6 @@ export class SubTexture extends Texture {
     this.forwardParentTxState('failed', error);
   };
 
-  private onParentTxFetched = () => {
-    this.forwardParentTxState('fetched', {
-      width: this.props.width,
-      height: this.props.height,
-    });
-  };
-
-  private onParentTxFetching = () => {
-    this.forwardParentTxState('fetching');
-  };
-
   private onParentTxLoading = () => {
     this.forwardParentTxState('loading');
   };
@@ -171,17 +157,14 @@ export class SubTexture extends Texture {
 
   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,
-      });
-    });
+    // SubTexture data ready - dimensions will be set during upload
+    return {
+      data: this.props,
+    };
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/src/core/textures/Texture.ts

@@ -103,9 +103,7 @@ export interface TextureData {
 
 export type TextureState =
   | 'initial' // Before anything is loaded
-  | 'fetching' // Fetching or generating texture source
-  | 'fetched' // Texture source is ready
-  | 'loading' // Uploading to GPU
+  | 'loading' // Loading texture data and uploading to GPU
   | 'loaded' // Fully loaded and usable
   | 'failed' // Failed to load
   | 'freed'; // Released and must be reloaded
@@ -139,16 +137,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;
 
@@ -160,6 +152,34 @@ export abstract class Texture extends EventEmitter {
 
   public textureData: TextureData | null = null;
 
+  /**
+   * 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 memUsed = 0;
+
+  public retryCount = 0;
+  public maxRetryCount: number | null = null;
+
+  /**
+   * 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();
   }
@@ -172,6 +192,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) {
+      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 +259,44 @@ 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.maxRetryCount !== null && this.retryCount > this.maxRetryCount) {
+      // We've exceeded the max retry count, do not attempt to load again
+      return;
+    }
+
     this.txManager.loadTexture(this);
   }
 
@@ -251,6 +335,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,7 +372,9 @@ export abstract class Texture extends EventEmitter {
    * e.g. ImageData that is downloaded from a URL.
    */
   freeTextureData(): void {
-    this.textureData = null;
+    queueMicrotask(() => {
+      this.textureData = null;
+    });
   }
 
   public setState(
@@ -289,6 +387,9 @@ export abstract class Texture extends EventEmitter {
 
     let payload: Error | Dimensions | null = null;
     if (state === 'loaded') {
+      // Clear any previous error when successfully loading
+      this._error = null;
+
       if (
         errorOrDimensions !== undefined &&
         'width' in errorOrDimensions === true &&
@@ -303,6 +404,22 @@ 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.release();
+      });
+    } else if (state === 'loading') {
+      // Clear error and reset dimensions when starting to load
+      // This ensures stale dimensions from previous loads don't persist
+      this._error = null;
+      this._dimensions = null;
+    } else {
+      this._error = null;
     }
 
     // emit the new state
@@ -373,4 +490,16 @@ export abstract class Texture extends EventEmitter {
   ): Record<string, unknown> {
     return {};
   }
+
+  /**
+   * Retry the texture by resetting retryCount and setting state to 'initial'.
+   *
+   * @remarks
+   * This allows the texture to be loaded again.
+   */
+  public retry(): void {
+    this.release();
+    this.retryCount = 0;
+    this.load();
+  }
 }