@lightningjs/renderer 3.0.0-beta18 → 3.0.0-beta19

package/src/core/CoreTextNode.ts

@@ -264,7 +264,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
 
       if (this.renderState > CoreNodeRenderState.OutOfBounds) {
         // We do want the texture to load immediately
-        this.texture.setRenderableOwner(this, true);
+        this.texture.setRenderableOwner(this._id, true);
       }
     }
 
@@ -279,14 +279,19 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     }
 
     this._renderInfo = result;
+    queueMicrotask(this.emitTextLoadedEvent);
+  }
+
+  // Reusable bound method for emitting loaded event
+  private emitTextLoadedEvent = () => {
     this.emit('loaded', {
       type: 'text',
       dimensions: {
-        w: width,
-        h: height,
+        w: this._renderInfo.width,
+        h: this._renderInfo.height,
       },
     } satisfies NodeTextLoadedPayload);
-  }
+  };
 
   /**
    * Override renderQuads to handle SDF vs Canvas rendering

package/src/core/CoreTextureManager.ts

@@ -32,6 +32,7 @@ import {
   type CreateImageBitmapSupport,
 } from './lib/validateImageBitmap.js';
 import type { Platform } from './platforms/Platform.js';
+import { TextureError, TextureErrorCode } from './TextureError.js';
 
 /**
  * Augmentable map of texture class types
@@ -64,6 +65,7 @@ export interface TextureManagerDebugInfo {
 export interface TextureManagerSettings {
   numImageWorkers: number;
   createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
+  maxRetryCount: number;
 }
 
 export type ResizeModeOptions =
@@ -138,6 +140,20 @@ export interface TextureOptions {
    */
   preventCleanup?: boolean;
 
+  /**
+   * 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 | null;
+
   /**
    * Flip the texture horizontally when rendering
    *
@@ -178,6 +194,7 @@ export class CoreTextureManager extends EventEmitter {
    */
   txConstructors: Partial<TextureMap> = {};
 
+  public maxRetryCount: number;
   private priorityQueue: Array<Texture> = [];
   private uploadTextureQueue: Array<Texture> = [];
   private initialized = false;
