@lightningtv/renderer 3.0.0-beta1 → 3.2.4

package/src/core/CoreTextureManager.ts

@@ -1,22 +1,3 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import { ImageWorkerManager } from './lib/ImageWorker.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
 import { ColorTexture } from './textures/ColorTexture.js';
@@ -24,14 +5,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 +46,7 @@ export interface TextureManagerDebugInfo {
 export interface TextureManagerSettings {
   numImageWorkers: number;
   createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
+  maxRetryCount: number;
 }
 
 export type ResizeModeOptions =
@@ -138,6 +121,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 +175,16 @@ export class CoreTextureManager extends EventEmitter {
    */
   txConstructors: Partial<TextureMap> = {};
 
-  private downloadTextureSourceQueue: Array<Texture> = [];
-  private priorityQueue: Array<Texture> = [];
-  private uploadTextureQueue: Array<Texture> = [];
+  public maxRetryCount: number;
+  private uploadTextureQueue: Set<Texture> = new Set();
   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 +215,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 +264,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,24 +289,13 @@ 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.
    *
    * @param texture - The texture to upload
    */
   enqueueUploadTexture(texture: Texture): void {
-    if (this.uploadTextureQueue.includes(texture) === false) {
-      this.uploadTextureQueue.push(texture);
-    }
+    this.uploadTextureQueue.add(texture);
   }
 
   /**
@@ -320,16 +311,19 @@ export class CoreTextureManager extends EventEmitter {
     let texture: Texture | undefined;
     const TextureClass = this.txConstructors[textureType];
     if (!TextureClass) {
-      throw new Error(`Texture type "${textureType}" is not registered`);
+      throw new TextureError(
+        TextureErrorCode.TEXTURE_TYPE_NOT_REGISTERED,
+        `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 +333,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 +347,89 @@ 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
-    ) {
+    // if we're not initialized, just queue the texture into the upload queue
+    if (this.initialized === false) {
+      this.uploadTextureQueue.add(texture);
       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);
-      }
+    texture.setState('loading');
 
-      // else we will have to re-download the texture
-      texture.free();
-    }
+    // Get texture data - early return on failure
+    const textureDataResult = await texture.getTextureData().catch((err) => {
+      console.error(err);
+      texture.setState(
+        'failed',
+        new TextureError(TextureErrorCode.TEXTURE_DATA_NULL),
+      );
+      return null;
+    });
 
-    // if we're not initialized, just queue the texture into the priority queue
-    if (this.initialized === false) {
-      this.priorityQueue.push(texture);
+    // Early return if texture data fetch failed
+    if (textureDataResult === null || texture.state === 'failed') {
       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);
+    // 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',
+          new TextureError(TextureErrorCode.TEXTURE_DATA_NULL),
+        );
+      });
       return;
     }
 
-    texture.setState('loading');
-
-    // prioritize the texture for immediate loading
-    if (priority === true) {
-      texture
-        .getTextureData()
-        .then(() => {
-          this.uploadTexture(texture);
-        })
-        .catch((err) => {
-          console.error(err);
-        });
-    }
-
-    // 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',
+        new TextureError(TextureErrorCode.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 TextureError(
+          TextureErrorCode.TEXTURE_DATA_NULL,
+          'Texture data is null, cannot upload texture',
+        ),
+      );
       return;
     }
 
@@ -455,72 +439,51 @@ 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.has(texture);
   }
 
   /**
-   * 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();
-
-    // Process priority queue
-    while (
-      this.priorityQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
-    ) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const texture = this.priorityQueue.pop()!;
-      texture.getTextureData().then(() => {
-        this.uploadTexture(texture);
-      });
-    }
-
-    // Process uploads
-    while (
-      this.uploadTextureQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
-    ) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.uploadTexture(this.uploadTextureQueue.pop()!);
-    }
+    const platform = this.platform;
+    const startTime = platform.getTimeStamp();
 
-    // Process downloads
+    // Process uploads - await each upload to prevent GPU overload
     while (
-      this.downloadTextureSourceQueue.length > 0 &&
-      getTimeStamp() - startTime < maxProcessingTime
+      this.uploadTextureQueue.size > 0 &&
+      platform.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;
+      if (!texture) break;
+      this.uploadTextureQueue.delete(texture);
+      try {
+        if (texture.textureData === null) {
+          await texture.getTextureData();
         }
-      });
+        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.size > 0;
   }
 
   /**
@@ -561,20 +524,12 @@ 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);
-    }
+    this.uploadTextureQueue.delete(texture);
   }
 
   /**