@lightningjs/renderer 2.16.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,39 +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.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
    */
@@ -290,66 +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;
-
-    // sort by renderability
-    const filteredAndSortedTextures: Texture[] = [];
-    const textures = [...this.loadedTextures.keys()];
-    for (let i = 0; i < textures.length; i++) {
-      const texture = textures[i];
-      if (texture === undefined) {
-        continue;
-      }
-
-      if (
-        texture.type === TextureType.image ||
-        texture.type === TextureType.noise ||
-        texture.type === TextureType.renderToTexture
-      ) {
-        if (texture.renderable === true) {
-          filteredAndSortedTextures.push(texture);
-        } else {
-          filteredAndSortedTextures.unshift(texture);
-        }
-      }
-    }
-
-    while (this.memUsed >= memTarget && filteredAndSortedTextures.length > 0) {
-      const texture = filteredAndSortedTextures.shift();
-      if (texture === undefined) {
-        continue;
-      }
-
-      if (texture.preventCleanup === true) {
-        continue;
-      }
-
-      if (texture.renderable === true) {
-        break;
-      }
-
-      // 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.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)) {
-        break;
-      }
-
-      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;
 
@@ -362,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) {
@@ -399,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
    *
@@ -408,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,
@@ -424,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();