@lightningjs/renderer 0.9.3 → 1.0.0-rc.0

package/src/core/Stage.ts

@@ -20,10 +20,10 @@ import { startLoop, getTimeStamp } from './platform.js';
 import { WebGlCoreRenderer } from './renderers/webgl/WebGlCoreRenderer.js';
 import { assertTruthy, setPremultiplyMode } from '../utils.js';
 import { AnimationManager } from './animations/AnimationManager.js';
-import { CoreNode } from './CoreNode.js';
+import { CoreNode, type CoreNodeProps } from './CoreNode.js';
 import { CoreTextureManager } from './CoreTextureManager.js';
 import { TrFontManager } from './text-rendering/TrFontManager.js';
-import { CoreShaderManager } from './CoreShaderManager.js';
+import { CoreShaderManager, type ShaderMap } from './CoreShaderManager.js';
 import type {
   TextRenderer,
   TextRendererMap,
@@ -37,18 +37,23 @@ import type {
   FpsUpdatePayload,
   FrameTickPayload,
 } from '../common/CommonTypes.js';
-import { TextureMemoryManager } from './TextureMemoryManager.js';
+import {
+  TextureMemoryManager,
+  type TextureMemoryManagerSettings,
+} from './TextureMemoryManager.js';
 import type {
   CoreRenderer,
   CoreRendererOptions,
 } from './renderers/CoreRenderer.js';
 import { CanvasCoreRenderer } from './renderers/canvas/CanvasCoreRenderer.js';
+import type { BaseShaderController } from '../main-api/ShaderController.js';
+import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
+import { santizeCustomDataMap } from '../main-api/utils.js';
 
 export interface StageOptions {
-  rootId: number;
   appWidth: number;
   appHeight: number;
-  txMemByteThreshold: number;
+  textureMemory: TextureMemoryManagerSettings;
   boundsMargin: number | [number, number, number, number];
   deviceLogicalPixelRatio: number;
   devicePhysicalPixelRatio: number;
@@ -58,10 +63,7 @@ export interface StageOptions {
   enableContextSpy: boolean;
   numImageWorkers: number;
   renderMode: 'webgl' | 'canvas';
-
-  debug?: {
-    monitorTextureCache?: boolean;
-  };
+  eventBus: EventEmitter;
 }
 
 export type StageFpsUpdateHandler = (
@@ -77,7 +79,7 @@ export type StageFrameTickHandler = (
 const bufferMemory = 2e6;
 const autoStart = true;
 
-export class Stage extends EventEmitter {
+export class Stage {
   /// Module Instances
   public readonly animationManager: AnimationManager;
   public readonly txManager: CoreTextureManager;
@@ -88,6 +90,17 @@ export class Stage extends EventEmitter {
   public readonly renderer: CoreRenderer;
   public readonly root: CoreNode;
   public readonly boundsMargin: [number, number, number, number];
+  public readonly defShaderCtr: BaseShaderController;
+
+  /**
+   * Renderer Event Bus for the Stage to emit events onto
+   *
+   * @remarks
+   * In reality this is just the RendererMain instance, which is an EventEmitter.
+   * this allows us to directly emit events from the Stage to RendererMain
+   * without having to set up forwarding handlers.
+   */
+  public readonly eventBus: EventEmitter;
 
   /// State
   deltaTime = 0;
@@ -96,6 +109,7 @@ export class Stage extends EventEmitter {
   private fpsNumFrames = 0;
   private fpsElapsedTime = 0;
   private renderRequested = false;
+  private frameEventQueue: [name: string, payload: unknown][] = [];
 
   /// Debug data
   contextSpy: ContextSpy | null = null;
@@ -104,23 +118,21 @@ export class Stage extends EventEmitter {
    * Stage constructor
    */
   constructor(readonly options: StageOptions) {
-    super();
     const {
       canvas,
       clearColor,
-      rootId,
-      debug,
       appWidth,
       appHeight,
       boundsMargin,
       enableContextSpy,
       numImageWorkers,
-      txMemByteThreshold,
+      textureMemory,
       renderMode,
     } = options;
 
+    this.eventBus = options.eventBus;
     this.txManager = new CoreTextureManager(numImageWorkers);
-    this.txMemManager = new TextureMemoryManager(txMemByteThreshold);
+    this.txMemManager = new TextureMemoryManager(this, textureMemory);
     this.shManager = new CoreShaderManager();
     this.animationManager = new AnimationManager();
     this.contextSpy = enableContextSpy ? new ContextSpy() : null;
@@ -133,15 +145,6 @@ export class Stage extends EventEmitter {
     }
     this.boundsMargin = bm;
 
-    if (debug?.monitorTextureCache) {
-      setInterval(() => {
-        assertTruthy(this.txManager);
-        const debugInfo = this.txManager.getDebugInfo();
-        console.log('Texture ID Cache Size: ', debugInfo.idCacheSize);
-        console.log('Texture Key Cache Size: ', debugInfo.keyCacheSize);
-      }, 1000);
-    }
-
     const rendererOptions: CoreRendererOptions = {
       stage: this,
       canvas,
@@ -160,6 +163,7 @@ export class Stage extends EventEmitter {
     } else {
       this.renderer = new WebGlCoreRenderer(rendererOptions);
     }
+    this.defShaderCtr = this.renderer.getDefShaderCtr();
     setPremultiplyMode(renderMode);
 
     // Must do this after renderer is created
@@ -178,7 +182,6 @@ export class Stage extends EventEmitter {
 
     // create root node
     const rootNode = new CoreNode(this, {
-      id: rootId,
       x: 0,
       y: 0,
       width: appWidth,
@@ -208,10 +211,11 @@ export class Stage extends EventEmitter {
       rotation: 0,
       parent: null,
       texture: null,
-      textureOptions: null,
-      shader: null,
-      shaderProps: null,
+      textureOptions: {},
+      shader: this.defShaderCtr,
       rtt: false,
+      src: null,
+      scale: 1,
     });
 
     this.root = rootNode;
@@ -222,6 +226,24 @@ export class Stage extends EventEmitter {
     }
   }
 
+  updateFrameTime() {
+    const newFrameTime = getTimeStamp();
+    this.lastFrameTime = this.currentFrameTime;
+    this.currentFrameTime = newFrameTime;
+    this.deltaTime = !this.lastFrameTime
+      ? 100 / 6
+      : newFrameTime - this.lastFrameTime;
+    this.txManager.frameTime = newFrameTime;
+    this.txMemManager.frameTime = newFrameTime;
+
+    // This event is emitted at the beginning of the frame (before any updates
+    // or rendering), so no need to to use `stage.queueFrameEvent` here.
+    this.eventBus.emit('frameTick', {
+      time: this.currentFrameTime,
+      delta: this.deltaTime,
+    });
+  }
+
   /**
    * Update animations
    */
@@ -230,17 +252,6 @@ export class Stage extends EventEmitter {
     if (!this.root) {
       return;
     }
-    this.lastFrameTime = this.currentFrameTime;
-    this.currentFrameTime = getTimeStamp();
-
-    this.deltaTime = !this.lastFrameTime
-      ? 100 / 6
-      : this.currentFrameTime - this.lastFrameTime;
-
-    this.emit('frameTick', {
-      time: this.currentFrameTime,
-      delta: this.deltaTime,
-    });
     // step animation
     animationManager.update(this.deltaTime);
   }
@@ -267,9 +278,9 @@ export class Stage extends EventEmitter {
     // Reset render operations and clear the canvas
     renderer.reset();
 
-    // Check if we need to garbage collect
-    if (renderer.txMemManager.gcRequested) {
-      renderer.txMemManager.gc();
+    // Check if we need to cleanup textures
+    if (this.txMemManager.criticalCleanupRequested) {
+      this.txMemManager.cleanup();
     }
 
     // If we have RTT nodes draw them first
@@ -292,6 +303,40 @@ export class Stage extends EventEmitter {
     }
   }
 
+  /**
+   * Queue an event to be emitted after the current/next frame is rendered
+   *
+   * @remarks
+   * When we are operating in the context of the render loop, we may want to
+   * emit events that are related to the current frame. However, we generally do
+   * NOT want to emit events directly in the middle of the render loop, since
+   * this could enable event handlers to modify the scene graph and cause
+   * unexpected behavior. Instead, we queue up events to be emitted and then
+   * flush the queue after the frame has been rendered.
+   *
+   * @param name
+   * @param data
+   */
+  queueFrameEvent(name: string, data: unknown) {
+    this.frameEventQueue.push([name, data]);
+  }
+
+  /**
+   * Emit all queued frame events
+   *
+   * @remarks
+   * This method should be called after the frame has been rendered to emit
+   * all events that were queued during the frame.
+   *
+   * See {@link queueFrameEvent} for more information.
+   */
+  flushFrameEvents() {
+    for (const [name, data] of this.frameEventQueue) {
+      this.eventBus.emit(name, data);
+    }
+    this.frameEventQueue = [];
+  }
+
   calculateFps() {
     // If there's an FPS update interval, emit the FPS update event
     // when the specified interval has elapsed.
@@ -305,7 +350,7 @@ export class Stage extends EventEmitter {
         );
         this.fpsNumFrames = 0;
         this.fpsElapsedTime = 0;
-        this.emit('fpsUpdate', {
+        this.queueFrameEvent('fpsUpdate', {
           fps,
           contextSpyData: this.contextSpy?.getData() ?? null,
         } satisfies FpsUpdatePayload);
@@ -407,4 +452,115 @@ export class Stage extends EventEmitter {
     // the covariant state argument in the setter method map
     return resolvedTextRenderer as unknown as TextRenderer;
   }
+
+  /**
+   * Create a shader controller instance
+   *
+   * @param type
+   * @param props
+   * @returns
+   */
+  createShaderCtr(
+    type: keyof ShaderMap,
+    props: Record<string, unknown>,
+  ): BaseShaderController {
+    return this.shManager.loadShader(type, props);
+  }
+
+  createNode(props: Partial<CoreNodeProps>) {
+    const resolvedProps = this.resolveNodeDefaults(props);
+    return new CoreNode(this, resolvedProps);
+  }
+
+  createTextNode(props: Partial<CoreTextNodeProps>) {
+    const fontSize = props.fontSize ?? 16;
+    const resolvedProps = {
+      ...this.resolveNodeDefaults(props),
+      text: props.text ?? '',
+      textRendererOverride: props.textRendererOverride ?? null,
+      fontSize,
+      fontFamily: props.fontFamily ?? 'sans-serif',
+      fontStyle: props.fontStyle ?? 'normal',
+      fontWeight: props.fontWeight ?? 'normal',
+      fontStretch: props.fontStretch ?? 'normal',
+      textAlign: props.textAlign ?? 'left',
+      contain: props.contain ?? 'none',
+      scrollable: props.scrollable ?? false,
+      scrollY: props.scrollY ?? 0,
+      offsetY: props.offsetY ?? 0,
+      letterSpacing: props.letterSpacing ?? 0,
+      lineHeight: props.lineHeight, // `undefined` is a valid value
+      maxLines: props.maxLines ?? 0,
+      textBaseline: props.textBaseline ?? 'alphabetic',
+      verticalAlign: props.verticalAlign ?? 'middle',
+      overflowSuffix: props.overflowSuffix ?? '...',
+      debug: props.debug ?? {},
+      shaderProps: null,
+    };
+
+    return new CoreTextNode(this, resolvedProps);
+  }
+
+  /**
+   * Resolves the default property values for a Node
+   *
+   * @remarks
+   * This method is used internally by the RendererMain to resolve the default
+   * property values for a Node. It is exposed publicly so that it can be used
+   * by Core Driver implementations.
+   *
+   * @param props
+   * @returns
+   */
+  protected resolveNodeDefaults(props: Partial<CoreNodeProps>): CoreNodeProps {
+    const color = props.color ?? 0xffffffff;
+    const colorTl = props.colorTl ?? props.colorTop ?? props.colorLeft ?? color;
+    const colorTr =
+      props.colorTr ?? props.colorTop ?? props.colorRight ?? color;
+    const colorBl =
+      props.colorBl ?? props.colorBottom ?? props.colorLeft ?? color;
+    const colorBr =
+      props.colorBr ?? props.colorBottom ?? props.colorRight ?? color;
+    const data = santizeCustomDataMap(props.data ?? {});
+
+    return {
+      x: props.x ?? 0,
+      y: props.y ?? 0,
+      width: props.width ?? 0,
+      height: props.height ?? 0,
+      alpha: props.alpha ?? 1,
+      autosize: props.autosize ?? false,
+      clipping: props.clipping ?? false,
+      color,
+      colorTop: props.colorTop ?? color,
+      colorBottom: props.colorBottom ?? color,
+      colorLeft: props.colorLeft ?? color,
+      colorRight: props.colorRight ?? color,
+      colorBl,
+      colorBr,
+      colorTl,
+      colorTr,
+      zIndex: props.zIndex ?? 0,
+      zIndexLocked: props.zIndexLocked ?? 0,
+      parent: props.parent ?? null,
+      texture: props.texture ?? null,
+      textureOptions: props.textureOptions ?? {},
+      shader: props.shader ?? this.defShaderCtr,
+      // Since setting the `src` will trigger a texture load, we need to set it after
+      // we set the texture. Otherwise, problems happen.
+      src: props.src ?? '',
+      scale: props.scale ?? null,
+      scaleX: props.scaleX ?? props.scale ?? 1,
+      scaleY: props.scaleY ?? props.scale ?? 1,
+      mount: props.mount ?? 0,
+      mountX: props.mountX ?? props.mount ?? 0,
+      mountY: props.mountY ?? props.mount ?? 0,
+      pivot: props.pivot ?? 0.5,
+      pivotX: props.pivotX ?? props.pivot ?? 0.5,
+      pivotY: props.pivotY ?? props.pivot ?? 0.5,
+      rotation: props.rotation ?? 0,
+      rtt: props.rtt ?? false,
+      data: data,
+    };
+  }
 }

package/src/core/TextureMemoryManager.ts

@@ -16,53 +16,262 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { CoreContextTexture } from './renderers/CoreContextTexture.js';
+import type { Stage } from './Stage.js';
+import type { Texture } from './textures/Texture.js';
+import { bytesToMb } from './utils.js';
 
+export interface TextureMemoryManagerSettings {
+  /**
+   * Critical Threshold (in bytes)
+   *
+   * @remarks
+   * When the amount of memory used by textures exceeds this threshold,
+   * the Renderer will immediately trigger a Texture Cleanup towards the
+   * Target Threshold Level.
+   *
+   * When set to `0`, the Texture Memory Manager is disabled.
+   *
+   * @defaultValue `124e6` (118 MB)
+   */
+  criticalThreshold: number;
+
+  /**
+   * Target Threshold Level (as fraction of Critical Threshold)
+   *
+   * @remarks
+   * This value is the fractional level of the Critical Threshold that the
+   * Texture Memory Manager will attempt to maintain by cleaning up textures.
+   * The Texture Memory Manager will attempt to keep the memory usage below
+   * this level by freeing up non-renderable textures.
+   *
+   * Valid Range: 0.0 - 1.0
+   *
+   * @defaultValue `0.5`
+   */
+  targetThresholdLevel: number;
+
+  /**
+   * Interval between Texture Cleanups (in milliseconds)
+   *
+   * @remarks
+   * Texture Memory Manager will perform a Texture Cleanup no more
+   * frequently than this interval generally when the scene becomes idle.
+   *
+   * @defaultValue `30,000` (30 seconds)
+   */
+  cleanupInterval: number;
+
+  /**
+   * Whether or not to log debug information
+   *
+   * @defaultValue `false`
+   */
+  debugLogging: boolean;
+}
+
+export interface MemoryInfo {
+  criticalThreshold: number;
+  targetThreshold: number;
+  renderableMemUsed: number;
+  memUsed: number;
+  renderableTexturesLoaded: number;
+  loadedTextures: number;
+}
+
+/**
+ * LRU (Least Recently Used) style memory manager for textures
+ *
+ * @remarks
+ * This class is responsible for managing the memory usage of textures
+ * in the Renderer. It keeps track of the memory used by each texture
+ * and triggers a cleanup when the memory usage exceeds a critical
+ * threshold (`criticalThreshold`).
+ *
+ * The cleanup process will free up non-renderable textures until the
+ * memory usage is below a target threshold (`targetThresholdLevel`).
+ *
+ * The memory manager's clean up process will also be triggered when the
+ * scene is idle for a certain amount of time (`cleanupInterval`).
+ */
 export class TextureMemoryManager {
   private memUsed = 0;
-  private textures: Map<CoreContextTexture, number> = new Map();
-  private threshold: number;
-  public gcRequested = false;
-
+  private loadedTextures: Map<Texture, number> = new Map();
+  private criticalThreshold: number;
+  private targetThreshold: number;
+  private cleanupInterval: number;
+  private debugLogging: boolean;
+  private lastCleanupTime = 0;
+  public criticalCleanupRequested = false;
   /**
-   * @param byteThreshold Number of texture bytes to trigger garbage collection
+   * The current frame time in milliseconds
+   *
+   * @remarks
+   * This is used to determine when to perform Idle Texture Cleanups.
+   *
+   * Set by stage via `updateFrameTime` method.
    */
-  constructor(byteThreshold: number) {
-    this.threshold = byteThreshold;
+  public frameTime = 0;
+
+  constructor(private stage: Stage, settings: TextureMemoryManagerSettings) {
+    const { criticalThreshold } = settings;
+    this.criticalThreshold = Math.round(criticalThreshold);
+    const targetFraction = Math.max(
+      0,
+      Math.min(1, settings.targetThresholdLevel),
+    );
+    this.targetThreshold = Math.round(criticalThreshold * targetFraction);
+    this.cleanupInterval = settings.cleanupInterval;
+    this.debugLogging = settings.debugLogging;
+
+    if (settings.debugLogging) {
+      let lastMemUse = 0;
+      setInterval(() => {
+        if (lastMemUse !== this.memUsed) {
+          lastMemUse = this.memUsed;
+          console.log(
+            `[TextureMemoryManager] Memory used: ${bytesToMb(
+              this.memUsed,
+            )} mb / ${bytesToMb(this.criticalThreshold)} mb (${(
+              (this.memUsed / this.criticalThreshold) *
+              100
+            ).toFixed(1)}%)`,
+          );
+        }
+      }, 1000);
+    }
 
     // If the threshold is 0, we disable the memory manager by replacing the
     // setTextureMemUse method with a no-op function.
-    if (byteThreshold === 0) {
+    if (criticalThreshold === 0) {
       // eslint-disable-next-line @typescript-eslint/no-empty-function
       this.setTextureMemUse = () => {};
     }
   }
 
-  setTextureMemUse(ctxTexture: CoreContextTexture, byteSize: number) {
-    if (this.textures.has(ctxTexture)) {
+  setTextureMemUse(texture: Texture, byteSize: number) {
+    if (this.loadedTextures.has(texture)) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.memUsed -= this.textures.get(ctxTexture)!;
+      this.memUsed -= this.loadedTextures.get(texture)!;
     }
 
     if (byteSize === 0) {
-      this.textures.delete(ctxTexture);
+      this.loadedTextures.delete(texture);
       return;
     } else {
       this.memUsed += byteSize;
-      this.textures.set(ctxTexture, byteSize);
+      this.loadedTextures.set(texture, byteSize);
     }
 
-    if (this.memUsed > this.threshold) {
-      this.gcRequested = true;
+    if (this.memUsed > this.criticalThreshold) {
+      this.criticalCleanupRequested = true;
     }
   }
 
-  gc() {
-    this.gcRequested = false;
-    this.textures.forEach((byteSize, ctxTexture) => {
-      if (!ctxTexture.renderable) {
-        ctxTexture.free();
+  checkCleanup() {
+    return (
+      this.criticalCleanupRequested ||
+      (this.memUsed > this.targetThreshold &&
+        this.frameTime - this.lastCleanupTime >= this.cleanupInterval)
+    );
+  }
+
+  cleanup() {
+    const critical = this.criticalCleanupRequested;
+    this.lastCleanupTime = this.frameTime;
+    this.criticalCleanupRequested = false;
+
+    if (critical) {
+      this.stage.queueFrameEvent('criticalCleanup', {
+        memUsed: this.memUsed,
+        criticalThreshold: this.criticalThreshold,
+      });
+    }
+
+    if (this.debugLogging) {
+      console.log(
+        `[TextureMemoryManager] Cleaning up textures. Critical: ${critical}`,
+      );
+    }
+
+    /**
+     * Sort the loaded textures by renderability, then by last touch time.
+     *
+     * This will ensure that the array is ordered by the following:
+     * - Non-renderable textures, starting at the least recently rendered
+     * - Renderable textures, starting at the least recently rendered
+     */
+    const textures = [...this.loadedTextures.keys()].sort(
+      (textureA, textureB) => {
+        const txARenderable = textureA.renderable;
+        const txBRenderable = textureB.renderable;
+        if (txARenderable === txBRenderable) {
+          return (
+            textureA.lastRenderableChangeTime -
+            textureB.lastRenderableChangeTime
+          );
+        } else if (txARenderable) {
+          return 1;
+        } else if (txBRenderable) {
+          return -1;
+        }
+        return 0;
+      },
+    );
+
+    // Free non-renderable textures until we reach the target threshold
+    const memTarget = this.targetThreshold;
+    const txManager = this.stage.txManager;
+    for (const texture of textures) {
+      if (texture.renderable) {
+        // Stop at the first renderable texture (The rest are renderable because of the sort above)
+        // We don't want to free renderable textures because they will just likely be reloaded in the next frame
+        break;
+      }
+      texture.ctxTexture.free();
+      txManager.removeTextureFromCache(texture);
+      if (this.memUsed <= memTarget) {
+        // Stop once we've freed enough textures to reach under the target threshold
+        break;
       }
-    });
+    }
+
+    if (this.memUsed >= this.criticalThreshold) {
+      this.stage.queueFrameEvent('criticalCleanupFailed', {
+        memUsed: this.memUsed,
+        criticalThreshold: this.criticalThreshold,
+      });
+      console.warn(
+        `[TextureMemoryManager] Memory usage above critical threshold after cleanup: ${this.memUsed}`,
+      );
+    }
+  }
+
+  /**
+   * Get the current texture memory usage information
+   *
+   * @remarks
+   * This method is for debugging purposes and returns information about the
+   * current memory usage of the textures in the Renderer.
+   */
+  getMemoryInfo(): MemoryInfo {
+    let renderableTexturesLoaded = 0;
+    const renderableMemUsed = [...this.loadedTextures.keys()].reduce(
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      (acc, texture) => {
+        renderableTexturesLoaded += texture.renderable ? 1 : 0;
+        return (
+          acc + (texture.renderable ? this.loadedTextures.get(texture)! : 0)
+        );
+      },
+      0,
+    );
+    return {
+      criticalThreshold: this.criticalThreshold,
+      targetThreshold: this.targetThreshold,
+      renderableMemUsed,
+      memUsed: this.memUsed,
+      renderableTexturesLoaded,
+      loadedTextures: this.loadedTextures.size,
+    };
   }
 }