@lightningjs/renderer 0.7.6 → 0.8.1

package/src/common/CommonTypes.ts

@@ -74,6 +74,13 @@ export type NodeTextureFailedPayload = {
   error: Error;
 };
 
+/**
+ * Payload for when texture failed to load
+ */
+export type NodeTextureFreedPayload = {
+  type: 'texture';
+};
+
 /**
  * Combined type for all failed payloads
  */

package/src/core/CoreNode.ts

@@ -30,10 +30,12 @@ import type { Stage } from './Stage.js';
 import type {
   Texture,
   TextureFailedEventHandler,
+  TextureFreedEventHandler,
   TextureLoadedEventHandler,
 } from './textures/Texture.js';
 import type {
   NodeTextureFailedPayload,
+  NodeTextureFreedPayload,
   NodeTextureLoadedPayload,
 } from '../common/CommonTypes.js';
 import { EventEmitter } from '../common/EventEmitter.js';
@@ -111,47 +113,99 @@ export enum UpdateType {
 
   /**
    * Scale/Rotate transform update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `scaleRotateTransform`
    */
   ScaleRotate = 2,
 
   /**
    * Translate transform update (x/y/width/height/pivot/mount)
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `localTransform`
    */
   Local = 4,
 
   /**
-   * Global transform update
+   * Global Transform update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `globalTransform`
+   * - `renderCoords`
+   * - `renderBound`
    */
   Global = 8,
 
   /**
    * Clipping rect update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `clippingRect`
    */
   Clipping = 16,
 
   /**
    * Calculated ZIndex update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `calcZIndex`
    */
   CalculatedZIndex = 32,
 
   /**
    * Z-Index Sorted Children update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `children` (sorts children by their `calcZIndex`)
    */
   ZIndexSortedChildren = 64,
 
   /**
-   * Premultiplied Colors
+   * Premultiplied Colors update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `premultipliedColorTl`
+   * - `premultipliedColorTr`
+   * - `premultipliedColorBl`
+   * - `premultipliedColorBr`
    */
   PremultipliedColors = 128,
 
   /**
-   * World Alpha
+   * World Alpha update
    *
    * @remarks
-   * World Alpha = Parent World Alpha * Alpha
+   * CoreNode Properties Updated:
+   * - `worldAlpha` = `parent.worldAlpha` * `alpha`
    */
   WorldAlpha = 256,
 
+  /**
+   * Render State update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `renderState`
+   */
+  RenderState = 512,
+
+  /**
+   * Is Renderable update
+   *
+   * @remarks
+   * CoreNode Properties Updated:
+   * - `isRenderable`
+   */
+  IsRenderable = 1024,
+
   /**
    * None
    */
@@ -160,7 +214,7 @@ export enum UpdateType {
   /**
    * All
    */
-  All = 511,
+  All = 2047,
 }
 
 export class CoreNode extends EventEmitter implements ICoreNode {
@@ -219,7 +273,7 @@ export class CoreNode extends EventEmitter implements ICoreNode {
 
     this.props.texture = texture;
     this.props.textureOptions = options;
-    this.updateIsRenderable();
+    this.setUpdateType(UpdateType.IsRenderable);
 
     // If texture is already loaded / failed, trigger loaded event manually
     // so that users get a consistent event experience.
@@ -230,20 +284,26 @@ export class CoreNode extends EventEmitter implements ICoreNode {
         this.onTextureLoaded(texture, texture.dimensions!);
       } else if (texture.state === 'failed') {
         this.onTextureFailed(texture, texture.error!);
+      } else if (texture.state === 'freed') {
+        this.onTextureFreed(texture);
       }
       texture.on('loaded', this.onTextureLoaded);
       texture.on('failed', this.onTextureFailed);
+      texture.on('freed', this.onTextureFreed);
     });
   }
 
   unloadTexture(): void {
     if (this.props.texture) {
-      this.props.texture.off('loaded', this.onTextureLoaded);
-      this.props.texture.off('failed', this.onTextureFailed);
+      const { texture } = this.props;
+      texture.off('loaded', this.onTextureLoaded);
+      texture.off('failed', this.onTextureFailed);
+      texture.off('freed', this.onTextureFreed);
+      texture.setRenderableOwner(this, false);
     }
     this.props.texture = null;
     this.props.textureOptions = null;
-    this.updateIsRenderable();
+    this.setUpdateType(UpdateType.IsRenderable);
   }
 
   private onTextureLoaded: TextureLoadedEventHandler = (target, dimensions) => {
@@ -262,6 +322,12 @@ export class CoreNode extends EventEmitter implements ICoreNode {
       error,
     } satisfies NodeTextureFailedPayload);
   };
