@lightningjs/renderer 0.7.6 → 0.8.1

package/src/core/text-rendering/renderers/TextRenderer.ts

@@ -66,6 +66,8 @@ export interface TextRendererState {
   textW: number | undefined;
   textH: number | undefined;
 
+  isRenderable: boolean;
+
   debugData: {
     updateCount: number;
     layoutCount: number;
@@ -311,6 +313,7 @@ export interface TrProps extends TrFontProps {
   overflowSuffix: string;
 
   zIndex: number;
+
   debug: Partial<TextRendererDebugProps>;
 }
 
@@ -450,6 +453,17 @@ export abstract class TextRenderer<
     state.emitter.emit(status, error);
   }
 
+  /**
+   * Allows the CoreTextNode to communicate changes to the isRenderable state of
+   * the itself.
+   *
+   * @param state
+   * @param renderable
+   */
+  setIsRenderable(state: StateT, renderable: boolean) {
+    state.isRenderable = renderable;
+  }
+
   /**
    * Called by constructor to get a map of property setter functions for this renderer.
    */
@@ -484,6 +498,24 @@ export abstract class TextRenderer<
 
   abstract createState(props: TrProps): StateT;
 
+  /**
+   * Destroy/Clean up the state object
+   *
+   * @remarks
+   * Opposite of createState(). Frees any event listeners / resources held by
+   * the state that may not reliably get garbage collected.
+   *
+   * @param state
+   */
+  destroyState(state: StateT) {
+    const stateEvents = ['loading', 'loaded', 'failed'];
+
+    // Remove the old event listeners from previous state obj there was one
+    stateEvents.forEach((eventName) => {
+      state.emitter.off(eventName);
+    });
+  }
+
   /**
    * Schedule a state update via queueMicrotask
    *

package/src/core/textures/Texture.ts

@@ -22,6 +22,11 @@ import type { SubTextureProps } from './SubTexture.js';
 import type { Dimensions } from '../../common/CommonTypes.js';
 import { EventEmitter } from '../../common/EventEmitter.js';
 
+/**
+ * Event handler for when a Texture is freed
+ */
+export type TextureFreedEventHandler = (target: any) => void;
+
 /**
  * Event handler for when a Texture is loading
  */
@@ -94,9 +99,10 @@ export interface TextureData {
   premultiplyAlpha?: boolean | null;
 }
 
-export type TextureState = 'loading' | 'loaded' | 'failed';
+export type TextureState = 'freed' | 'loading' | 'loaded' | 'failed';
 
 export interface TextureStateEventMap {
+  freed: TextureFreedEventHandler;
   loading: TextureLoadingEventHandler;
   loaded: TextureLoadedEventHandler;
   failed: TextureFailedEventHandler;
@@ -135,12 +141,43 @@ export abstract class Texture extends EventEmitter {
 
   readonly error: Error | null = null;
 
-  readonly state: TextureState = 'loading';
+  readonly state: TextureState = 'freed';
+
+  readonly renderableOwners = new Set<unknown>();
 
   constructor(protected txManager: CoreTextureManager) {
     super();
   }
 
+  /**
+   * Add/remove an owner to/from the Texture based on its renderability.
+   *
+   * @remarks
+   * Any object can own a texture, be it a CoreNode or even the state object
+   * from a Text Renderer.
+   *
+   * When the reference to the texture that an owner object holds is replaced
+   * or cleared it must call this with `renderable=false` to release the owner
+   * association.
+   *
+   * @param owner
+   * @param renderable
+   */
+  setRenderableOwner(owner: unknown, renderable: boolean): void {
+    if (renderable) {
+      this.renderableOwners.add(owner);
+    } else {
+      this.renderableOwners.delete(owner);
+    }
+  }
+
+  /**
+   * Returns true if the texture is assigned to any Nodes that are renderable.
+   */
+  get renderable(): boolean {
+    return this.renderableOwners.size > 0;
+  }
+
   /**
    * Set the state of the texture
    *

package/src/main-api/ICoreDriver.ts

@@ -63,4 +63,6 @@ export interface ICoreDriver {
   onFpsUpdate(fpsData: FpsUpdatePayload): void;
 
   onFrameTick(frameTickData: FrameTickPayload): void;
+
+  onIdle?(): void;
 }

package/src/main-api/Inspector.ts

@@ -9,6 +9,7 @@ import type { ICoreDriver } from './ICoreDriver.js';
 import { type RendererMainSettings } from './RendererMain.js';
 import type { AnimationSettings } from '../core/animations/CoreAnimation.js';
 import type { IAnimationController } from '../common/IAnimationController.js';
+import { isProductionEnvironment } from '../utils.js';
 
 /**
  * Inspector
@@ -152,7 +153,7 @@ export class Inspector {
   private scaleY = 1;
 
   constructor(canvas: HTMLCanvasElement, settings: RendererMainSettings) {
-    if (import.meta.env.PROD) return;
+    if (isProductionEnvironment()) return;
 
     if (!settings) {
       throw new Error('settings is required');

package/src/main-api/RendererMain.ts

@@ -40,6 +40,7 @@ import type { TextureUsageTracker } from './texture-usage-trackers/TextureUsageT
 import { EventEmitter } from '../common/EventEmitter.js';
 import { Inspector } from './Inspector.js';
 import { santizeCustomDataMap } from '../render-drivers/utils.js';
+import { isProductionEnvironment } from '../utils.js';
 
 /**
  * An immutable reference to a specific Texture type
@@ -127,11 +128,22 @@ export interface RendererMainSettings {
   appHeight?: number;
 
   /**
-   * Bounds margin to extend the boundary in which a CoreNode is added as Quad.
+   * Texture Memory Byte Threshold
    *
+   * @remarks
+   * When the amount of GPU VRAM used by textures exceeds this threshold,
+   * the Renderer will free up all the textures that are current not visible
+   * within the configured `boundsMargin`.
    *
+   * When set to `0`, the threshold-based texture memory manager is disabled.
+   */
+  txMemByteThreshold?: number;
+
+  /**
+   * Bounds margin to extend the boundary in which a CoreNode is added as Quad.
    */
   boundsMargin?: number | [number, number, number, number];
+
   /**
    * Factor to convert app-authored logical coorindates to device logical coordinates
    *
@@ -317,6 +329,7 @@ export class RendererMain extends EventEmitter {
     const resolvedSettings: Required<RendererMainSettings> = {
       appWidth: settings.appWidth || 1920,
       appHeight: settings.appHeight || 1080,
+      txMemByteThreshold: settings.txMemByteThreshold || 124e6,
       boundsMargin: settings.boundsMargin || 0,
       deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
       devicePhysicalPixelRatio:
@@ -397,9 +410,13 @@ export class RendererMain extends EventEmitter {
       this.emit('frameTick', frameTickData);
     };
 
+    driver.onIdle = () => {
+      this.emit('idle');
+    };
+
     targetEl.appendChild(canvas);
 
-    if (enableInspector && !import.meta.env.PROD) {
+    if (enableInspector && !isProductionEnvironment()) {
       this.inspector = new Inspector(canvas, resolvedSettings);
     }
   }

package/src/render-drivers/main/MainCoreDriver.ts

@@ -55,6 +55,7 @@ export class MainCoreDriver implements ICoreDriver {
       rootId: getNewId(),
       appWidth: rendererSettings.appWidth,
       appHeight: rendererSettings.appHeight,
+      txMemByteThreshold: rendererSettings.txMemByteThreshold,
       boundsMargin: rendererSettings.boundsMargin,
       deviceLogicalPixelRatio: rendererSettings.deviceLogicalPixelRatio,
       devicePhysicalPixelRatio: rendererSettings.devicePhysicalPixelRatio,
@@ -92,6 +93,10 @@ export class MainCoreDriver implements ICoreDriver {
     this.stage.on('frameTick', ((stage, frameTickData) => {
       this.onFrameTick(frameTickData);
     }) satisfies StageFrameTickHandler);
+
+    this.stage.on('idle', () => {
+      this.onIdle();
+    });
   }
 
   createNode(props: INodeWritableProps): INode {
@@ -145,5 +150,9 @@ export class MainCoreDriver implements ICoreDriver {
   onFrameTick(frameTickData: FrameTickPayload) {
     throw new Error('Method not implemented.');
   }
+
+  onIdle() {
+    throw new Error('Method not implemented.');
+  }
   //#endregion
 }

package/src/render-drivers/main/MainOnlyNode.ts

@@ -108,6 +108,7 @@ export class MainOnlyNode extends EventEmitter implements INode {
     // Forward loaded/failed events
     this.coreNode.on('loaded', this.onTextureLoaded);
     this.coreNode.on('failed', this.onTextureFailed);
+    this.coreNode.on('freed', this.onTextureFreed);
 
     this.coreNode.on('outOfBounds', this.onOutOfBounds);
     this.coreNode.on('inBounds', this.onInBounds);
@@ -420,6 +421,10 @@ export class MainOnlyNode extends EventEmitter implements INode {
     this.emit('failed', payload);
   };
 
+  private onTextureFreed: NodeLoadedEventHandler = (target, payload) => {
+    this.emit('freed', payload);
+  };
+
   private onOutOfBounds: NodeRenderStateEventHandler = (target, payload) => {
     this.emit('outOfBounds', payload);
   };
@@ -461,13 +466,14 @@ export class MainOnlyNode extends EventEmitter implements INode {
 
   destroy(): void {
     this.emit('beforeDestroy', {});
-    this.coreNode.destroy();
-    // destroy children
-    const length = this.children.length;
-    for (let i = 0; i < length; i++) {
-      this.children[i]?.destroy();
+
+    //use while loop since setting parent to null removes it from array
+    let child = this.children[0];
+    while (child) {
+      child.destroy();
+      child = this.children[0];
     }
-    this.children.length = 0;
+    this.coreNode.destroy();
     this.parent = null;
     this.texture = null;
     this.emit('afterDestroy', {});

package/src/render-drivers/threadx/ThreadXCoreDriver.ts

@@ -112,6 +112,7 @@ export class ThreadXCoreDriver implements ICoreDriver {
         canvas: offscreenCanvas,
         appWidth: rendererSettings.appWidth,
         appHeight: rendererSettings.appHeight,
+        txMemByteThreshold: rendererSettings.txMemByteThreshold,
         boundsMargin: rendererSettings.boundsMargin,
         deviceLogicalPixelRatio: rendererSettings.deviceLogicalPixelRatio,
         devicePhysicalPixelRatio: rendererSettings.devicePhysicalPixelRatio,

package/src/render-drivers/threadx/ThreadXRendererMessage.ts

@@ -44,6 +44,7 @@ export interface ThreadXRendererInitMessage extends ThreadXRendererMessage {
   canvas: OffscreenCanvas;
   appWidth: number;
   appHeight: number;
+  txMemByteThreshold: number;
   boundsMargin: number | [number, number, number, number];
   deviceLogicalPixelRatio: number;
   devicePhysicalPixelRatio: number;

package/src/render-drivers/threadx/worker/ThreadXRendererNode.ts

@@ -33,6 +33,7 @@ import type { AnimationSettings } from '../../../core/animations/CoreAnimation.j
 import type {
   NodeLoadedPayload,
   NodeFailedPayload,
+  NodeTextureFreedPayload,
 } from '../../../common/CommonTypes.js';
 
 export class ThreadXRendererNode extends SharedNode {
@@ -143,6 +144,12 @@ export class ThreadXRendererNode extends SharedNode {
         this.emit('failed', payload);
       },
     );
+    this.coreNode.on(
+      'freed',
+      (target: CoreNode, payload: NodeTextureFreedPayload) => {
+        this.emit('freed', payload);
+      },
+    );
   }
 
   override onPropertyChange<Key extends keyof this['z$__type__Props']>(

package/src/render-drivers/threadx/worker/renderer.ts

@@ -66,6 +66,7 @@ const threadx = ThreadX.init({
         rootId: nodeStruct.id,
         appWidth: message.appWidth,
         appHeight: message.appHeight,
+        txMemByteThreshold: message.txMemByteThreshold,
         boundsMargin: message.boundsMargin,
         deviceLogicalPixelRatio: message.deviceLogicalPixelRatio,
         devicePhysicalPixelRatio: message.devicePhysicalPixelRatio,

package/src/utils.ts

@@ -79,7 +79,7 @@ export function assertTruthy(
   condition: unknown,
   message?: string,
 ): asserts condition {
-  if (import.meta.env.PROD) return;
+  if (isProductionEnvironment()) return;
   if (!condition) {
     throw new Error(message || 'Assertion failed');
   }
@@ -205,3 +205,12 @@ export function hasOwn(obj: object, prop: string | number | symbol): boolean {
 export function deg2Rad(degrees: number): number {
   return (degrees * Math.PI) / 180;
 }
+
+/**
+ * Checks import.meta if env is production
+ *
+ * @returns
+ */
+export function isProductionEnvironment(): boolean {
+  return import.meta.env && import.meta.env.PROD;
+}