@lightningjs/renderer 2.17.0 → 2.18.0

package/src/core/TextureMemoryManager.ts

@@ -17,9 +17,8 @@
  * limitations under the License.
  */
 import { isProductionEnvironment } from '../utils.js';
-import { getTimeStamp } from './platform.js';
 import type { Stage } from './Stage.js';
-import { Texture, TextureType, type TextureState } from './textures/Texture.js';
+import { Texture, TextureType } from './textures/Texture.js';
 import { bytesToMb } from './utils.js';
 
 export interface TextureMemoryManagerSettings {
@@ -116,14 +115,14 @@ export interface MemoryInfo {
  */
 export class TextureMemoryManager {
   private memUsed = 0;
-  private loadedTextures: Map<Texture, number> = new Map();
-  private orphanedTextures: Texture[] = [];
+  private loadedTextures: (Texture | null)[] = [];
   private criticalThreshold: number;
   private targetThreshold: number;
   private cleanupInterval: number;
   private debugLogging: boolean;
   private lastCleanupTime = 0;
   private baselineMemoryAllocation: number;
+  private needsDefrag = false;
 
   public criticalCleanupRequested = false;
   public doNotExceedCriticalThreshold: boolean;
@@ -181,35 +180,6 @@ export class TextureMemoryManager {
     }
   }
 
-  /**
-   * Add a texture to the orphaned textures list
-   *
-   * @param texture - The texture to add to the orphaned textures list
-   */
-  addToOrphanedTextures(texture: Texture) {
-    // if the texture is already in the orphaned textures list add it at the end
-    if (this.orphanedTextures.includes(texture)) {
-      this.removeFromOrphanedTextures(texture);
-    }
-
-    // If the texture can be cleaned up, add it to the orphaned textures list
-    if (texture.preventCleanup === false) {
-      this.orphanedTextures.push(texture);
-    }
-  }
-
-  /**
-   * Remove a texture from the orphaned textures list
-   *
-   * @param texture - The texture to remove from the orphaned textures list
-   */
-  removeFromOrphanedTextures(texture: Texture) {
-    const index = this.orphanedTextures.indexOf(texture);
-    if (index !== -1) {
-      this.orphanedTextures.splice(index, 1);
-    }
-  }
-
   /**
    * Set the memory usage of a texture
    *
@@ -217,17 +187,25 @@ export class TextureMemoryManager {
    * @param byteSize - The size of the texture in bytes
    */
   setTextureMemUse(texture: Texture, byteSize: number) {
-    if (this.loadedTextures.has(texture)) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.memUsed -= this.loadedTextures.get(texture)!;
-    }
+    // Update global memory counter by subtracting old value
+    this.memUsed -= texture.memUsed;
 
     if (byteSize === 0) {
-      this.loadedTextures.delete(texture);
+      // PERFORMANCE: Mark for deletion instead of splice (zero overhead)
+      const index = this.loadedTextures.indexOf(texture);
+      if (index !== -1) {
+        this.loadedTextures[index] = null;
+        this.needsDefrag = true;
+      }
+      texture.memUsed = 0;
       return;
     } else {
+      // Update texture memory and add to tracking if not already present
+      texture.memUsed = byteSize;
       this.memUsed += byteSize;
-      this.loadedTextures.set(texture, byteSize);
+      if (this.loadedTextures.indexOf(texture) === -1) {
+        this.loadedTextures.push(texture);
+      }
     }
 
     if (this.memUsed > this.criticalThreshold) {
@@ -247,42 +225,21 @@ export class TextureMemoryManager {
     return this.memUsed > this.criticalThreshold;
   }
 
-  cleanupQuick(critical: boolean) {
-    // Free non-renderable textures until we reach the target threshold
-    const memTarget = this.targetThreshold;
-    const timestamp = getTimeStamp();
-
-    while (
-      this.memUsed >= memTarget &&
-      this.orphanedTextures.length > 0 &&
-      (critical || getTimeStamp() - timestamp < 10)
-    ) {
-      const texture = this.orphanedTextures.shift();
-
-      if (texture === undefined) {
-        continue;
-      }
-
-      if (texture.renderable === true) {
-        // If the texture is renderable, we can't free it up
-        continue;
-      }
-
-      // Skip textures that are in transitional states - we only want to clean up
-      // textures that are in a stable state (loaded, failed, or freed)
-      if (
-        texture.state === 'initial' ||
-        Texture.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)
-      ) {
-        continue;
-      }
-
-      this.destroyTexture(texture);
-    }
+  /**
+   * 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 remove it from the memory manager
+   * Destroy a texture and null out its array position
    *
    * @param texture - The texture to destroy
    */
@@ -293,46 +250,25 @@ export class TextureMemoryManager {
       );
     }
 
+    // PERFORMANCE: Null out array position instead of splice (zero overhead)
+    const index = this.loadedTextures.indexOf(texture);
+    if (index !== -1) {
+      this.loadedTextures[index] = null;
+      this.needsDefrag = true;
+    }
+
+    // Destroy texture and update memory counters
     const txManager = this.stage.txManager;
-    txManager.removeTextureFromQueue(texture);
     txManager.removeTextureFromCache(texture);
 
     texture.destroy();
 
-    this.removeFromOrphanedTextures(texture);
-    this.loadedTextures.delete(texture);
-  }
-  cleanupDeep(critical: boolean) {
-    // Free non-renderable textures until we reach the target threshold
-    const memTarget = critical ? this.criticalThreshold : this.targetThreshold;
-
-    // Filter for textures that are candidates for cleanup
-    // note: This is an expensive operation, so we only do it in deep cleanup
-    const cleanupCandidates = [...this.loadedTextures.keys()].filter(
-      (texture) => {
-        return (
-          (texture.type === TextureType.image ||
-            texture.type === TextureType.noise ||
-            texture.type === TextureType.renderToTexture) &&
-          texture.renderable === false &&
-          texture.preventCleanup === false &&
-          texture.state !== 'initial' &&
-          !Texture.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)
-        );
-      },
-    );
-
-    while (this.memUsed >= memTarget && cleanupCandidates.length > 0) {
-      const texture = cleanupCandidates.shift();
-      if (texture === undefined) {
-        continue;
-      }
-
-      this.destroyTexture(texture);
-    }
+    // Update memory counters
+    this.memUsed -= texture.memUsed;
+    texture.memUsed = 0;
   }
 