+
+  private onTextureFreed: TextureFreedEventHandler = (target: Texture) => {
+    this.emit('freed', {
+      type: 'texture',
+    } satisfies NodeTextureFreedPayload);
+  };
   //#endregion Textures
 
   loadShader<Type extends keyof ShaderMap>(
@@ -273,7 +339,7 @@ export class CoreNode extends EventEmitter implements ICoreNode {
     const { shader, props: p } = shManager.loadShader(shaderType, props);
     this.props.shader = shader;
     this.props.shaderProps = p;
-    this.updateIsRenderable();
+    this.setUpdateType(UpdateType.IsRenderable);
   }
 
   /**
@@ -353,8 +419,9 @@ export class CoreNode extends EventEmitter implements ICoreNode {
       }
       this.calculateRenderCoords();
       this.updateBoundingRect();
-      this.updateRenderState();
-      this.setUpdateType(UpdateType.Clipping | UpdateType.Children);
+      this.setUpdateType(
+        UpdateType.Clipping | UpdateType.RenderState | UpdateType.Children,
+      );
       childUpdateType |= UpdateType.Global;
     }
 
@@ -408,9 +475,15 @@ export class CoreNode extends EventEmitter implements ICoreNode {
           true,
         );
       }
+    }
+
+    if (this.updateType & UpdateType.RenderState) {
+      this.updateRenderState(parentClippingRect);
+      this.setUpdateType(UpdateType.IsRenderable);
+    }
+
+    if (this.updateType & UpdateType.IsRenderable) {
       this.updateIsRenderable();
-      this.setUpdateType(UpdateType.Children);
-      childUpdateType |= UpdateType.PremultipliedColors;
     }
 
     // No need to update zIndex if there is no parent
@@ -501,25 +574,24 @@ export class CoreNode extends EventEmitter implements ICoreNode {
     return false;
   }
 
-  checkRenderBounds(): CoreNodeRenderState {
-    assertTruthy(this.clippingRect);
+  checkRenderBounds(parentClippingRect: RectWithValid): CoreNodeRenderState {
     assertTruthy(this.renderBound);
-    const rectW = this.clippingRect.width || this.stage.root.width;
-    const rectH = this.clippingRect.height || this.stage.root.height;
+    const rectW = parentClippingRect.width || this.stage.root.width;
+    const rectH = parentClippingRect.height || this.stage.root.height;
     this.strictBound = createBound(
-      this.clippingRect.x,
-      this.clippingRect.y,
-      rectW,
-      rectH,
+      parentClippingRect.x,
+      parentClippingRect.y,
+      parentClippingRect.x + rectW,
+      parentClippingRect.y + rectH,
       this.strictBound,
     );
 
     const renderM = this.stage.boundsMargin;
     this.preloadBound = createBound(
-      this.clippingRect.x - renderM[3],
-      this.clippingRect.y - renderM[0],
-      this.clippingRect.x + rectW + renderM[1],
-      this.clippingRect.y + rectH + renderM[2],
+      parentClippingRect.x - renderM[3],
+      parentClippingRect.y - renderM[0],
+      parentClippingRect.x + rectW + renderM[1],
+      parentClippingRect.y + rectH + renderM[2],
       this.preloadBound,
     );
 
@@ -533,13 +605,13 @@ export class CoreNode extends EventEmitter implements ICoreNode {
     return CoreNodeRenderState.OutOfBounds;
   }
 
-  updateRenderState() {
-    const renderState = this.checkRenderBounds();
+  updateRenderState(parentClippingRect: RectWithValid) {
+    const renderState = this.checkRenderBounds(parentClippingRect);
     if (renderState !== this.renderState) {
       const previous = this.renderState;
       this.renderState = renderState;
       if (previous === CoreNodeRenderState.InViewport) {
-        this.emit('outOfViewPort', {
+        this.emit('outOfViewport', {
           previous,
           current: renderState,
         });
@@ -551,7 +623,6 @@ export class CoreNode extends EventEmitter implements ICoreNode {
         current: renderState,
       });
     }
-    this.updateIsRenderable();
   }
 
   setRenderState(state: CoreNodeRenderState) {
@@ -561,13 +632,26 @@ export class CoreNode extends EventEmitter implements ICoreNode {
     }
   }
 
-  // This function checks if the current node is renderable based on certain properties.
-  // It returns true if any of the specified properties are truthy or if any color property is not 0, otherwise it returns false.
+  /**
+   * This function updates the `isRenderable` property based on certain conditions.
+   *
+   * @returns
+   */
   updateIsRenderable() {
+    let newIsRenderable;
     if (!this.checkRenderProps()) {
-      return (this.isRenderable = false);
+      newIsRenderable = false;
+    } else {
+      newIsRenderable = this.renderState > CoreNodeRenderState.OutOfBounds;
+    }
+    if (this.isRenderable !== newIsRenderable) {
+      this.isRenderable = newIsRenderable;
+      this.onChangeIsRenderable(newIsRenderable);
     }
-    this.isRenderable = this.renderState > CoreNodeRenderState.OutOfBounds;
+  }
+
+  onChangeIsRenderable(isRenderable: boolean) {
+    this.props.texture?.setRenderableOwner(this, isRenderable);
   }
 
   calculateRenderCoords() {

package/src/core/CoreShaderManager.ts

@@ -60,6 +60,7 @@ import {
   RadialProgressEffect,
   type RadialProgressEffectProps,
 } from './renderers/webgl/shaders/effects/RadialProgressEffect.js';
+import { HolePunchEffect } from './renderers/webgl/shaders/effects/HolePunchEffect.js';
 
 export type { FadeOutEffectProps };
 export type { LinearGradientEffectProps };
@@ -94,6 +95,7 @@ export interface EffectMap {
   grayscale: typeof GrayscaleEffect;
   glitch: typeof GlitchEffect;
   radialProgress: typeof RadialProgressEffect;
+  holePunch: typeof HolePunchEffect;
 }
 
 export type EffectProps =
@@ -131,6 +133,7 @@ export class CoreShaderManager {
     this.registerEffectType('glitch', GlitchEffect);
     this.registerEffectType('radius', RadiusEffect);
     this.registerEffectType('radialProgress', RadialProgressEffect);
+    this.registerEffectType('holePunch', HolePunchEffect);
   }
 
   registerShaderType<Type extends keyof ShaderMap>(

package/src/core/CoreTextNode.ts

@@ -55,35 +55,32 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
     super(stage, props);
     this._textRendererOverride = props.textRendererOverride;
     const { resolvedTextRenderer, textRendererState } =
-      this.resolveTextRendererAndState(
-        {
-          x: this.absX,
-          y: this.absY,
-          width: props.width,
-          height: props.height,
-          textAlign: props.textAlign,
-          color: props.color,
-          zIndex: props.zIndex,
-          contain: props.contain,
-          scrollable: props.scrollable,
-          scrollY: props.scrollY,
-          offsetY: props.offsetY,
-          letterSpacing: props.letterSpacing,
-          debug: props.debug,
-          fontFamily: props.fontFamily,
-          fontSize: props.fontSize,
-          fontStretch: props.fontStretch,
-          fontStyle: props.fontStyle,
-          fontWeight: props.fontWeight,
-          text: props.text,
-          lineHeight: props.lineHeight,
-          maxLines: props.maxLines,
-          textBaseline: props.textBaseline,
-          verticalAlign: props.verticalAlign,
-          overflowSuffix: props.overflowSuffix,
-        },
-        undefined,
-      );
+      this.resolveTextRendererAndState({
+        x: this.absX,
+        y: this.absY,
+        width: props.width,
+        height: props.height,
+        textAlign: props.textAlign,
+        color: props.color,
+        zIndex: props.zIndex,
+        contain: props.contain,
+        scrollable: props.scrollable,
+        scrollY: props.scrollY,
+        offsetY: props.offsetY,
+        letterSpacing: props.letterSpacing,
+        debug: props.debug,
+        fontFamily: props.fontFamily,
+        fontSize: props.fontSize,
+        fontStretch: props.fontStretch,
+        fontStyle: props.fontStyle,
+        fontWeight: props.fontWeight,
+        text: props.text,
+        lineHeight: props.lineHeight,
+        maxLines: props.maxLines,
+        textBaseline: props.textBaseline,
+        verticalAlign: props.verticalAlign,
+        overflowSuffix: props.overflowSuffix,
+      });
     this.textRenderer = resolvedTextRenderer;
     this.trState = textRendererState;
   }
@@ -179,8 +176,10 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
   set textRendererOverride(value: CoreTextNodeProps['textRendererOverride']) {
     this._textRendererOverride = value;
 
+    this.textRenderer.destroyState(this.trState);
+
     const { resolvedTextRenderer, textRendererState } =
-      this.resolveTextRendererAndState(this.trState.props, this.trState);
+      this.resolveTextRendererAndState(this.trState.props);
     this.textRenderer = resolvedTextRenderer;
     this.trState = textRendererState;
   }
@@ -348,6 +347,11 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
     return super.checkRenderProps();
   }
 
+  override onChangeIsRenderable(isRenderable: boolean) {
+    super.onChangeIsRenderable(isRenderable);
+    this.textRenderer.setIsRenderable(this.trState, isRenderable);
+  }
+
   override renderQuads(renderer: CoreRenderer) {
     assertTruthy(this.globalTransform);
     this.textRenderer.renderQuads(
@@ -358,15 +362,21 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
     );
   }
 
+  /**
+   * Destroy the node and cleanup all resources
+   */
+  override destroy(): void {
+    super.destroy();
+
+    this.textRenderer.destroyState(this.trState);
+  }
+
   /**
    * Resolve a text renderer and a new state based on the current text renderer props provided
    * @param props
    * @returns
    */
-  private resolveTextRendererAndState(
-    props: TrProps,
-    prevState?: TextRendererState,
-  ): {
+  private resolveTextRendererAndState(props: TrProps): {
     resolvedTextRenderer: TextRenderer;
     textRendererState: TextRendererState;
   } {
@@ -377,15 +387,6 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
 
     const textRendererState = resolvedTextRenderer.createState(props);
 
-    const stateEvents = ['loading', 'loaded', 'failed'];
-
-    if (prevState) {
-      // Remove the old event listeners from previous state obj there was one
-      stateEvents.forEach((eventName) => {
-        prevState.emitter.off(eventName);
-      });
-    }
-
     textRendererState.emitter.on('loaded', this.onTextLoaded);
     textRendererState.emitter.on('failed', this.onTextFailed);
 

package/src/core/CoreTextureManager.ts

@@ -288,6 +288,8 @@ export class CoreTextureManager {
         }
       }
     }
+    // Free the ctx texture if it exists.
+    this.ctxTextureCache.get(texture)?.free();
   }
 
   /**

package/src/core/Stage.ts

@@ -37,11 +37,13 @@ import type {
   FpsUpdatePayload,
   FrameTickPayload,
 } from '../common/CommonTypes.js';
+import { TextureMemoryManager } from './TextureMemoryManager.js';
 
 export interface StageOptions {
   rootId: number;
   appWidth: number;
   appHeight: number;
+  txMemByteThreshold: number;
   boundsMargin: number | [number, number, number, number];
   deviceLogicalPixelRatio: number;
   devicePhysicalPixelRatio: number;
@@ -73,6 +75,7 @@ export class Stage extends EventEmitter {
   /// Module Instances
   public readonly animationManager: AnimationManager;
   public readonly txManager: CoreTextureManager;
+  public readonly txMemManager: TextureMemoryManager;
   public readonly fontManager: TrFontManager;
   public readonly textRenderers: Partial<TextRendererMap>;
   public readonly shManager: CoreShaderManager;
@@ -106,9 +109,11 @@ export class Stage extends EventEmitter {
       boundsMargin,
       enableContextSpy,
       numImageWorkers,
+      txMemByteThreshold,
     } = options;
 
     this.txManager = new CoreTextureManager(numImageWorkers);
+    this.txMemManager = new TextureMemoryManager(txMemByteThreshold);
     this.shManager = new CoreShaderManager();
     this.animationManager = new AnimationManager();
     this.contextSpy = enableContextSpy ? new ContextSpy() : null;
@@ -138,6 +143,7 @@ export class Stage extends EventEmitter {
       clearColor: clearColor ?? 0xff000000,
       bufferMemory,
       txManager: this.txManager,
+      txMemManager: this.txMemManager,
       shManager: this.shManager,
       contextSpy: this.contextSpy,
     });
@@ -243,11 +249,15 @@ export class Stage extends EventEmitter {
 
     renderer?.render();
 
+    this.calculateFps();
+
     // Reset renderRequested flag if it was set
     if (renderRequested) {
       this.renderRequested = false;
     }
+  }
 
+  calculateFps() {
     // If there's an FPS update interval, emit the FPS update event
     // when the specified interval has elapsed.
     const { fpsUpdateInterval } = this.options;

package/src/core/TextureMemoryManager.ts

@@ -0,0 +1,66 @@
+/*
+ * 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 type { CoreContextTexture } from './renderers/CoreContextTexture.js';
+
+export class TextureMemoryManager {
+  private memUsed = 0;
+  private textures: Map<CoreContextTexture, number> = new Map();
+  private threshold: number;
+
+  /**
+   * @param byteThreshold Number of texture bytes to trigger garbage collection
+   */
+  constructor(byteThreshold: number) {
+    this.threshold = byteThreshold;
+
+    // If the threshold is 0, we disable the memory manager by replacing the
+    // setTextureMemUse method with a no-op function.
+    if (byteThreshold === 0) {
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      this.setTextureMemUse = () => {};
+    }
+  }
+
+  setTextureMemUse(ctxTexture: CoreContextTexture, byteSize: number) {
+    if (this.textures.has(ctxTexture)) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.memUsed -= this.textures.get(ctxTexture)!;
+    }
+
+    if (byteSize === 0) {
+      this.textures.delete(ctxTexture);
+      return;
+    } else {
+      this.memUsed += byteSize;
+      this.textures.set(ctxTexture, byteSize);
+    }
+
+    if (this.memUsed > this.threshold) {
+      this.gc();
+    }
+  }
+
+  gc() {
+    this.textures.forEach((byteSize, ctxTexture) => {
+      if (!ctxTexture.renderable) {
+        ctxTexture.free();
+      }
+    });
+  }
+}

