@lightningjs/renderer 3.0.2 → 3.0.4

package/src/core/CoreTextNode.ts

@@ -21,7 +21,6 @@ import type {
   FontHandler,
   TextRenderer,
   TrProps,
-  TextLayout,
   TextRenderInfo,
 } from './text-rendering/TextRenderer.js';
 import {
@@ -40,6 +39,11 @@ import type { RectWithValid } from './lib/utils.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
 import type { TextureLoadedEventHandler } from './textures/Texture.js';
 import { Matrix3d } from './lib/Matrix3d.js';
+import { BufferCollection } from './renderers/webgl/internal/BufferCollection.js';
+import type { SdfShaderProps } from './shaders/webgl/SdfShader.js';
+import type { WebGlRenderer } from './renderers/webgl/WebGlRenderer.js';
+import type { WebGlCtxTexture } from './renderers/webgl/WebGlCtxTexture.js';
+import { mergeColorAlpha } from '../utils.js';
 export interface CoreTextNodeProps extends CoreNodeProps, TrProps {
   /**
    * Force Text Node to use a specific Text Renderer
@@ -63,19 +67,14 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   private _waitingForFont = false;
   private _containType: TextConstraint = TextConstraint.none;
 
-  // SDF layout caching for performance
-  private _cachedLayout: TextLayout | null = null;
-  private _lastVertexBuffer: Float32Array | null = null;
+  private _sdfBuffer: WebGLBuffer | null = null;
+  private _sdfQuadCollection: BufferCollection | null = null;
+  private _sdfShaderProps: Partial<SdfShaderProps> | null = null;
 
   // Text renderer properties - stored directly on the node
-  private textProps: CoreTextNodeProps;
+  textProps: CoreTextNodeProps;
 
-  private _renderInfo: TextRenderInfo = {
-    width: 0,
-    height: 0,
-  };
-
-  private _type: 'sdf' | 'canvas' = 'sdf'; // Default to SDF renderer
+  private _renderInfo: TextRenderInfo | null = null;
 
   constructor(
     stage: Stage,
@@ -85,7 +84,6 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     super(stage, props);
     this.textRenderer = textRenderer;
     this.fontHandler = textRenderer.font;
-    this._type = textRenderer.type;
 
     // Initialize text properties from props
     // Props are guaranteed to have all defaults resolved by Stage.createTextNode
@@ -113,6 +111,19 @@ 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._sdfBuffer;
+    if (buf === null) return;
+    this.stage.renderer.deleteBuffer(buf);
+    this._sdfBuffer = null;
+    this._sdfQuadCollection = null;
+  }
+
   allowTextGeneration() {
     const p = this.props.parent;
     if (p === null) {
@@ -196,7 +207,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 &&
@@ -206,8 +218,8 @@ 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._renderInfo = null; // Clear any previous render info before generating new layout
+        this.releaseSdfBuffer(); // Free the cached WebGLBuffer
         const resp = this.textRenderer.renderText(this.textProps);
         this.handleRenderResult(resp);
         this._layoutGenerated = true;
@@ -216,11 +228,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._renderInfo = null;
+      this.releaseSdfBuffer(); // Free the cached WebGLBuffer
     }
 
     // First run the standard CoreNode update
@@ -232,20 +246,21 @@ 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;
-    if (hasValidText === false) {
+    const hasValidText =
+      typeof this.textProps.text === 'string' && this.textProps.text.length > 0;
+
+    const renderInfo = this._renderInfo;
+    if (hasValidText === false || renderInfo === null) {
       this.setRenderable(false);
       return;
     }
 
     // SDF text nodes are always renderable if they have a valid layout
-    if (this._type === 'canvas') {
+    if (renderInfo.type === 'canvas') {
       super.updateIsRenderable();
       return;
     }
-
-    // For SDF, check if we have a cached layout
-    this.setRenderable(this._cachedLayout !== null);
+    this.setRenderable(true);
   }
 
   /**
@@ -253,10 +268,19 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
    */
   private handleRenderResult(result: TextRenderInfo): void {
     // Host paths on top
-    const textRendererType = this._type;
+    const textRendererType = result.type;
     let width = result.width;
     let height = result.height;
 
+    // Handle zero-dimension case (can happen with certain text inputs or font issues)
+    if (width === 0 || height === 0) {
+      this.emit('failed', {
+        type: 'text',
+        error: new Error('Text rendering failed, width or height zero'),
+      } satisfies NodeTextFailedPayload);
+      return;
+    }
+
     // Handle Canvas renderer (uses ImageData)
     if (textRendererType === 'canvas') {
       if (result.imageData === undefined) {
@@ -273,6 +297,9 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         premultiplyAlpha: true,
         src: result.imageData as ImageData,
       });
+
+      this.props.w = width;
+      this.props.h = height;
       // It isn't renderable until the texture is loaded we have to set it to false here to avoid it
       // being detected as a renderable default color node in the next frame
       // it will be corrected once the texture is loaded
@@ -282,25 +309,31 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         // We do want the texture to load immediately
         this.texture.setRenderableOwner(this._id, true);
       }
-    }
+    } else {
+      const layout = result.layout;
+      // For SDF, we rely on the presence of a valid layout to determine renderability
+      if (layout === undefined) {
+        this.emit('failed', {
+          type: 'text',
+          error: new Error(
+            'SDF text rendering failed, no layout data returned',
+          ),
+        } satisfies NodeTextFailedPayload);
+        return;
+      }
 
-    // Handle zero-dimension case (can happen with certain text inputs or font issues)
-    if (width === 0 || height === 0) {
-      this.emit('failed', {
-        type: 'text',
-        error: new Error('Text rendering failed, width or height zero'),
-      } satisfies NodeTextFailedPayload);
-      return;
-    }
+      this.props.w = width;
+      this.props.h = height;
+      this.setUpdateType(UpdateType.Local);
+      this.setRenderable(true);
+      this.numQuads = layout.glyphCount;
 
-    this._cachedLayout = result.layout || null;
-    this.props.w = width;
-    this.props.h = height;
+      this._sdfShaderProps = {
+        size: layout.fontScale,
+        distanceRange: layout.distanceRange,
+      };
 
-    // Handle SDF renderer (uses layout caching)
-    if (textRendererType === 'sdf') {
-      this.setRenderable(true);
-      this.setUpdateType(UpdateType.Local);
+      this.renderOpTextures = [result.atlasTexture as WebGlCtxTexture];
     }
 
     this._renderInfo = result;
@@ -309,6 +342,8 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
 
   // Reusable bound method for emitting loaded event
   private emitTextLoadedEvent = () => {
+    if (this._renderInfo === null) return; // Guard against unexpected null
+
     this.emit('loaded', {
       type: 'text',
       dimensions: {
@@ -328,44 +363,72 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         return;
     }
 
-    // Canvas renderer: use standard texture rendering via CoreNode
-    if (this._type === 'canvas') {
-      super.renderQuads(renderer);
+    // Early return if no renderInfo
+    if (this._renderInfo === null) {
       return;
     }
 
-    // Early return if no cached data
-    if (!this._cachedLayout) {
+    // Canvas renderer: use standard texture rendering via CoreNode
+    if (this._renderInfo.type === 'canvas') {
+      super.renderQuads(renderer);
       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,
-      },
+    if (this._sdfBuffer === null) {
+      const glw = (this.stage.renderer as WebGlRenderer).glw;
+      this._sdfBuffer = glw.createBuffer();
+      if (this._sdfBuffer === null) {
+        console.error('Failed to create WebGL buffer for SDF text rendering');
+        return;
+      }
+      glw.arrayBufferData(
+        this._sdfBuffer,
+        this._renderInfo.layout.vertexBuffer,
+        glw.STATIC_DRAW,
+      );
+
+      this._sdfQuadCollection = new BufferCollection([
+        {
+          buffer: this._sdfBuffer,
+          attributes: {
+            a_position: {
+              name: 'a_position',
+              size: 2,
+              type: glw.FLOAT as number,
+              normalized: false,
+              stride: 4 * Float32Array.BYTES_PER_ELEMENT,
+              offset: 0,
+            },
+            a_textureCoords: {
+              name: 'a_textureCoords',
+              size: 2,
+              type: glw.FLOAT as number,
+              normalized: false,
+              stride: 4 * Float32Array.BYTES_PER_ELEMENT,
+              offset: 2 * Float32Array.BYTES_PER_ELEMENT,
+            },
+          },
+        },
+      ]);
+    }
+
+    this.sdfShaderProps!.transform = this.globalTransform!.getFloatArr();
+    this.sdfShaderProps!.color = mergeColorAlpha(
+      this.props.color,
+      this.worldAlpha,
     );
+
+    this.textRenderer.renderQuads(this);
+  }
+
+  override updateRenderState(renderState: CoreNodeRenderState): void {
+    super.updateRenderState(renderState);
+    if (
+      this._renderInfo !== null &&
+      renderState === CoreNodeRenderState.OutOfBounds
+    ) {
+      this.releaseSdfBuffer();
+    }
   }
 
   override destroy(): void {
@@ -374,8 +437,8 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     }
 
     // Clear cached layout and vertex buffer
-    this._cachedLayout = null;
-    this._lastVertexBuffer = null;
+    this._renderInfo = 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
@@ -383,6 +446,70 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     super.destroy();
   }
 
+  /**
+   * used in webgl SDF shader to get the quad buffer collection for rendering text quads
+   */
+  override get quadBufferCollection(): BufferCollection {
+    return this._sdfQuadCollection || super.quadBufferCollection;
+  }
+
+  /**
+   * used in webgl SDF shader to get the SDF shader props for rendering text quads
+   */
+  get sdfShaderProps(): SdfShaderProps {
+    return this._sdfShaderProps as SdfShaderProps;
+  }
+
+  override get isSdfRenderOp(): boolean {
+    return this.textRenderer.type === 'sdf';
+  }
+
+  override draw(renderer: WebGlRenderer) {
+    if (this.textRenderer.type === 'canvas') {
+      super.draw(renderer);
+      return;
+    }
+
+    const { glw, stage } = renderer;
+    const canvas = stage.platform!.canvas!;
+    const shader = this.props.shader as any;
+
+    stage.shManager.useShader(shader.program);
+    shader.program.bindRenderOp(this);
+
+    const clippingRect = this.clippingRect;
+
+    // Clipping
+    if (clippingRect.valid === true) {
+      const pixelRatio = this.parentHasRenderTexture ? 1 : stage.pixelRatio;
+
+      const clipX = Math.round(clippingRect.x * pixelRatio);
+      const clipWidth = Math.round(clippingRect.w * pixelRatio);
+      const clipHeight = Math.round(clippingRect.h * pixelRatio);
+      let clipY = Math.round(
+        canvas.height - clipHeight - clippingRect.y * pixelRatio,
+      );
+      // if parent has render texture, we need to adjust the scissor rect
+      // to be relative to the parent's framebuffer
+      if (this.parentHasRenderTexture) {
+        const parentFramebufferDimensions = this.parentFramebufferDimensions;
+        clipY =
+          parentFramebufferDimensions !== null
+            ? parentFramebufferDimensions.h - this.props.h
+            : 0;
+      }
+
+      glw.setScissorTest(true);
+      glw.scissor(clipX, clipY, clipWidth, clipHeight);
+    } else {
+      glw.setScissorTest(false);
+    }
+
+    // SDF rendering uses drawArrays with explicit triangle vertices (6 vertices per quad)
+    // Note: buffers should be bound by bindRenderOp -> bindBufferCollection
+    glw.drawArrays(glw.TRIANGLES, 0, 6 * this.numQuads);
+  }
+
   override set w(value: number) {
     this.maxWidth = value;
   }
@@ -601,7 +728,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     }
   }
 
-  get renderInfo(): TextRenderInfo {
+  get renderInfo(): TextRenderInfo | null {
     return this._renderInfo;
   }
 }

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