-  cleanup(aggressive: boolean = false) {
+  cleanup() {
     const critical = this.criticalCleanupRequested;
     this.lastCleanupTime = this.frameTime;
 
@@ -345,25 +281,41 @@ export class TextureMemoryManager {
 
     if (this.debugLogging === true) {
       console.log(
-        `[TextureMemoryManager] Cleaning up textures. Critical: ${critical}. Aggressive: ${aggressive}`,
+        `[TextureMemoryManager] Cleaning up textures. Critical: ${critical}.`,
       );
     }
 
-    // Note: We skip textures in transitional states during cleanup:
-    // - 'initial': These textures haven't started loading yet
-    // - 'fetching': These textures are in the process of being fetched
-    // - 'fetched': These textures have been fetched but not yet uploaded to GPU
-    // - 'loading': These textures are being uploaded to the GPU
-    //
-    // For 'failed' and 'freed' states, we only remove them from the tracking
-    // arrays without trying to free GPU resources that don't exist.
-
-    // try a quick cleanup first
-    this.cleanupQuick(critical);
-
-    // if we're still above the target threshold, do a deep cleanup
-    if (aggressive === true && this.memUsed >= this.criticalThreshold) {
-      this.cleanupDeep(critical);
+    // Free non-renderable textures until we reach the target threshold
+    const memTarget = critical ? this.criticalThreshold : this.targetThreshold;
+
+    // PERFORMANCE: Zero-overhead cleanup with null marking
+    // Skip null entries, mark cleaned textures as null for later defrag
+    let currentMemUsed = this.memUsed;
+
+    for (let i = 0; i < this.loadedTextures.length; i++) {
+      // Early exit: target memory reached
+      if (currentMemUsed < memTarget) {
+        break;
+      }
+
+      const texture = this.loadedTextures[i];
+      if (!texture) continue; // Skip null entries from previous deletions
+
+      // Fast type check for cleanable textures
+      const isCleanableType =
+        texture.type === TextureType.image ||
+        texture.type === TextureType.noise ||
+        texture.type === TextureType.renderToTexture;
+
+      // Immediate cleanup if eligible
+      if (isCleanableType && texture.canBeCleanedUp() === true) {
+        // Get memory before destroying
+        const textureMemory = texture.memUsed;
+
+        // Destroy texture (which will null out the array position)
+        this.destroyTexture(texture);
+        currentMemUsed -= textureMemory;
+      }
     }
 
     if (this.memUsed >= this.criticalThreshold) {
@@ -382,6 +334,37 @@ export class TextureMemoryManager {
     }
   }
 
+  /**
+   * 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
    *
@@ -391,15 +374,19 @@ export class TextureMemoryManager {
    */
   getMemoryInfo(): MemoryInfo {
     let renderableTexturesLoaded = 0;
-    const renderableMemUsed = [...this.loadedTextures.keys()].reduce(
-      (acc, texture) => {
-        renderableTexturesLoaded += texture.renderable ? 1 : 0;
-        // Get the memory used by the texture, defaulting to 0 if not found
-        const textureMemory = this.loadedTextures.get(texture) ?? 0;
-        return acc + (texture.renderable ? textureMemory : 0);
-      },
-      this.baselineMemoryAllocation,
-    );
+    let renderableMemUsed = this.baselineMemoryAllocation;
+
+    for (const texture of this.loadedTextures) {
+      if (texture && texture.renderable) {
+        renderableTexturesLoaded += 1;
+        renderableMemUsed += texture.memUsed;
+      }
+    }
+
+    // Count non-null entries for accurate loaded texture count
+    const actualLoadedTextures = this.loadedTextures.filter(
+      (t) => t !== null,
+    ).length;
 
     return {
       criticalThreshold: this.criticalThreshold,
@@ -407,7 +394,7 @@ export class TextureMemoryManager {
       renderableMemUsed,
       memUsed: this.memUsed,
       renderableTexturesLoaded,
-      loadedTextures: this.loadedTextures.size,
+      loadedTextures: actualLoadedTextures,
       baselineMemoryAllocation: this.baselineMemoryAllocation,
     };
   }

package/src/core/lib/WebGlContextWrapper.ts

@@ -1277,6 +1277,44 @@ export class WebGlContextWrapper {
     const { gl } = this;
     gl.deleteShader(shader);
   }
+
+  /**
+   * Check for WebGL errors and return error information
+   * @param operation Description of the operation for error reporting
+   * @returns Object with error information or null if no error
+   */
+  checkError(
+    operation: string,
+  ): { error: number; errorName: string; message: string } | null {
+    const error = this.getError();
+    if (error !== 0) {
+      // 0 is GL_NO_ERROR
+      let errorName = 'UNKNOWN_ERROR';
+      switch (error) {
+        case this.INVALID_ENUM:
+          errorName = 'INVALID_ENUM';
+          break;
+        case 0x0501: // GL_INVALID_VALUE
+          errorName = 'INVALID_VALUE';
+          break;
+        case this.INVALID_OPERATION:
+          errorName = 'INVALID_OPERATION';
+          break;
+        case 0x0505: // GL_OUT_OF_MEMORY
+          errorName = 'OUT_OF_MEMORY';
+          break;
+        case 0x9242: // GL_CONTEXT_LOST_WEBGL
+          errorName = 'CONTEXT_LOST_WEBGL';
+          break;
+      }
+
+      const message = `WebGL ${errorName} (0x${error.toString(
+        16,
+      )}) during ${operation}`;
+      return { error, errorName, message };
+    }
+    return null;
+  }
 }
 
 // prettier-ignore

package/src/core/lib/textureCompression.ts

@@ -39,14 +39,25 @@ export function isCompressedTextureContainer(url: string): boolean {
 export const loadCompressedTexture = async (
   url: string,
 ): Promise<TextureData> => {
-  const response = await fetch(url);
-  const arrayBuffer = await response.arrayBuffer();
+  try {
+    const response = await fetch(url);
 
-  if (url.indexOf('.ktx') !== -1) {
-    return loadKTXData(arrayBuffer);
-  }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch compressed texture: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+
+    if (url.indexOf('.ktx') !== -1) {
+      return loadKTXData(arrayBuffer);
+    }
 
-  return loadPVRData(arrayBuffer);
+    return loadPVRData(arrayBuffer);
+  } catch (error) {
+    throw new Error(`Failed to load compressed texture from ${url}: ${error}`);
+  }
 };
 
 /**
@@ -111,7 +122,7 @@ const loadPVRData = async (buffer: ArrayBuffer): Promise<TextureData> => {
   const header = new Int32Array(arrayBuffer, 0, pvrHeaderLength);
 
   // @ts-expect-error Object possibly undefined
-  // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+
   const dataOffset = header[pvrMetadata] + 52;
   const pvrtcData = new Uint8Array(arrayBuffer, dataOffset);
   const mipmaps = [];

package/src/core/platform.ts

@@ -63,7 +63,11 @@ export const startLoop = (stage: Stage) => {
       }
 
       if (stage.txMemManager.checkCleanup() === true) {
-        stage.txMemManager.cleanup(false);
+        stage.txMemManager.cleanup();
+      }
+
+      if (stage.txMemManager.checkDefrag() === true) {
+        stage.txMemManager.defragment();
       }
 
       stage.flushFrameEvents();

package/src/core/renderers/CoreContextTexture.ts

@@ -35,6 +35,7 @@ export abstract class CoreContextTexture {
   }
 
   abstract load(): Promise<void>;
+  abstract release(): void;
   abstract free(): void;
 
   get renderable(): boolean {

package/src/core/renderers/canvas/CanvasCoreTexture.ts

@@ -41,18 +41,20 @@ export class CanvasCoreTexture extends CoreContextTexture {
     try {
       const size = await this.onLoadRequest();
       this.textureSource.setState('loaded', size);
-      this.textureSource.freeTextureData();
       this.updateMemSize();
     } catch (err) {
       this.textureSource.setState('failed', err as Error);
-      this.textureSource.freeTextureData();
       throw err;
     }
   }
 
-  free(): void {
+  release(): void {
     this.image = undefined;
     this.tintCache = undefined;
+  }
+
+  free(): void {
+    this.release();
     this.textureSource.setState('freed');
     this.setTextureMemUse(0);
     this.textureSource.freeTextureData();

package/src/core/renderers/webgl/WebGlCoreCtxTexture.ts

@@ -22,7 +22,6 @@ import { assertTruthy } from '../../../utils.js';
 import type { TextureMemoryManager } from '../../TextureMemoryManager.js';
 import type { WebGlContextWrapper } from '../../lib/WebGlContextWrapper.js';
 import type { Texture } from '../../textures/Texture.js';
-import { isPowerOfTwo } from '../../utils.js';
 import { CoreContextTexture } from '../CoreContextTexture.js';
 import { isHTMLImageElement } from './internal/RendererUtils.js';
 
@@ -52,6 +51,25 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
     super(memManager, textureSource);
   }
 
+  /**
+   * GL error check with direct state marking
+   * Uses cached error result to minimize function calls
+   */
+  private checkGLError(): boolean {
+    // Skip if already failed to prevent double-processing
+    if (this.state === 'failed') {
+      return true;
+    }
+
+    const error = this.glw.getError();
+    if (error !== 0) {
+      this.state = 'failed';
+      this.textureSource.setState('failed', new Error(`WebGL Error: ${error}`));
+      return true;
+    }
+    return false;
+  }
+
   get ctxTexture(): WebGLTexture | null {
     if (this.state === 'freed') {
       this.load();
@@ -92,10 +110,11 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
 
     if (this._nativeCtxTexture === null) {
       this.state = 'failed';
-      const error = new Error('Could not create WebGL Texture');
-      this.textureSource.setState('failed', error);
-      console.error('Could not create WebGL Texture');
-      throw error;
+      this.textureSource.setState(
+        'failed',
+        new Error('WebGL Texture creation failed'),
+      );
+      return;
     }
 
     try {
@@ -113,16 +132,7 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
       // Update the texture source's width and height so that it can be used
       // for rendering.
       this.textureSource.setState('loaded', { width, height });
-
-      // cleanup source texture data next tick
-      // This is done using queueMicrotask to ensure it runs after the current
-      // event loop tick, allowing the texture to be fully loaded and bound
-      // to the GL context before freeing the source data.
-      // This is important to avoid issues with the texture data being
-      // freed while the texture is still being loaded or used.
-      queueMicrotask(() => {
-        this.textureSource.freeTextureData();
-      });
+      this.textureSource.freeTextureData();
     } catch (err: unknown) {
       // If the texture has been freed while loading, return early.
       // Type assertion needed because state could change during async operations
@@ -130,12 +140,9 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
         return;
       }
 
+      // Ensure texture is marked as failed
       this.state = 'failed';
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.textureSource.setState('failed', error);
-      this.textureSource.freeTextureData();
-      console.error(err);
-      throw error; // Re-throw to propagate the error
+      this.textureSource.setState('failed');
     }
   }
 
@@ -145,10 +152,19 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
   async onLoadRequest(): Promise<Dimensions> {
     const { glw } = this;
     const textureData = this.textureSource.textureData;
+
+    // Early return if texture is already failed
+    if (this.state === 'failed') {
+      return { width: 0, height: 0 };
+    }
+
     if (textureData === null || this._nativeCtxTexture === null) {
-      throw new Error(
-        'Texture data or native texture is null ' + this.textureSource.type,
+      this.state = 'failed';
+      this.textureSource.setState(
+        'failed',
+        new Error('No texture data available'),
       );
+      return { width: 0, height: 0 };
     }
 
     // Set to a 1x1 transparent texture
@@ -160,6 +176,11 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
 
     glw.activeTexture(0);
 
+    // High-performance error check - single call, direct state marking
+    if (this.checkGLError() === true) {
+      return { width: 0, height: 0 };
+    }
+
     const tdata = textureData.data;
     const format = glw.RGBA;
     const formatBytes = 4;
@@ -183,25 +204,13 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
 
       glw.texImage2D(0, format, format, glw.UNSIGNED_BYTE, tdata);
 
-      this.setTextureMemUse(height * width * formatBytes * memoryPadding);
-    } else if (tdata === null) {
-      width = 0;
-      height = 0;
-      // Reset to a 1x1 transparent texture
-      glw.bindTexture(this._nativeCtxTexture);
+      // Check for errors after image upload operations
+      if (this.checkGLError() === true) {
+        return { width: 0, height: 0 };
+      }
 
-      glw.texImage2D(
-        0,
-        format,
-        1,
-        1,
-        0,
-        format,
-        glw.UNSIGNED_BYTE,
-        TRANSPARENT_TEXTURE_DATA,
-      );
-      this.setTextureMemUse(TRANSPARENT_TEXTURE_DATA.byteLength);
-    } else if ('mipmaps' in tdata && tdata.mipmaps) {
+      this.setTextureMemUse(height * width * formatBytes * memoryPadding);
+    } else if (tdata && 'mipmaps' in tdata && tdata.mipmaps) {
       const { mipmaps, width = 0, height = 0, type, glInternalFormat } = tdata;
       const view =
         type === 'ktx'
@@ -216,6 +225,11 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
       glw.texParameteri(glw.TEXTURE_MAG_FILTER, glw.LINEAR);
       glw.texParameteri(glw.TEXTURE_MIN_FILTER, glw.LINEAR);
 
+      // Check for errors after compressed texture operations
+      if (this.checkGLError() === true) {
+        return { width: 0, height: 0 };
+      }
+
       this.setTextureMemUse(view.byteLength);
     } else if (tdata && tdata instanceof Uint8Array) {
       // Color Texture
@@ -239,12 +253,24 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
         tdata,
       );
 
+      // Check for errors after color texture operations
+      if (this.checkGLError() === true) {
+        return { width: 0, height: 0 };
+      }
+
       this.setTextureMemUse(width * height * formatBytes);
     } else {
       console.error(
         `WebGlCoreCtxTexture.onLoadRequest: Unexpected textureData returned`,
         textureData,
       );
+
+      this.state = 'failed';
+      this.textureSource.setState(
+        'failed',
+        new Error('Unexpected texture data'),
+      );
+      return { width: 0, height: 0 };
     }
 
     return {
@@ -265,6 +291,13 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
 
     this.state = 'freed';
     this.textureSource.setState('freed');
+    this.release();
+  }
+
+  /**
+   * Release the WebGLTexture from the GPU without changing state
+   */
+  release(): void {
     this._w = 0;
     this._h = 0;
 
@@ -308,6 +341,11 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
     glw.texParameteri(glw.TEXTURE_WRAP_S, glw.CLAMP_TO_EDGE);
     glw.texParameteri(glw.TEXTURE_WRAP_T, glw.CLAMP_TO_EDGE);
 
+    const error = glw.getError();
+    if (error !== 0) {
+      return null;
+    }
+
     return nativeTexture;
   }
 }