Refactor Texture Management and Garbage collection (#647)

This change improves the Texture Management and Garbage collection
routines.

To eliminate the "stuck texture" problem:


![IMG_9685](https://github.com/user-attachments/assets/4ce9f08b-2c00-47ec-a116-2c0f858d23f0)

Fixes:
    - Auto retry mechanism in case of failure
    - Expose retry API on texture to trigger manually
    - Expose max retry count property on texture
    - Fix stuck texture failure case
    - Reset dimensions on texture re-initialise
    - Fix GC race condition on starved CPUs
    - Optimized renderability toggling for faster loading
    - Remove old fetching/fetched states
- Extended Inspector to have more metrics surrounding texture loading
for easy debugging

Author: jfboeve

src/core/CoreNode.ts

@@ -27,6 +27,7 @@ import type { TextureOptions } from './CoreTextureManager.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
 import type { Stage } from './Stage.js';
 import {
+  TextureType,
   type Texture,
   type TextureFailedEventHandler,
   type TextureFreedEventHandler,
@@ -835,6 +836,7 @@ export class CoreNode extends EventEmitter {
 
       texture.preventCleanup =
         this.props.textureOptions?.preventCleanup ?? false;
+
       texture.on('loaded', this.onTextureLoaded);
       texture.on('failed', this.onTextureFailed);
       texture.on('freed', this.onTextureFreed);
@@ -866,7 +868,7 @@ export class CoreNode extends EventEmitter {
       this.texture.off('loaded', this.onTextureLoaded);
       this.texture.off('failed', this.onTextureFailed);
       this.texture.off('freed', this.onTextureFreed);
-      this.texture.setRenderableOwner(this, false);
+      this.texture.setRenderableOwner(this._id, false);
     }
   }
 
@@ -908,6 +910,7 @@ export class CoreNode extends EventEmitter {
     // immediately set isRenderable to false, so that we handle the error
     // without waiting for the next frame loop
     this.isRenderable = false;
+    this.updateTextureOwnership(false);
     this.setUpdateType(UpdateType.IsRenderable);
 
     // If parent has a render texture, flag that we need to update
@@ -925,6 +928,7 @@ export class CoreNode extends EventEmitter {
     // immediately set isRenderable to false, so that we handle the error
     // without waiting for the next frame loop
     this.isRenderable = false;
+    this.updateTextureOwnership(false);
     this.setUpdateType(UpdateType.IsRenderable);
 
     // If parent has a render texture, flag that we need to update
@@ -1506,7 +1510,7 @@ export class CoreNode extends EventEmitter {
    * Changes the renderable state of the node.
    */
   updateTextureOwnership(isRenderable: boolean) {
-    this.texture?.setRenderableOwner(this, isRenderable);
+    this.texture?.setRenderableOwner(this._id, isRenderable);
   }
 
   /**
@@ -2333,6 +2337,7 @@ export class CoreNode extends EventEmitter {
       sy: this.props.srcY,
       sw: this.props.srcWidth,
       sh: this.props.srcHeight,
+      maxRetryCount: this.props.textureOptions.maxRetryCount,
     });
   }
 
@@ -2418,13 +2423,12 @@ export class CoreNode extends EventEmitter {
 
     const oldTexture = this.props.texture;
     if (oldTexture) {
-      oldTexture.setRenderableOwner(this, false);
       this.unloadTexture();
     }
 
     this.props.texture = value;
     if (value !== null) {
-      value.setRenderableOwner(this, this.isRenderable);
+      value.setRenderableOwner(this._id, this.isRenderable);
       this.loadTexture();
     }
 

src/core/CoreTextureManager.ts

@@ -138,6 +138,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
    *
@@ -329,27 +343,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 {
-    this.stage.txMemManager.removeFromOrphanedTextures(texture);
-
+  async loadTexture(texture: Texture, priority?: boolean): Promise<void> {
     if (texture.type === TextureType.subTexture) {
       // ignore subtextures - they get loaded through their parent
       return;
@@ -360,7 +360,7 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
-    if (Texture.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)) {
+    if (texture.state === 'loading') {
       return;
     }
 
@@ -370,46 +370,33 @@ export class CoreTextureManager extends EventEmitter {
       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);
   }
 
   /**
@@ -424,11 +411,30 @@ export class CoreTextureManager extends EventEmitter {
       this.stage.txMemManager.criticalCleanupRequested === true
     ) {
       // we're at a critical memory threshold, don't upload textures
-      texture.setState('failed');
+      texture.setState('failed', new Error('Memory threshold exceeded'));
+      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 Error('Texture data is null, cannot upload texture'),
+      );
       return;
     }
 
     const coreContext = texture.loadCtxTexture();
+
     if (coreContext !== null && coreContext.state === 'loaded') {
       texture.setState('loaded');
       return;
@@ -529,18 +535,6 @@ export class CoreTextureManager extends EventEmitter {
     }
   }
 
-  /**
-   * Remove texture from the upload queue
-   *
-   * @param texture - The texture to remove
-   */
-  removeTextureFromQueue(texture: Texture): void {
-    const uploadIndex = this.uploadTextureQueue.indexOf(texture);
-    if (uploadIndex !== -1) {
-      this.uploadTextureQueue.splice(uploadIndex, 1);
-    }
-  }
-
   /**
    * Resolve a parent texture from the cache or fallback to the provided texture.
    *

src/core/Stage.ts

@@ -353,7 +353,6 @@ export class Stage {
    * Create default PixelTexture
    */
   createDefaultTexture() {
-    console.log('Creating default texture');
     (this.defaultTexture as ColorTexture) = this.txManager.createTexture(
       'ColorTexture',
       {
@@ -367,7 +366,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
@@ -422,16 +421,6 @@ export class Stage {
     // Reset render operations and clear the canvas
     renderer.reset();
 
-    // Check if we need to cleanup textures
-    if (this.txMemManager.criticalCleanupRequested === true) {
-      this.txMemManager.cleanup(false);
-
-      if (this.txMemManager.criticalCleanupRequested === true) {
-        // If we still need to cleanup, request another but aggressive cleanup
-        this.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) {
@@ -451,6 +440,11 @@ export class Stage {
     if (renderRequested) {
       this.renderRequested = false;
     }
+
+    // Check if we need to cleanup textures
+    if (this.txMemManager.criticalCleanupRequested === true) {
+      this.txMemManager.cleanup();
+    }
   }
 
   /**
@@ -815,12 +809,12 @@ export class Stage {
   }
 
   /**
-   * Cleanup Orphaned Textures
+   * Cleanup Unused Textures
    *
    * @remarks
-   * This method is used to cleanup orphaned textures that are no longer in use.
+   * This method is used to cleanup unused textures that are no longer in use.
    */
-  cleanup(aggressive: boolean) {
-    this.txMemManager.cleanup(aggressive);
+  cleanup() {
+    this.txMemManager.cleanup();
   }
 }