@@ -218,10 +235,13 @@ export class CoreTextureManager extends EventEmitter {
   constructor(stage: Stage, settings: TextureManagerSettings) {
     super();
 
-    const { numImageWorkers, createImageBitmapSupport } = settings;
+    const { numImageWorkers, createImageBitmapSupport, maxRetryCount } =
+      settings;
+
     this.stage = stage;
     this.platform = stage.platform;
     this.numImageWorkers = numImageWorkers;
+    this.maxRetryCount = maxRetryCount;
 
     if (createImageBitmapSupport === 'auto') {
       validateCreateImageBitmap(this.platform)
@@ -315,14 +335,14 @@ export class CoreTextureManager extends EventEmitter {
     if (!TextureClass) {
       throw new Error(`Texture type "${textureType}" is not registered`);
     }
-
-    const cacheKey = TextureClass.makeCacheKey(props as any);
+    const resolvedProps = TextureClass.resolveDefaults(props as any);
+    const cacheKey = TextureClass.makeCacheKey(resolvedProps as any);
     if (cacheKey && this.keyCache.has(cacheKey)) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       texture = this.keyCache.get(cacheKey)!;
     } else {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
-      texture = new TextureClass(this, props as any);
+      texture = new TextureClass(this, resolvedProps as any);
 
       if (cacheKey) {
         this.initTextureToCache(texture, cacheKey);
@@ -332,25 +352,13 @@ export class CoreTextureManager extends EventEmitter {
     return texture as InstanceType<TextureMap[Type]>;
   }
 
-  orphanTexture(texture: Texture): void {
-    // if it is part of the download or upload queue, remove it
-    this.removeTextureFromQueue(texture);
-
-    if (texture.type === TextureType.subTexture) {
-      // ignore subtextures
-      return;
-    }
-
-    this.stage.txMemManager.addToOrphanedTextures(texture);
-  }
-
   /**
    * Override loadTexture to use the batched approach.
    *
    * @param texture - The texture to load
    * @param immediate - Whether to prioritize the texture for immediate loading
    */
-  loadTexture(texture: Texture, priority?: boolean): void {
+  async loadTexture(texture: Texture, priority?: boolean): Promise<void> {
     this.stage.txMemManager.removeFromOrphanedTextures(texture);
 
     if (texture.type === TextureType.subTexture) {
@@ -363,56 +371,39 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
-    if (Texture.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)) {
-      return;
-    }
-
     // if we're not initialized, just queue the texture into the priority queue
     if (this.initialized === false) {
       this.priorityQueue.push(texture);
       return;
     }
 
-    // If the texture failed to load, we need to re-download it.
-    if (texture.state === 'failed') {
-      texture.free();
-      texture.freeTextureData();
-    }
-
     texture.setState('loading');
 
-    // Get the texture data
-    texture
-      .getTextureData()
-      .then(() => {
-        if (texture.state !== 'fetched') {
-          texture.setState('failed');
-          return;
-        }
-
-        // For non-image textures, upload immediately
-        if (texture.type !== TextureType.image) {
-          this.uploadTexture(texture).catch((err) => {
-            console.error('Failed to upload non-image texture:', err);
-            texture.setState('failed');
-          });
-        } else {
-          // For image textures, queue for throttled upload
-          // If it's a priority texture, upload it immediately
-          if (priority === true) {
-            this.uploadTexture(texture).catch((err) => {
-              console.error('Failed to upload priority texture:', err);
-              texture.setState('failed');
-            });
-          } else {
-            this.enqueueUploadTexture(texture);
-          }
-        }
-      })
-      .catch((err) => {
-        console.error(err);
+    // Get texture data - early return on failure
+    const textureDataResult = await texture.getTextureData().catch((err) => {
+      console.error(err);
+      texture.setState('failed');
+      return null;
+    });
+
+    // Early return if texture data fetch failed
+    if (textureDataResult === null || texture.state === 'failed') {
+      return;
+    }
+
+    // Handle non-image textures: upload immediately
+    const shouldUploadImmediately =
+      texture.type !== TextureType.image || priority === true;
+    if (shouldUploadImmediately === true) {
+      await this.uploadTexture(texture).catch((err) => {
+        console.error(`Failed to upload texture:`, err);
         texture.setState('failed');
       });
+      return;
+    }
+
+    // Queue image textures for throttled upload
+    this.enqueueUploadTexture(texture);
   }
 
   /**
@@ -431,6 +422,27 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
+    if (texture.state === 'failed' || texture.state === 'freed') {
+      // don't upload failed or freed textures
+      return;
+    }
+
+    if (texture.state === 'loaded') {
+      // already loaded
+      return;
+    }
+
+    if (texture.textureData === null) {
+      texture.setState(
+        'failed',
+        new TextureError(
+          TextureErrorCode.TEXTURE_DATA_NULL,
+          'Texture data is null, cannot upload texture',
+        ),
+      );
+      return;
+    }
+
     const coreContext = texture.loadCtxTexture();
     if (coreContext !== null && coreContext.state === 'loaded') {
       texture.setState('loaded');

package/src/core/Stage.ts

@@ -60,7 +60,7 @@ import type { RendererMainSettings } from '../main-api/Renderer.js';
 
 export type StageOptions = Omit<
   RendererMainSettings,
-  'inspector' | 'platform'
+  'inspector' | 'platform' | 'maxRetryCount'
 > & {
   textureMemory: TextureMemoryManagerSettings;
   canvas: HTMLCanvasElement | OffscreenCanvas;
@@ -68,6 +68,7 @@ export type StageOptions = Omit<
   eventBus: EventEmitter;
   platform: Platform | WebPlatform;
   inspector: boolean;
+  maxRetryCount: number;
 };
 
 export type StageFpsUpdateHandler = (
@@ -129,9 +130,12 @@ export class Stage {
   public readonly eventBus: EventEmitter;
 
   /// State
+  startTime = 0;
   deltaTime = 0;
   lastFrameTime = 0;
   currentFrameTime = 0;
+  elapsedTime = 0;
+  private timedNodes: CoreNode[] = [];
   private clrColor = 0x00000000;
   private fpsNumFrames = 0;
   private fpsElapsedTime = 0;
@@ -167,6 +171,7 @@ export class Stage {
       fontEngines,
       createImageBitmapSupport,
       platform,
+      maxRetryCount,
     } = options;
 
     assertTruthy(
@@ -176,6 +181,8 @@ export class Stage {
 
     this.platform = platform;
 
+    this.startTime = platform.getTimeStamp();
+
     this.eventBus = options.eventBus;
 
     // Calculate target frame time from targetFPS option
@@ -184,6 +191,7 @@ export class Stage {
     this.txManager = new CoreTextureManager(this, {
       numImageWorkers,
       createImageBitmapSupport,
+      maxRetryCount,
     });
 
     // Wait for the Texture Manager to initialize
@@ -335,7 +343,6 @@ export class Stage {
       colorBl: 0x00000000,
       colorBr: 0x00000000,
       zIndex: 0,
-      zIndexLocked: 0,
       scaleX: 1,
       scaleY: 1,
       mountX: 0,
@@ -383,9 +390,10 @@ export class Stage {
   }
 
   updateFrameTime() {
-    const newFrameTime = this.platform!.getTimeStamp();
+    const newFrameTime = this.platform.getTimeStamp();
     this.lastFrameTime = this.currentFrameTime;
     this.currentFrameTime = newFrameTime;
+    this.elapsedTime = this.startTime - newFrameTime;
     this.deltaTime = !this.lastFrameTime
       ? 100 / 6
       : newFrameTime - this.lastFrameTime;
@@ -417,7 +425,7 @@ export class Stage {
     // Mark the default texture as ALWAYS renderable
     // This prevents it from ever being cleaned up.
     // Fixes https://github.com/lightning-js/renderer/issues/262
-    this.defaultTexture.setRenderableOwner(this, true);
+    this.defaultTexture.setRenderableOwner('stage', true);
 
     // When the default texture is loaded, request a render in case the
     // RAF is paused. Fixes: https://github.com/lightning-js/renderer/issues/123
@@ -472,16 +480,6 @@ export class Stage {
     // Reset render operations and clear the canvas
     renderer.reset();
 
-    // Check if we need to cleanup textures
-    if (txMemManager.criticalCleanupRequested === true) {
-      txMemManager.cleanup(false);
-
-      if (txMemManager.criticalCleanupRequested === true) {
-        // If we still need to cleanup, request another but aggressive cleanup
-        txMemManager.cleanup(true);
-      }
-    }
-
     // If we have RTT nodes draw them first
     // So we can use them as textures in the main scene
     if (renderer.rttNodes.length > 0) {
@@ -501,6 +499,19 @@ export class Stage {
     if (renderRequested === true) {
       this.renderRequested = false;
     }
+
+    if (this.timedNodes.length > 0) {
+      for (let key in this.timedNodes) {
+        if (this.timedNodes[key]!.isRenderable === true) {
+          this.requestRender();
+          break;
+        }
+      }
+    }
+    // Check if we need to cleanup textures
+    if (this.txMemManager.criticalCleanupRequested === true) {
+      this.txMemManager.cleanup();
+    }
   }
 
   /**
@@ -764,6 +775,30 @@ export class Stage {
     return topNode || null;
   }
 
+  /**
+   * add node to timeNodes arrays
+   * @param node
+   * @returns
+   */
+  trackTimedNode(node: CoreNode) {
+    if (this.timedNodes[node.id] !== undefined) {
+      return;
+    }
+    this.timedNodes[node.id] = node;
+  }
+
+  /**
+   * remove node from timeNodes arrays
+   * @param node
+   * @returns
+   */
+  untrackTimedNode(node: CoreNode) {
+    if (this.timedNodes[node.id] === undefined) {
+      return;
+    }
+    delete this.timedNodes[node.id];
+  }
+
   /**
    * Resolves the default property values for a Node
    *
@@ -821,7 +856,6 @@ export class Stage {
       colorBl,
       colorBr,
       zIndex: props.zIndex ?? 0,
-      zIndexLocked: props.zIndexLocked ?? 0,
       parent: props.parent ?? null,
       texture: props.texture ?? null,
       textureOptions: props.textureOptions ?? {},
@@ -854,8 +888,8 @@ export class Stage {
    * @remarks
    * This method is used to cleanup orphaned textures that are no longer in use.
    */
-  cleanup(aggressive: boolean) {
-    this.txMemManager.cleanup(aggressive);
+  cleanup() {
+    this.txMemManager.cleanup();
   }
 
   set clearColor(value: number) {

package/src/core/TextureError.ts

@@ -0,0 +1,46 @@
+export enum TextureErrorCode {
+  MEMORY_THRESHOLD_EXCEEDED = 'MEMORY_THRESHOLD_EXCEEDED',
+  TEXTURE_DATA_NULL = 'TEXTURE_DATA_NULL',
+  TEXTURE_TYPE_NOT_REGISTERED = 'TEXTURE_TYPE_NOT_REGISTERED',
+}
+
+const defaultMessages: Record<TextureErrorCode, string> = {
+  [TextureErrorCode.MEMORY_THRESHOLD_EXCEEDED]: 'Memory threshold exceeded',
+  [TextureErrorCode.TEXTURE_DATA_NULL]: 'Texture data is null',
+  [TextureErrorCode.TEXTURE_TYPE_NOT_REGISTERED]:
+    'Texture type is not registered',
+};
+
+export class TextureError extends Error {
+  code?: TextureErrorCode;
+
+  constructor(message: string);
+  constructor(code: TextureErrorCode, message?: string);
+  constructor(codeOrMessage: TextureErrorCode | string, maybeMessage?: string) {
+    const isCode = Object.values(TextureErrorCode).includes(
+      codeOrMessage as TextureErrorCode,
+    );
+
+    const code = isCode ? (codeOrMessage as TextureErrorCode) : undefined;
+    let message: string;
+    if (isCode && code) {
+      message = maybeMessage ?? defaultMessages[code];
+    } else {
+      message = String(codeOrMessage);
+    }
+
+    super(message);
+    this.name = new.target.name;
+    if (code) this.code = code;
+  }
+}
+
+export function isTextureError(err: unknown): err is TextureError {
+  return (
+    err instanceof TextureError ||
+    (typeof err === 'object' &&
+      err !== null &&
+      (err as { name?: unknown }).name === 'TextureError' &&
+      typeof (err as { code?: unknown }).code === 'string')
+  );
+}