@lightningjs/renderer 3.0.1 → 3.0.3

package/src/core/CoreTextNode.ts

@@ -65,7 +65,9 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
 
   // SDF layout caching for performance
   private _cachedLayout: TextLayout | null = null;
-  private _lastVertexBuffer: Float32Array | null = null;
+  // Mutable ref box shared with SdfTextRenderer so the renderer can write the
+  // created WebGLBuffer back into it, allowing reuse across frames.
+  private _sdfBufferRef: { current: WebGLBuffer | null } = { current: null };
 
   // Text renderer properties - stored directly on the node
   private textProps: CoreTextNodeProps;
@@ -113,6 +115,18 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     this.setUpdateType(UpdateType.IsRenderable);
   };
 
+  /**
+   * Delete the cached WebGLBuffer held by the SDF renderer ref and reset the
+   * ref so the next renderQuads call allocates a fresh one.
+   * Safe to call from destroy() or on text change.
+   */
+  private releaseSdfBuffer(): void {
+    const buf = this._sdfBufferRef.current;
+    if (buf === null) return;
+    this.stage.renderer.deleteBuffer(buf);
+    this._sdfBufferRef.current = null;
+  }
+
   allowTextGeneration() {
     const p = this.props.parent;
     if (p === null) {
@@ -196,7 +210,8 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
    * Override CoreNode's update method to handle text-specific updates
    */
   override update(delta: number, parentClippingRect: RectWithValid): void {
-    const hasValidText = this.textProps.text && this.textProps.text.length > 0;
+    const hasValidText =
+      typeof this.textProps.text === 'string' && this.textProps.text.length > 0;
 
     if (
       hasValidText === true &&
@@ -207,7 +222,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
       if (this.fontHandler.isFontLoaded(this.textProps.fontFamily) === true) {
         this._waitingForFont = false;
         this._cachedLayout = null; // Invalidate cached layout
-        this._lastVertexBuffer = null; // Invalidate last vertex buffer
+        this.releaseSdfBuffer(); // Free the cached WebGLBuffer
         const resp = this.textRenderer.renderText(this.textProps);
         this.handleRenderResult(resp);
         this._layoutGenerated = true;
@@ -216,11 +231,13 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         this._waitingForFont = true;
       }
     } else if (hasValidText === false) {
+      this.props.w = 0;
+      this.props.h = 0;
       // If text is invalid, ensure node is not renderable
       this.setRenderable(false);
       this._layoutGenerated = false;
       this._cachedLayout = null;
-      this._lastVertexBuffer = null;
+      this.releaseSdfBuffer(); // Free the cached WebGLBuffer
     }
 
     // First run the standard CoreNode update
@@ -232,7 +249,8 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
    */
   override updateIsRenderable(): void {
     // Guard: Text nodes are never renderable without valid text
-    const hasValidText = this.textProps.text && this.textProps.text.length > 0;
+    const hasValidText =
+      typeof this.textProps.text === 'string' && this.textProps.text.length > 0;
     if (hasValidText === false) {
       this.setRenderable(false);
       return;
@@ -335,37 +353,39 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     }
 
     // Early return if no cached data
-    if (!this._cachedLayout) {
+    if (this._cachedLayout === null) {
       return;
     }
 
-    if (this._lastVertexBuffer === null) {
-      this._lastVertexBuffer = this.textRenderer.addQuads(this._cachedLayout);
-    }
-
     const props = this.textProps;
-    this.textRenderer.renderQuads(
-      renderer,
-      this._cachedLayout as TextLayout,
-      this._lastVertexBuffer!,
-      {
-        fontFamily: this.textProps.fontFamily,
-        fontSize: props.fontSize,
-        color: this.props.color || 0xffffffff,
-        offsetY: props.offsetY,
-        worldAlpha: this.worldAlpha,
-        globalTransform: this.globalTransform!.getFloatArr(),
-        clippingRect: this.clippingRect,
-        width: this.props.w,
-        height: this.props.h,
-        parentHasRenderTexture: this.parentHasRenderTexture,
-        framebufferDimensions:
-          this.parentHasRenderTexture === true
-            ? this.parentFramebufferDimensions
-            : null,
-        stage: this.stage,
-      },
-    );
+    this.textRenderer.renderQuads(renderer, this._cachedLayout as TextLayout, {
+      fontFamily: this.textProps.fontFamily,
+      fontSize: props.fontSize,
+      color: this.props.color || 0xffffffff,
+      offsetY: props.offsetY,
+      worldAlpha: this.worldAlpha,
+      globalTransform: this.globalTransform!.getFloatArr(),
+      clippingRect: this.clippingRect,
+      width: this.props.w,
+      height: this.props.h,
+      parentHasRenderTexture: this.parentHasRenderTexture,
+      framebufferDimensions:
+        this.parentHasRenderTexture === true
+          ? this.parentFramebufferDimensions
+          : null,
+      stage: this.stage,
+      glBufferRef: this._sdfBufferRef,
+    });
+  }
+
+  override updateRenderState(renderState: CoreNodeRenderState): void {
+    super.updateRenderState(renderState);
+    if (
+      this._type === 'sdf' &&
+      renderState === CoreNodeRenderState.OutOfBounds
+    ) {
+      this.releaseSdfBuffer();
+    }
   }
 
   override destroy(): void {
@@ -375,7 +395,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
 
     // Clear cached layout and vertex buffer
     this._cachedLayout = null;
-    this._lastVertexBuffer = null;
+    this.releaseSdfBuffer(); // Delete the cached WebGLBuffer before losing stage ref
 
     this.fontHandler = null!; // Clear reference to avoid memory leaks
     this.textRenderer = null!; // Clear reference to avoid memory leaks

package/src/core/CoreTextureManager.ts

@@ -289,8 +289,6 @@ export class CoreTextureManager extends EventEmitter {
    * @param immediate - Whether to prioritize the texture for immediate loading
    */
   async loadTexture(texture: Texture, priority?: boolean): Promise<void> {
-    this.stage.txMemManager.removeFromOrphanedTextures(texture);
-
     if (texture.type === TextureType.subTexture) {
       // ignore subtextures - they get loaded through their parent
       return;
@@ -464,6 +462,20 @@ export class CoreTextureManager extends EventEmitter {
     }
   }
 
+  /**
+   * Destroy the CoreTextureManager and release all internal references.
+   *
+   * @remarks
+   * Clears the upload queue and key/inverse-key caches so that queued
+   * textures can be garbage-collected after a renderer teardown.
+   */
+  destroy(): void {
+    this.uploadTextureQueue = [];
+    this.keyCache.clear();
+    // inverseKeyCache is a WeakMap – entries will be GC'd automatically once
+    // the texture objects themselves are no longer referenced.
+  }
+
   /**
    * Resolve a parent texture from the cache or fallback to the provided texture.
    *

package/src/core/Stage.ts

@@ -882,6 +882,35 @@ export class Stage {
     this.txMemManager.cleanup(full);
   }
 
+  /**
+   * Destroy the stage and release all resources.
+   *
+   * @remarks
+   * This method stops the render loop, destroys all nodes, releases all
+   * textures and GPU resources, and terminates any background workers.
+   */
+  destroy(): void {
+    // Stop the render loop and terminate workers
+    this.platform.stopLoop();
+
+    // Recursively destroy all nodes (includes CoreTextNode font/text cleanup)
+    this.root.destroy();
+
+    // Free all GPU-side textures and clear internal tracking arrays/caches
+    this.txMemManager.destroy();
+
+    // Clear the texture upload queue and key caches
+    this.txManager.destroy();
+
+    // Release the GPU context (WebGL) or canvas resources
+    this.renderer.destroy();
+
+    // Clear text renderer caches
+    for (const key in this.textRenderers) {
+      this.textRenderers[key]!.clearCache();
+    }
+  }
+
   set clearColor(value: number) {
     this.renderer.updateClearColor(value);
     this.renderRequested = true;

package/src/core/TextureMemoryManager.test.ts

@@ -0,0 +1,134 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2024 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 { describe, it, expect } from 'vitest';
+import { mock } from 'vitest-mock-extended';
+import {
+  TextureMemoryManager,
+  type TextureMemoryManagerSettings,
+} from './TextureMemoryManager.js';
+import type { Stage } from './Stage.js';
+import type { Texture } from './textures/Texture.js';
+import { TextureType } from './textures/Texture.js';
+
+function makeSettings(
+  overrides?: Partial<TextureMemoryManagerSettings>,
+): TextureMemoryManagerSettings {
+  return {
+    criticalThreshold: 124e6,
+    targetThresholdLevel: 0.5,
+    cleanupInterval: 5000,
+    debugLogging: false,
+    baselineMemoryAllocation: 25e6,
+    doNotExceedCriticalThreshold: false,
+    ...overrides,
+  };
+}
+
+function makeTexture(memUsed = 1024): Texture {
+  const texture = mock<Texture>();
+  texture.memUsed = memUsed;
+  texture.type = TextureType.image;
+  texture.state = 'loaded';
+  (texture as { renderable: boolean }).renderable = false;
+  texture.preventCleanup = false;
+  texture.canBeCleanedUp.mockReturnValue(true);
+  return texture;
+}
+
+function makeStage() {
+  const stage = mock<Stage>();
+  const txManager = mock<Stage['txManager']>();
+  (stage as { txManager: Stage['txManager'] }).txManager = txManager;
+  return stage;
+}
+
+describe('TextureMemoryManager', () => {
+  describe('destroy()', () => {
+    it('calls destroyTexture for every loaded texture', () => {
+      const stage = makeStage();
+      const manager = new TextureMemoryManager(stage, makeSettings());
+
+      const textures = [makeTexture(512), makeTexture(1024), makeTexture(2048)];
+
+      for (const texture of textures) {
+        manager.setTextureMemUse(texture, texture.memUsed);
+      }
+
+      manager.destroy();
+
+      for (const texture of textures) {
+        expect(texture.destroy).toHaveBeenCalledOnce();
+      }
+    });
+
+    it('clears internal tracking so memUsed is 0 after destroy', () => {
+      const stage = makeStage();
+      const manager = new TextureMemoryManager(stage, makeSettings());
+
+      const texture = makeTexture(4096);
+      manager.setTextureMemUse(texture, texture.memUsed);
+
+      manager.destroy();
+
+      expect(manager.getMemoryInfo().memUsed).toBe(0);
+    });
+
+    it('reports no loaded textures after destroy', () => {
+      const stage = makeStage();
+      const manager = new TextureMemoryManager(stage, makeSettings());
+
+      manager.setTextureMemUse(makeTexture(512), 512);
+      manager.setTextureMemUse(makeTexture(1024), 1024);
+
+      manager.destroy();
+
+      expect(manager.getMemoryInfo().loadedTextures).toBe(0);
+    });
+
+    it('removes each texture from the cache via txManager', () => {
+      const stage = makeStage();
+      const manager = new TextureMemoryManager(stage, makeSettings());
+
+      const textures = [makeTexture(256), makeTexture(512)];
+      for (const texture of textures) {
+        manager.setTextureMemUse(texture, texture.memUsed);
+      }
+
+      manager.destroy();
+
+      expect(stage.txManager.removeTextureFromCache).toHaveBeenCalledTimes(
+        textures.length,
+      );
+
+      for (const texture of textures) {
+        expect(stage.txManager.removeTextureFromCache).toHaveBeenCalledWith(
+          texture,
+        );
+      }
+    });
+
+    it('handles an empty loadedTextures list without throwing', () => {
+      const stage = makeStage();
+      const manager = new TextureMemoryManager(stage, makeSettings());
+
+      expect(() => manager.destroy()).not.toThrow();
+    });
+  });
+});

package/src/core/TextureMemoryManager.ts

@@ -116,7 +116,6 @@ export interface MemoryInfo {
 export class TextureMemoryManager {
   private memUsed = 0;
   private loadedTextures: (Texture | null)[] = [];
-  private orphanedTextures: Texture[] = [];
   private criticalThreshold: number = 124e6;
   private targetThreshold: number = 0.5;
   private cleanupInterval: number = 5000;
@@ -145,35 +144,6 @@ export class TextureMemoryManager {
     this.updateSettings(settings);
   }
 
-  /**
-   * 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
    *
@@ -415,4 +385,27 @@ export class TextureMemoryManager {
       this.setTextureMemUse = () => {};
     }
   }
+
+  /**
+   * Destroy the TextureMemoryManager and release all internal references.
+   *
+   * @remarks
+   * Clears the debug-logging interval (if active) and empties all internal
+   * texture tracking arrays so that held textures can be garbage-collected.
+   */
+  destroy(): void {
+    if (this.loggingID) {
+      clearInterval(this.loggingID);
+      this.loggingID = 0 as unknown as ReturnType<typeof setInterval>;
+    }
+    // Free GPU resources for every loaded texture before clearing the array
+    for (let i = 0; i < this.loadedTextures.length; i++) {
+      const texture = this.loadedTextures[i];
+      if (texture !== null && texture !== undefined) {
+        this.destroyTexture(texture);
+      }
+    }
+    this.loadedTextures = [];
+    this.memUsed = 0;
+  }
 }

package/src/core/platforms/Platform.ts

@@ -89,6 +89,11 @@ export abstract class Platform {
    */
   abstract startLoop(stage: Stage): void;
 
+  /**
+   * Stops the main rendering loop and releases platform resources.
+   */
+  abstract stopLoop(): void;
+
   /**
    * Fetches a resource from the network.
    * @param url - The URL of the resource to fetch.

package/src/core/platforms/web/WebPlatform.ts

@@ -48,6 +48,7 @@ export class WebPlatform extends Platform {
   private useImageWorker: boolean;
   private imageWorkerManager: ImageWorkerManager | null = null;
   private hasWorker = !!self.Worker;
+  private stopped = false;
 
   constructor(settings: PlatformSettings = {}) {
     super(settings);
@@ -100,10 +101,12 @@ export class WebPlatform extends Platform {
   ////////////////////////
 
   override startLoop(stage: Stage): void {
+    this.stopped = false;
     let isIdle = false;
     let lastFrameTime = 0;
 
     const runLoop = (currentTime: number = 0) => {
+      if (this.stopped) return;
       const targetFrameTime = stage.targetFrameTime;
 
       // Check if we should throttle this frame
@@ -173,6 +176,16 @@ export class WebPlatform extends Platform {
     requestAnimationFrame(runLoop);
   }
 
+  override stopLoop(): void {
+    this.stopped = true;
+    if (this.imageWorkerManager !== null) {
+      for (const worker of this.imageWorkerManager.workers) {
+        worker.terminate();
+      }
+      this.imageWorkerManager = null;
+    }
+  }
+
   ////////////////////////
   // Image handling
   ////////////////////////

package/src/core/renderers/CoreRenderer.ts

@@ -67,5 +67,15 @@ export abstract class CoreRenderer {
   abstract getQuadCount(): number | null;
   abstract updateViewport(): void;
   abstract updateClearColor(color: number): void;
+  abstract destroy(): void;
   getTextureCoords?(node: CoreNode): TextureCoords | undefined;
+
+  /**
+   * Delete a GPU buffer previously allocated by this renderer.
+   * No-op for renderers that do not use WebGL buffers (e.g. Canvas).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  deleteBuffer(_buffer: WebGLBuffer): void {
+    // no-op default — overridden by WebGlRenderer
+  }
 }

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

@@ -255,4 +255,10 @@ export class CanvasRenderer extends CoreRenderer {
   getDefaultShaderNode() {
     return null;
   }
+
+  override destroy(): void {
+    // Release canvas 2D context by resizing canvas to 0
+    this.canvas.width = 0;
+    this.canvas.height = 0;
+  }
 }