@lightningjs/renderer 2.18.2 → 2.18.4

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')
+  );
+}

package/src/core/TextureMemoryManager.ts

@@ -122,7 +122,7 @@ export class TextureMemoryManager {
   private debugLogging: boolean;
   private lastCleanupTime = 0;
   private baselineMemoryAllocation: number;
-  private needsDefrag = false;
+  private hasWarnedAboveCritical = false;
 
   public criticalCleanupRequested = false;
   public doNotExceedCriticalThreshold: boolean;
@@ -191,11 +191,10 @@ export class TextureMemoryManager {
     this.memUsed -= texture.memUsed;
 
     if (byteSize === 0) {
-      // PERFORMANCE: Mark for deletion instead of splice (zero overhead)
+      // PERFORMANCE: Mark for deletion, slot will be reused later
       const index = this.loadedTextures.indexOf(texture);
       if (index !== -1) {
         this.loadedTextures[index] = null;
-        this.needsDefrag = true;
       }
       texture.memUsed = 0;
       return;
@@ -204,7 +203,13 @@ export class TextureMemoryManager {
       texture.memUsed = byteSize;
       this.memUsed += byteSize;
       if (this.loadedTextures.indexOf(texture) === -1) {
-        this.loadedTextures.push(texture);
+        // PERFORMANCE: Reuse empty slots before appending
+        const emptyIndex = this.loadedTextures.indexOf(null);
+        if (emptyIndex !== -1) {
+          this.loadedTextures[emptyIndex] = texture;
+        } else {
+          this.loadedTextures.push(texture);
+        }
       }
     }
 
@@ -225,19 +230,6 @@ export class TextureMemoryManager {
     return this.memUsed > this.criticalThreshold;
   }
 
-  /**
-   * Check if defragmentation is needed
-   *
-   * @remarks
-   * Returns true if the loadedTextures array has null entries that need
-   * to be compacted. Called by platform during idle periods.
-   *
-   * @returns true if defragmentation should be performed
-   */
-  checkDefrag() {
-    return this.needsDefrag;
-  }
-
   /**
    * Destroy a texture and null out its array position
    *
@@ -250,11 +242,10 @@ export class TextureMemoryManager {
       );
     }
 
-    // PERFORMANCE: Null out array position instead of splice (zero overhead)
+    // PERFORMANCE: Null out array position, slot will be reused later
     const index = this.loadedTextures.indexOf(texture);
     if (index !== -1) {
       this.loadedTextures[index] = null;
-      this.needsDefrag = true;
     }
 
     // Destroy texture and update memory counters
@@ -323,48 +314,23 @@ export class TextureMemoryManager {
         memUsed: this.memUsed,
         criticalThreshold: this.criticalThreshold,
       });
-
-      if (this.debugLogging === true || isProductionEnvironment() === false) {
+      // Only emit the warning once per over-threshold period
+      if (
+        !this.hasWarnedAboveCritical &&
+        (this.debugLogging === true || isProductionEnvironment() === false)
+      ) {
         console.warn(
           `[TextureMemoryManager] Memory usage above critical threshold after cleanup: ${this.memUsed}`,
         );
+
+        this.hasWarnedAboveCritical = true;
       }
     } else {
       this.criticalCleanupRequested = false;
+      this.hasWarnedAboveCritical = false;
     }
   }
 
-  /**
-   * Defragment the loadedTextures array by removing null entries
-   *
-   * @remarks
-   * This should be called during idle periods to compact the array
-   * after null-marking deletions. Zero overhead during critical cleanup.
-   */
-  defragment() {
-    if (!this.needsDefrag) {
-      return;
-    }
-
-    // PERFORMANCE: Single-pass compaction
-    let writeIndex = 0;
-    for (
-      let readIndex = 0;
-      readIndex < this.loadedTextures.length;
-      readIndex++
-    ) {
-      const texture = this.loadedTextures[readIndex];
-      if (texture !== null && texture !== undefined) {
-        this.loadedTextures[writeIndex] = texture;
-        writeIndex++;
-      }
-    }
-
-    // Trim array to new size
-    this.loadedTextures.length = writeIndex;
-    this.needsDefrag = false;
-  }
-
   /**
    * Get the current texture memory usage information
    *

package/src/core/platform.ts

@@ -66,10 +66,6 @@ export const startLoop = (stage: Stage) => {
         stage.txMemManager.cleanup();
       }
 
-      if (stage.txMemManager.checkDefrag() === true) {
-        stage.txMemManager.defragment();
-      }
-
       stage.flushFrameEvents();
       return;
     }

package/src/core/textures/ImageTexture.ts

@@ -138,7 +138,8 @@ export class ImageTexture extends Texture {
     const resolvedProps = ImageTexture.resolveDefaults(props);
     super(txManager);
     this.props = resolvedProps;
-    this.maxRetryCount = resolvedProps.maxRetryCount ?? 5;
+    this.maxRetryCount =
+      resolvedProps.maxRetryCount ?? this.txManager.maxRetryCount;
   }
 
   hasAlphaChannel(mimeType: string) {
@@ -407,7 +408,7 @@ export class ImageTexture extends Texture {
       sy: props.sy ?? null,
       sw: props.sw ?? null,
       sh: props.sh ?? null,
-      maxRetryCount: props.maxRetryCount ?? 5,
+      maxRetryCount: props.maxRetryCount ?? null,
     };
   }
 

package/src/core/textures/SubTexture.ts

@@ -137,6 +137,8 @@ export class SubTexture extends Texture {
   };
 
   private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
+    //decrement with 1 because in the failed state it will do +1 again.
+    this.retryCount = this.parentTexture.retryCount - 1;
     this.forwardParentTxState('failed', error);
   };
 

package/src/core/textures/Texture.ts

@@ -22,6 +22,7 @@ import type { SubTextureProps } from './SubTexture.js';
 import type { Dimensions } from '../../common/CommonTypes.js';
 import { EventEmitter } from '../../common/EventEmitter.js';
 import type { CoreContextTexture } from '../renderers/CoreContextTexture.js';
+import type { TextureError } from '../TextureError.js';
 
 /**
  * Event handler for when a Texture is freed
@@ -135,7 +136,7 @@ export abstract class Texture extends EventEmitter {
    * `null`.
    */
   private _dimensions: Dimensions | null = null;
-  private _error: Error | null = null;
+  private _error: TextureError | null = null;
 
   // aggregate state
   public state: TextureState = 'initial';
@@ -162,7 +163,7 @@ export abstract class Texture extends EventEmitter {
   public memUsed = 0;
 
   public retryCount = 0;
-  public maxRetryCount: number = 5;
+  public maxRetryCount: number;
 
   /**
    * Timestamp when texture was created (for startup grace period)
@@ -182,13 +183,14 @@ export abstract class Texture extends EventEmitter {
 
   constructor(protected txManager: CoreTextureManager) {
     super();
+    this.maxRetryCount = txManager.maxRetryCount;
   }
 
   get dimensions(): Dimensions | null {
     return this._dimensions;
   }
 
-  get error(): Error | null {
+  get error(): TextureError | null {
     return this._error;
   }
 

package/src/main-api/Inspector.ts

@@ -533,7 +533,10 @@ export class Inspector {
 
     // Update error information if present
     if (texture.error) {
-      div.setAttribute('data-texture-error', texture.error.message);
+      div.setAttribute(
+        'data-texture-error',
+        texture.error.code || texture.error.message,
+      );
     } else {
       div.removeAttribute('data-texture-error');
     }

package/src/main-api/Renderer.ts

@@ -329,6 +329,20 @@ export interface RendererMainSettings {
    * @defaultValue `full`
    */
   createImageBitmapSupport?: 'auto' | 'basic' | 'options' | 'full';
+
+  /**
+   * 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;
 }
 
 /**
@@ -432,6 +446,7 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 42,
       canvas: settings.canvas || document.createElement('canvas'),
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+      maxRetryCount: settings.maxRetryCount ?? 5,
     };
     this.settings = resolvedSettings;
 
@@ -477,6 +492,7 @@ export class RendererMain extends EventEmitter {
       strictBounds: this.settings.strictBounds,
       textureProcessingTimeLimit: this.settings.textureProcessingTimeLimit,
       createImageBitmapSupport: this.settings.createImageBitmapSupport,
+      maxRetryCount: this.settings.maxRetryCount,
     });
 
     // Extract the root node

package/dist/src/core/renderers/webgl/WebGlCoreShader.destroy.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/core/renderers/webgl/WebGlCoreShader.destroy.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=WebGlCoreShader.destroy.js.map

package/dist/src/core/renderers/webgl/WebGlCoreShader.destroy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"WebGlCoreShader.destroy.js","sourceRoot":"","sources":["../../../../../src/core/renderers/webgl/WebGlCoreShader.destroy.ts"],"names":[],"mappings":""}