@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta20

package/src/core/CoreTextureManager.ts

@@ -24,14 +24,15 @@ import { ImageTexture } from './textures/ImageTexture.js';
 import { NoiseTexture } from './textures/NoiseTexture.js';
 import { SubTexture } from './textures/SubTexture.js';
 import { RenderTexture } from './textures/RenderTexture.js';
-import { TextureType, type Texture } from './textures/Texture.js';
+import { Texture, TextureType } from './textures/Texture.js';
 import { EventEmitter } from '../common/EventEmitter.js';
-import { getTimeStamp } from './platform.js';
 import type { Stage } from './Stage.js';
 import {
   validateCreateImageBitmap,
   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,15 +194,17 @@ export class CoreTextureManager extends EventEmitter {
    */
   txConstructors: Partial<TextureMap> = {};
 
-  private downloadTextureSourceQueue: Array<Texture> = [];
+  public maxRetryCount: number;
   private priorityQueue: Array<Texture> = [];
   private uploadTextureQueue: Array<Texture> = [];
   private initialized = false;
   private stage: Stage;
   private numImageWorkers: number;
 
+  public platform: Platform;
+
   imageWorkerManager: ImageWorkerManager | null = null;
-  hasCreateImageBitmap = !!self.createImageBitmap;
+  hasCreateImageBitmap = false;
   imageBitmapSupported = {
     basic: false,
     options: false,
@@ -217,16 +235,20 @@ 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()
+      validateCreateImageBitmap(this.platform)
         .then((result) => {
           this.initialize(result);
         })
-        .catch((e) => {
+        .catch(() => {
           console.warn(
             '[Lightning] createImageBitmap is not supported on this browser. ImageTexture will be slower.',
           );
@@ -262,15 +284,15 @@ export class CoreTextureManager extends EventEmitter {
       support.basic || support.options || support.full;
     this.imageBitmapSupported = support;
 
-    if (!this.hasCreateImageBitmap) {
+    if (this.hasCreateImageBitmap === false) {
       console.warn(
         '[Lightning] createImageBitmap is not supported on this browser. ImageTexture will be slower.',
       );
     }
 
     if (
-      this.hasCreateImageBitmap &&
-      this.hasWorker &&
+      this.hasCreateImageBitmap === true &&
+      this.hasWorker === true &&
       this.numImageWorkers > 0
     ) {
       this.imageWorkerManager = new ImageWorkerManager(
@@ -287,15 +309,6 @@ export class CoreTextureManager extends EventEmitter {
     this.emit('initialized');
   }
 
-  /**
-   * Enqueue a texture for downloading its source image.
-   */
-  enqueueDownloadTextureSource(texture: Texture): void {
-    if (!this.downloadTextureSourceQueue.includes(texture)) {
-      this.downloadTextureSourceQueue.push(texture);
-    }
-  }
-
   /**
    * Enqueue a texture for uploading to the GPU.
    *
@@ -322,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);
@@ -339,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) {
@@ -365,87 +366,80 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
-    // if the texture is already loaded, don't load it again
-    if (
-      texture.ctxTexture !== undefined &&
-      texture.ctxTexture.state === 'loaded'
-    ) {
-      texture.setState('loaded');
+    if (texture.state === 'loaded') {
+      // if the texture is already loaded, just return
       return;
     }
 
-    // if the texture is already being processed, don't load it again
-    if (
-      this.downloadTextureSourceQueue.includes(texture) === true ||
-      this.uploadTextureQueue.includes(texture) === true
-    ) {
-      return;
-    }
-
-    // if the texture is already loading, free it, this can happen if the texture is
-    // orphaned and then reloaded
-    if (
-      texture.ctxTexture !== undefined &&
-      texture.ctxTexture.state === 'loading'
-    ) {
-      // if the texture has texture data, queue it for upload
-      if (texture.textureData !== null) {
-        this.enqueueUploadTexture(texture);
-      }
-
-      // else we will have to re-download the texture
-      texture.free();
-    }
-
     // if we're not initialized, just queue the texture into the priority queue
     if (this.initialized === false) {
       this.priorityQueue.push(texture);
       return;
     }
 
-    // these types of textures don't need to be downloaded
-    // Technically the noise texture shouldn't either, but it's a special case
-    // and not really used in production so who cares ¯\_(ツ)_/¯
-    if (
-      (texture.type === TextureType.color ||
-        texture.type === TextureType.renderToTexture) &&
-      texture.state !== 'initial'
-    ) {
-      texture.setState('fetched');
-      this.enqueueUploadTexture(texture);
+    texture.setState('loading');
+
+    // 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;
     }
 
-    texture.setState('loading');
-
-    // prioritize the texture for immediate loading
-    if (priority === true) {
-      texture
-        .getTextureData()
-        .then(() => {
-          this.uploadTexture(texture);
-        })
-        .catch((err) => {
-          console.error(err);
-        });
+    // 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;
     }
 
-    // enqueue the texture for download and upload
-    this.enqueueDownloadTextureSource(texture);
+    // Queue image textures for throttled upload
+    this.enqueueUploadTexture(texture);
   }
 
   /**
    * Upload a texture to the GPU
    *
    * @param texture Texture to upload
+   * @returns Promise that resolves when the texture is fully loaded
    */
-  uploadTexture(texture: Texture): void {
+  async uploadTexture(texture: Texture): Promise<void> {
     if (
       this.stage.txMemManager.doNotExceedCriticalThreshold === true &&
       this.stage.txMemManager.criticalCleanupRequested === true
     ) {
       // we're at a critical memory threshold, don't upload textures
-      this.enqueueUploadTexture(texture);
+      texture.setState('failed');
+      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;
     }
 
@@ -455,72 +449,63 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
-    coreContext.load();
+    await coreContext.load();
   }
 
   /**
    * Check if a texture is being processed
    */
   isProcessingTexture(texture: Texture): boolean {
-    return (
-      this.downloadTextureSourceQueue.includes(texture) === true ||
-      this.uploadTextureQueue.includes(texture) === true
-    );
+    return this.uploadTextureQueue.includes(texture) === true;
   }
 
   /**
-   * Process a limited number of downloads and uploads.
+   * Process a limited number of uploads.
    *
-   * @param maxItems - The maximum number of items to process
+   * @param maxProcessingTime - The maximum processing time in milliseconds
    */
-  processSome(maxProcessingTime: number): void {
+  async processSome(maxProcessingTime: number): Promise<void> {
     if (this.initialized === false) {
       return;
     }
 
-    const startTime = getTimeStamp();
+    const platform = this.platform;
+    const startTime = platform.getTimeStamp();
 
     // Process priority queue
     while (
       this.priorityQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
+      platform.getTimeStamp() - startTime < maxProcessingTime
     ) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const texture = this.priorityQueue.pop()!;
-      texture.getTextureData().then(() => {
-        this.uploadTexture(texture);
-      });
+      try {
+        await texture.getTextureData();
+        await this.uploadTexture(texture);
+      } catch (error) {
+        console.error('Failed to process priority texture:', error);
+        // Continue with next texture instead of stopping entire queue
+      }
     }
 
-    // Process uploads
+    // Process uploads - await each upload to prevent GPU overload
     while (
       this.uploadTextureQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
+      platform.getTimeStamp() - startTime < maxProcessingTime
     ) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.uploadTexture(this.uploadTextureQueue.pop()!);
-    }
-
-    // Process downloads
-    while (
-      this.downloadTextureSourceQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
-    ) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const texture = this.downloadTextureSourceQueue.shift()!;
-      texture.getTextureData().then(() => {
-        if (texture.state === 'fetched') {
-          this.enqueueUploadTexture(texture);
-        }
-      });
+      const texture = this.uploadTextureQueue.shift()!;
+      try {
+        await this.uploadTexture(texture);
+      } catch (error) {
+        console.error('Failed to upload texture:', error);
+        // Continue with next texture instead of stopping entire queue
+      }
     }
   }
 
   public hasUpdates(): boolean {
-    return (
-      this.downloadTextureSourceQueue.length > 0 ||
-      this.uploadTextureQueue.length > 0
-    );
+    return this.uploadTextureQueue.length > 0;
   }
 
   /**
@@ -561,16 +546,11 @@ export class CoreTextureManager extends EventEmitter {
   }
 
   /**
-   * Remove texture from the queue's
+   * Remove texture from the upload queue
    *
    * @param texture - The texture to remove
    */
   removeTextureFromQueue(texture: Texture): void {
-    const downloadIndex = this.downloadTextureSourceQueue.indexOf(texture);
-    if (downloadIndex !== -1) {
-      this.downloadTextureSourceQueue.splice(downloadIndex, 1);
-    }
-
     const uploadIndex = this.uploadTextureQueue.indexOf(texture);
     if (uploadIndex !== -1) {
       this.uploadTextureQueue.splice(uploadIndex, 1);