@lightningjs/renderer 3.0.2 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/renderer",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Lightning 3 Renderer",
   "type": "module",
   "main": "./dist/exports/index.js",
@@ -40,6 +40,7 @@
     "concurrently": "^8.2.2",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^8.10.2",
+    "happy-dom": "17.6.3",
     "husky": "^8.0.3",
     "lint-staged": "^13.3.0",
     "prettier": "^2.8.8",

package/src/core/CoreNode.ts

@@ -202,6 +202,26 @@ export enum UpdateType {
   All = 16383,
 }
 
+/**
+ * Bitmask of UpdateType flags that represent a visually significant change
+ * within a node. Used to gate notifyParentRTTOfUpdate() so that RTT surfaces
+ * are only marked dirty when something actually visible changed, rather than
+ * on every update() cycle that merely propagates child traversal.
+ *
+ * Excluded flags (non-visual cascade/bookkeeping):
+ *   Children, RenderBounds, RenderState, ParentRenderTexture, Autosize
+ */
+const RTT_NOTIFY_MASK =
+  UpdateType.Local |
+  UpdateType.Global |
+  UpdateType.Clipping |
+  UpdateType.SortZIndexChildren |
+  UpdateType.PremultipliedColors |
+  UpdateType.WorldAlpha |
+  UpdateType.IsRenderable |
+  UpdateType.RenderTexture |
+  UpdateType.RecalcUniforms;
+
 /**
  * A custom data map which can be stored on an CoreNode
  *
@@ -1345,10 +1365,15 @@ export class CoreNode extends EventEmitter {
       }
     }
 
-    // If the node has an RTT parent and requires a texture re-render, inform the RTT parent
-    // if (this.parentHasRenderTexture && updateType & UpdateType.RenderTexture) {
-    // @TODO have a more scoped down updateType for RTT updates
-    if (parentHasRenderTexture === true) {
+    // If the node has an RTT parent and a visually relevant change occurred (or a
+    // nested RTT child already flagged this node via hasRTTupdates), notify the
+    // nearest RTT ancestor so it re-renders its surface.
+    // Guarded by RTT_NOTIFY_MASK to avoid redundant notifications on frames where
+    // only child-traversal bookkeeping flags (Children, RenderBounds, etc.) are set.
+    if (
+      parentHasRenderTexture === true &&
+      (this.hasRTTupdates === true || (updateType & RTT_NOTIFY_MASK) !== 0)
+    ) {
       this.notifyParentRTTOfUpdate();
     }
 

package/src/core/CoreTextNode.test.ts

@@ -19,6 +19,7 @@
 
 import { describe, expect, it, vi, beforeEach } from 'vitest';
 import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
+import { CoreNodeRenderState } from './CoreNode.js';
 import { Stage } from './Stage.js';
 import { CoreRenderer } from './renderers/CoreRenderer.js';
 import { mock } from 'vitest-mock-extended';
@@ -308,4 +309,240 @@ describe('CoreTextNode', () => {
       expect(node.isRenderable).toBe(false);
     });
   });
+
+  function makeStageWithDeleteBuffer(deleteBuffer: ReturnType<typeof vi.fn>) {
+    return mock<Stage>({
+      strictBound: createBound(0, 0, 1920, 1080),
+      preloadBound: createBound(0, 0, 1920, 1080),
+      defaultTexture: { state: 'loaded' },
+      renderer: { deleteBuffer } as unknown as CoreRenderer,
+    });
+  }
+
+  describe('updateRenderState – SDF buffer release on OutOfBounds', () => {
+    it('should call renderer.deleteBuffer and clear _sdfBufferRef when transitioning to OutOfBounds', () => {
+      const deleteBuffer = vi.fn();
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        mockTextRenderer,
+      );
+
+      // Simulate a live WebGLBuffer sitting in the ref
+      const fakeBuffer = {};
+      (node as any)._sdfBufferRef.current = fakeBuffer;
+
+      node.updateRenderState(CoreNodeRenderState.OutOfBounds);
+
+      expect(deleteBuffer).toHaveBeenCalledWith(fakeBuffer);
+      expect((node as any)._sdfBufferRef.current).toBeNull();
+    });
+
+    it('should not call renderer.deleteBuffer when _sdfBufferRef is already null', () => {
+      const deleteBuffer = vi.fn();
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        mockTextRenderer,
+      );
+
+      // _sdfBufferRef.current is null by default
+      node.updateRenderState(CoreNodeRenderState.OutOfBounds);
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+    });
+
+    it('should not release the buffer when transitioning to InBounds', () => {
+      const deleteBuffer = vi.fn();
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        mockTextRenderer,
+      );
+
+      const fakeBuffer = {};
+      (node as any)._sdfBufferRef.current = fakeBuffer;
+
+      node.updateRenderState(CoreNodeRenderState.InBounds);
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+      expect((node as any)._sdfBufferRef.current).toBe(fakeBuffer);
+    });
+
+    it('should not release the buffer for a canvas-type text node', () => {
+      const deleteBuffer = vi.fn();
+      const canvasTextRenderer = {
+        ...mockTextRenderer,
+        type: 'canvas' as const,
+      } as any;
+
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        canvasTextRenderer,
+      );
+
+      (node as any)._sdfBufferRef.current = {};
+
+      node.updateRenderState(CoreNodeRenderState.OutOfBounds);
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('SDF buffer release on layout regeneration', () => {
+    it('should call renderer.deleteBuffer before regenerating layout when font is already loaded', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      const fakeBuffer = {} as WebGLBuffer;
+      (node as any)._sdfBufferRef.current = fakeBuffer;
+
+      node.update(16, clippingRect);
+
+      expect(deleteBuffer).toHaveBeenCalledWith(fakeBuffer);
+      expect((node as any)._sdfBufferRef.current).toBeNull();
+    });
+
+    it('should call renderer.deleteBuffer again on each subsequent layout regeneration', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      node.update(16, clippingRect); // first layout – no buffer yet, no delete call
+      expect(deleteBuffer).not.toHaveBeenCalled();
+
+      // Trigger a second layout pass by invalidating the layout
+      node.fontSize = 24;
+      const secondBuffer = {} as WebGLBuffer;
+      (node as any)._sdfBufferRef.current = secondBuffer;
+
+      node.update(16, clippingRect);
+
+      expect(deleteBuffer).toHaveBeenCalledWith(secondBuffer);
+      expect((node as any)._sdfBufferRef.current).toBeNull();
+    });
+
+    it('should not call renderer.deleteBuffer when buffer is already null at regeneration time', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      // _sdfBufferRef.current is null by default
+      node.update(16, clippingRect);
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('SDF buffer release when text becomes invalid', () => {
+    it('should call renderer.deleteBuffer when text is cleared during update', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, text: 'Hello', forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      // Prime the node with a cached buffer
+      const fakeBuffer = {} as WebGLBuffer;
+      (node as any)._sdfBufferRef.current = fakeBuffer;
+      (node as any)._layoutGenerated = true;
+
+      node.text = '';
+      node.update(16, clippingRect);
+
+      expect(deleteBuffer).toHaveBeenCalledWith(fakeBuffer);
+      expect((node as any)._sdfBufferRef.current).toBeNull();
+    });
+
+    it('should not call renderer.deleteBuffer when text is invalid and buffer is already null', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, text: '', forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      node.update(16, clippingRect);
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+    });
+
+    it('should also clear _cachedLayout when text becomes invalid', () => {
+      const deleteBuffer = vi.fn();
+      const props = { ...defaultTextProps, text: 'Hello', forceLoad: true };
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        props,
+        mockTextRenderer,
+      );
+
+      (node as any)._cachedLayout = {};
+      (node as any)._layoutGenerated = true;
+
+      node.text = '';
+      node.update(16, clippingRect);
+
+      expect((node as any)._cachedLayout).toBeNull();
+    });
+  });
+
+  describe('SDF buffer release on destroy', () => {
+    it('should call renderer.deleteBuffer on destroy when a buffer is held', () => {
+      const deleteBuffer = vi.fn();
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        mockTextRenderer,
+      );
+
+      const fakeBuffer = {} as WebGLBuffer;
+      (node as any)._sdfBufferRef.current = fakeBuffer;
+
+      node.destroy();
+
+      expect(deleteBuffer).toHaveBeenCalledWith(fakeBuffer);
+      expect((node as any)._sdfBufferRef.current).toBeNull();
+    });
+
+    it('should not call renderer.deleteBuffer on destroy when buffer is already null', () => {
+      const deleteBuffer = vi.fn();
+      const node = new CoreTextNode(
+        makeStageWithDeleteBuffer(deleteBuffer),
+        defaultTextProps,
+        mockTextRenderer,
+      );
+
+      // _sdfBufferRef.current is null by default
+      node.destroy();
+
+      expect(deleteBuffer).not.toHaveBeenCalled();
+    });
+
+    it('should clear _cachedLayout on destroy', () => {
+      const node = new CoreTextNode(stage, defaultTextProps, mockTextRenderer);
+
+      (node as any)._cachedLayout = {};
+
+      node.destroy();
+
+      expect((node as any)._cachedLayout).toBeNull();
+    });
+  });
 });

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