package/src/core/platform.ts

@@ -23,14 +23,22 @@ import type { Stage } from './Stage.js';
  * Platform render loop initiator
  */
 export const startLoop = (stage: Stage) => {
+  let isIdle = false;
   const runLoop = () => {
     stage.updateAnimations();
 
     if (!stage.hasSceneUpdates()) {
+      // We still need to calculate the fps else it looks like the app is frozen
+      stage.calculateFps();
       setTimeout(runLoop, 16.666666666666668);
+      if (!isIdle) {
+        stage.emit('idle');
+        isIdle = true;
+      }
       return;
     }
 
+    isIdle = false;
     stage.drawFrame();
     requestAnimationFrame(runLoop);
   };

package/src/core/renderers/CoreContextTexture.ts

@@ -17,14 +17,19 @@
  * limitations under the License.
  */
 
+import type { TextureMemoryManager } from '../TextureMemoryManager.js';
 import type { Texture } from '../textures/Texture.js';
 
 export abstract class CoreContextTexture {
+  readonly memManager: TextureMemoryManager;
   readonly textureSource: Texture;
 
-  constructor(textureSource: Texture) {
+  constructor(memManager: TextureMemoryManager, textureSource: Texture) {
+    this.memManager = memManager;
     this.textureSource = textureSource;
   }
 
   abstract load(): void;
+  abstract free(): void;
+  abstract get renderable(): boolean;
 }

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

@@ -18,13 +18,18 @@
  */
 
 import type { Dimensions } from '../../../common/CommonTypes.js';
+import type { TextureMemoryManager } from '../../TextureMemoryManager.js';
 import type { WebGlContextWrapper } from '../../lib/WebGlContextWrapper.js';
 import type { SubTexture } from '../../textures/SubTexture.js';
 import { WebGlCoreCtxTexture } from './WebGlCoreCtxTexture.js';
 
 export class WebGlCoreCtxSubTexture extends WebGlCoreCtxTexture {
-  constructor(glw: WebGlContextWrapper, textureSource: SubTexture) {
-    super(glw, textureSource);
+  constructor(
+    glw: WebGlContextWrapper,
+    memManager: TextureMemoryManager,
+    textureSource: SubTexture,
+  ) {
+    super(glw, memManager, textureSource);
   }
 
   override async onLoadRequest(): Promise<Dimensions> {