@lightningjs/renderer 3.0.0-beta1 → 3.0.0-beta11

package/src/main-api/Renderer.ts

@@ -19,16 +19,15 @@
 
 import type { ExtractProps, TextureMap } from '../core/CoreTextureManager.js';
 import { EventEmitter } from '../common/EventEmitter.js';
-import { assertTruthy, isProductionEnvironment } from '../utils.js';
-import { Stage } from '../core/Stage.js';
+import { isProductionEnvironment } from '../utils.js';
+import { Stage, type StageOptions } from '../core/Stage.js';
 import { CoreNode, type CoreNodeProps } from '../core/CoreNode.js';
 import { type CoreTextNodeProps } from '../core/CoreTextNode.js';
 import type { INode, INodeProps, ITextNode, ITextNodeProps } from './INode.js';
 import type { TextureMemoryManagerSettings } from '../core/TextureMemoryManager.js';
-import type { CanvasTextRenderer } from '../core/text-rendering/renderers/CanvasTextRenderer.js';
-import type { SdfTextRenderer } from '../core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
+import type { TextRenderer } from '../core/text-rendering/TextRenderer.js';
 import type { CanvasRenderer } from '../core/renderers/canvas/CanvasRenderer.js';
+import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
 import type { Inspector } from './Inspector.js';
 import type { CoreShaderNode } from '../core/renderers/CoreShaderNode.js';
 import type {
@@ -36,34 +35,36 @@ import type {
   OptionalShaderProps,
   ShaderMap,
 } from '../core/CoreShaderManager.js';
+import { WebPlatform } from '../core/platforms/web/WebPlatform.js';
+import { Platform } from '../core/platforms/Platform.js';
 
 /**
- * Configuration settings for {@link RendererMain}
+ * Settings for the Renderer that can be updated during runtime.
  */
-export interface RendererMainSettings {
+export interface RendererRuntimeSettings {
   /**
    * Authored logical pixel width of the application
    *
    * @defaultValue `1920`
    */
-  appWidth?: number;
+  appWidth: number;
 
   /**
    * Authored logical pixel height of the application
    *
    * @defaultValue `1080`
    */
-  appHeight?: number;
+  appHeight: number;
 
   /**
    * Texture Memory Manager Settings
    */
-  textureMemory?: Partial<TextureMemoryManagerSettings>;
+  textureMemory: Partial<TextureMemoryManagerSettings>;
 
   /**
    * Bounds margin to extend the boundary in which a Node is added as Quad.
    */
-  boundsMargin?: number | [number, number, number, number];
+  boundsMargin: number | [number, number, number, number];
 
   /**
    * Factor to convert app-authored logical coorindates to device logical coordinates
@@ -80,7 +81,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `1`
    */
-  deviceLogicalPixelRatio?: number;
+  deviceLogicalPixelRatio: number;
 
   /**
    * Factor to convert device logical coordinates to device physical coordinates
@@ -97,14 +98,14 @@ export interface RendererMainSettings {
    *
    * @defaultValue `window.devicePixelRatio`
    */
-  devicePhysicalPixelRatio?: number;
+  devicePhysicalPixelRatio: number;
 
   /**
    * RGBA encoded number of the background to use
    *
    * @defaultValue `0x00000000`
    */
-  clearColor?: number;
+  clearColor: number;
 
   /**
    * Interval in milliseconds to receive FPS updates
@@ -114,8 +115,51 @@ export interface RendererMainSettings {
    *
    * @defaultValue `0` (disabled)
    */
-  fpsUpdateInterval?: number;
+  fpsUpdateInterval: number;
+
+  /**
+   * DOM Inspector
+   *
+   * @remarks
+   * The inspector will replicate the state of the Nodes created
+   * in the renderer and allow inspection of the state of the nodes.
+   *
+   */
+  inspector: typeof Inspector | false;
 
+  /**
+   * Texture Processing Limit (in milliseconds)
+   *
+   * @remarks
+   * The maximum amount of time the renderer is allowed to process textures in a
+   * single frame. If the processing time exceeds this limit, the renderer will
+   * skip processing the remaining textures and continue rendering the frame.
+   *
+   * @defaultValue `10`
+   */
+  textureProcessingTimeLimit: number;
+
+  /**
+   * Target FPS for the global render loop
+   *
+   * @remarks
+   * Controls the maximum frame rate of the entire rendering system.
+   * When set to 0, no throttling is applied (use display refresh rate).
+   * When set to a positive number, the global requestAnimationFrame loop
+   * will be throttled to this target FPS, affecting all animations and rendering.
+   *
+   * This provides global performance control for the entire application,
+   * useful for managing performance on lower-end devices.
+   *
+   * @defaultValue `0` (no throttling, use display refresh rate)
+   */
+  targetFPS: number;
+}
+
+/**
+ * Configuration settings for {@link RendererMain}
+ */
+export type RendererMainSettings = RendererRuntimeSettings & {
   /**
    * Include context call (i.e. WebGL) information in FPS updates
    *
@@ -129,7 +173,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `false` (disabled)
    */
-  enableContextSpy?: boolean;
+  enableContextSpy: boolean;
 
   /**
    * Number or Image Workers to use
@@ -141,17 +185,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `2`
    */
-  numImageWorkers?: number;
-
-  /**
-   * DOM Inspector
-   *
-   * @remarks
-   * The inspector will replicate the state of the Nodes created
-   * in the renderer and allow inspection of the state of the nodes.
-   *
-   */
-  inspector?: typeof Inspector | false;
+  numImageWorkers: number;
 
   /**
    * Renderer Engine
@@ -173,7 +207,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue 4 * 1024 * 1024
    */
-  quadBufferSize?: number;
+  quadBufferSize: number;
 
   /**
    * Font Engines
@@ -203,7 +237,7 @@ export interface RendererMainSettings {
    *
    *
    */
-  fontEngines: (typeof SdfTextRenderer | typeof CanvasTextRenderer)[];
+  fontEngines: TextRenderer[];
 
   /**
    * Force WebGL2
@@ -214,7 +248,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `false`
    */
-  forceWebGL2?: boolean;
+  forceWebGL2: boolean;
 
   /**
    * Enable strictBounds
@@ -225,19 +259,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `true`
    */
-  strictBounds?: boolean;
-
-  /**
-   * Texture Processing Limit (in milliseconds)
-   *
-   * @remarks
-   * The maximum amount of time the renderer is allowed to process textures in a
-   * single frame. If the processing time exceeds this limit, the renderer will
-   * skip processing the remaining textures and continue rendering the frame.
-   *
-   * @defaultValue `10`
-   */
-  textureProcessingTimeLimit?: number;
+  strictBounds: boolean;
 
   /**
    * Canvas object to use for rendering
@@ -246,7 +268,7 @@ export interface RendererMainSettings {
    * This is used to render the scene graph. If not provided, a new canvas
    * element will be created and appended to the target element.
    */
-  canvas?: HTMLCanvasElement;
+  canvas: HTMLCanvasElement;
 
   /**
    * createImageBitmap support for the runtime
@@ -271,8 +293,20 @@ export interface RendererMainSettings {
    *
    * @defaultValue `full`
    */
-  createImageBitmapSupport?: 'auto' | 'basic' | 'options' | 'full';
-}
+  createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
+
+  /**
+   * Provide an alternative platform abstraction layer
+   *
+   * @remarks
+   * By default the Lightning 3 renderer will load a webplatform, assuming it runs
+   * inside a web browsr. However for special cases there might be a need to provide
+   * an abstracted platform layer to run on non-web or non-standard JS engines
+   *
+   * @defaultValue `null`
+   */
+  platform: typeof Platform | null;
+};
 
 /**
  * The Renderer Main API
@@ -327,7 +361,6 @@ export interface RendererMainSettings {
 export class RendererMain extends EventEmitter {
   readonly root: INode;
   readonly canvas: HTMLCanvasElement;
-  readonly settings: Readonly<Required<RendererMainSettings>>;
   readonly stage: Stage;
   private inspector: Inspector | null = null;
 
@@ -338,21 +371,17 @@ export class RendererMain extends EventEmitter {
    * @param target Element ID or HTMLElement to insert the canvas into
    * @param driver Core Driver to use
    */
-  constructor(settings: RendererMainSettings, target: string | HTMLElement) {
+  constructor(
+    settings: Partial<RendererMainSettings>,
+    target: string | HTMLElement,
+  ) {
     super();
 
-    const resolvedTxSettings: TextureMemoryManagerSettings = {
-      criticalThreshold: settings.textureMemory?.criticalThreshold || 124e6,
-      targetThresholdLevel: settings.textureMemory?.targetThresholdLevel || 0.5,
-      cleanupInterval: settings.textureMemory?.cleanupInterval || 5000,
-      debugLogging: settings.textureMemory?.debugLogging || false,
-      baselineMemoryAllocation:
-        settings.textureMemory?.baselineMemoryAllocation || 26e6,
-      doNotExceedCriticalThreshold:
-        settings.textureMemory?.doNotExceedCriticalThreshold || false,
-    };
+    const resolvedTxSettings = this.resolveTxSettings(
+      settings.textureMemory || {},
+    );
 
-    const resolvedSettings: Required<RendererMainSettings> = {
+    settings = {
       appWidth: settings.appWidth || 1920,
       appHeight: settings.appHeight || 1080,
       textureMemory: resolvedTxSettings,
@@ -362,6 +391,7 @@ export class RendererMain extends EventEmitter {
         settings.devicePhysicalPixelRatio || window.devicePixelRatio,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+      targetFPS: settings.targetFPS || 0,
       numImageWorkers:
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
       enableContextSpy: settings.enableContextSpy ?? false,
@@ -369,13 +399,13 @@ export class RendererMain extends EventEmitter {
       inspector: settings.inspector ?? false,
       renderEngine: settings.renderEngine,
       quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
-      fontEngines: settings.fontEngines,
+      fontEngines: settings.fontEngines ?? [],
       strictBounds: settings.strictBounds ?? true,
-      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 42,
       canvas: settings.canvas || document.createElement('canvas'),
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+      platform: settings.platform || null,
     };
-    this.settings = resolvedSettings;
 
     const {
       appWidth,
@@ -384,7 +414,19 @@ export class RendererMain extends EventEmitter {
       devicePhysicalPixelRatio,
       inspector,
       canvas,
-    } = resolvedSettings;
+    } = settings as RendererMainSettings;
+
+    let platform;
+    if (
+      settings.platform !== undefined &&
+      settings.platform !== null &&
+      settings.platform.prototype instanceof Platform === true
+    ) {
+      // @ts-ignore - if Platform is a valid class, it will be used
+      platform = new settings.platform();
+    } else {
+      platform = new WebPlatform();
+    }
 
     const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
     const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
@@ -398,26 +440,28 @@ export class RendererMain extends EventEmitter {
 
     // Initialize the stage
     this.stage = new Stage({
-      appWidth: this.settings.appWidth,
-      appHeight: this.settings.appHeight,
-      boundsMargin: this.settings.boundsMargin,
-      clearColor: this.settings.clearColor,
+      appWidth,
+      appHeight,
+      boundsMargin: settings.boundsMargin!,
+      clearColor: settings.clearColor!,
       canvas: this.canvas,
-      deviceLogicalPixelRatio: this.settings.deviceLogicalPixelRatio,
-      devicePhysicalPixelRatio: this.settings.devicePhysicalPixelRatio,
-      enableContextSpy: this.settings.enableContextSpy,
-      forceWebGL2: this.settings.forceWebGL2,
-      fpsUpdateInterval: this.settings.fpsUpdateInterval,
-      numImageWorkers: this.settings.numImageWorkers,
-      renderEngine: this.settings.renderEngine,
+      deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio,
+      enableContextSpy: settings.enableContextSpy!,
+      forceWebGL2: settings.forceWebGL2!,
+      fpsUpdateInterval: settings.fpsUpdateInterval!,
+      numImageWorkers: settings.numImageWorkers!,
+      renderEngine: settings.renderEngine!,
       textureMemory: resolvedTxSettings,
       eventBus: this,
-      quadBufferSize: this.settings.quadBufferSize,
-      fontEngines: this.settings.fontEngines,
-      inspector: this.settings.inspector !== null,
-      strictBounds: this.settings.strictBounds,
-      textureProcessingTimeLimit: this.settings.textureProcessingTimeLimit,
-      createImageBitmapSupport: this.settings.createImageBitmapSupport,
+      quadBufferSize: settings.quadBufferSize!,
+      fontEngines: settings.fontEngines!,
+      inspector: settings.inspector !== null,
+      strictBounds: settings.strictBounds!,
+      targetFPS: settings.targetFPS!,
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
+      createImageBitmapSupport: settings.createImageBitmapSupport!,
+      platform,
     });
 
     // Extract the root node
@@ -438,11 +482,49 @@ export class RendererMain extends EventEmitter {
     targetEl.appendChild(canvas);
 
     // Initialize inspector (if enabled)
-    if (inspector && !isProductionEnvironment()) {
-      this.inspector = new inspector(canvas, resolvedSettings);
+    if (inspector && isProductionEnvironment === false) {
+      this.inspector = new inspector(canvas, settings as RendererMainSettings);
     }
   }
 
+  /**
+   * Resolves the Texture Memory Manager values
+   *
+   * @param props
+   * @returns
+   */
+  private resolveTxSettings(
+    textureMemory: Partial<TextureMemoryManagerSettings>,
+  ): TextureMemoryManagerSettings {
+    const currentTxSettings =
+      (this.stage && this.stage.options.textureMemory) || {};
+
+    return {
+      criticalThreshold:
+        textureMemory?.criticalThreshold ??
+        currentTxSettings?.criticalThreshold ??
+        124e6,
+      targetThresholdLevel:
+        textureMemory?.targetThresholdLevel ??
+        currentTxSettings?.targetThresholdLevel ??
+        0.5,
+      cleanupInterval:
+        textureMemory?.cleanupInterval ??
+        currentTxSettings?.cleanupInterval ??
+        5000,
+      debugLogging:
+        textureMemory?.debugLogging ?? currentTxSettings?.debugLogging ?? false,
+      baselineMemoryAllocation:
+        textureMemory?.baselineMemoryAllocation ??
+        currentTxSettings?.baselineMemoryAllocation ??
+        26e6,
+      doNotExceedCriticalThreshold:
+        textureMemory?.doNotExceedCriticalThreshold ??
+        currentTxSettings?.doNotExceedCriticalThreshold ??
+        false,
+    };
+  }
+
   /**
    * Create a new scene graph node
    *
@@ -461,16 +543,12 @@ export class RendererMain extends EventEmitter {
   createNode<ShNode extends CoreShaderNode<any>>(
     props: Partial<INodeProps<ShNode>>,
   ): INode<ShNode> {
-    assertTruthy(this.stage, 'Stage is not initialized');
-
     const node = this.stage.createNode(props as Partial<CoreNodeProps>);
 
     if (this.inspector) {
       return this.inspector.createNode(node) as unknown as INode<ShNode>;
     }
 
-    // FIXME onDestroy event? node.once('beforeDestroy'
-    // FIXME onCreate event?
     return node as unknown as INode<ShNode>;
   }
 
@@ -557,7 +635,7 @@ export class RendererMain extends EventEmitter {
     props?: OptionalShaderProps<ShType>,
   ) {
     return this.stage.shManager.createShader(shType, props) as CoreShaderNode<
-      ExtractShaderProps<ShType>
+      NonNullable<ExtractShaderProps<ShType>>
     >;
   }
 
@@ -646,4 +724,150 @@ export class RendererMain extends EventEmitter {
   setClearColor(color: number) {
     this.stage.setClearColor(color);
   }
+
+  /**
+   * Set options for the renderer
+   *
+   * @param options
+   */
+  setOptions(options: Partial<RendererRuntimeSettings>) {
+    const stage = this.stage;
+    if (options.textureMemory !== undefined) {
+      const textureMemory = (options.textureMemory = this.resolveTxSettings(
+        options.textureMemory,
+      ));
+      stage.txMemManager.updateSettings(textureMemory);
+      stage.txMemManager.cleanup();
+    }
+
+    if (options.boundsMargin !== undefined) {
+      let bm = options.boundsMargin!;
+      options.boundsMargin = Array.isArray(bm) ? bm : [bm, bm, bm, bm];
+    }
+
+    const stageOptions = stage.options;
+    for (let key in options) {
+      stageOptions[key] = options[key]!;
+    }
+
+    if (options.inspector !== undefined && !isProductionEnvironment) {
+      if (options.inspector === false) {
+        this.inspector?.destroy();
+        this.inspector = null;
+      } else if (
+        this.inspector === null ||
+        this.inspector.constructor !== options.inspector
+      ) {
+        this.inspector = new options.inspector(
+          this.canvas,
+          stage.options as unknown as RendererMainSettings,
+        );
+        this.inspector?.createNodes(this.root as unknown as CoreNode);
+      }
+    }
+
+    let needDimensionsUpdate = false;
+
+    if (
+      options.deviceLogicalPixelRatio ||
+      options.devicePhysicalPixelRatio !== undefined
+    ) {
+      this.stage.pixelRatio =
+        stageOptions.devicePhysicalPixelRatio *
+        stageOptions.deviceLogicalPixelRatio;
+      this.inspector?.updateViewport(
+        stageOptions.appWidth,
+        stageOptions.appHeight,
+        stageOptions.deviceLogicalPixelRatio,
+      );
+      needDimensionsUpdate = true;
+    }
+
+    if (options.appWidth !== undefined || options.appHeight !== undefined) {
+      this.inspector?.updateViewport(
+        stageOptions.appWidth,
+        stageOptions.appHeight,
+        stageOptions.deviceLogicalPixelRatio,
+      );
+      needDimensionsUpdate = true;
+    }
+
+    if (options.boundsMargin !== undefined) {
+      this.stage.setBoundsMargin(options.boundsMargin);
+    }
+
+    if (options.clearColor !== undefined) {
+      this.stage.setClearColor(options.clearColor);
+    }
+
+    if (needDimensionsUpdate) {
+      this.updateAppDimensions();
+    }
+  }
+
+  private updateAppDimensions() {
+    const {
+      appWidth,
+      appHeight,
+      deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio,
+    } = this.stage.options;
+
+    const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
+    const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
+
+    this.canvas.width = deviceLogicalWidth * devicePhysicalPixelRatio;
+    this.canvas.height = deviceLogicalHeight * devicePhysicalPixelRatio;
+
+    this.canvas.style.width = `${deviceLogicalWidth}px`;
+    this.canvas.style.height = `${deviceLogicalHeight}px`;
+
+    this.stage.renderer.updateViewport();
+
+    this.root.width = appWidth;
+    this.root.height = appHeight;
+    this.stage.updateViewportBounds();
+  }
+
+  get settings(): Readonly<StageOptions> {
+    return this.stage.options;
+  }
+
+  /**
+   * Gets the target FPS for the global render loop
+   *
+   * @returns The current target FPS (0 means no throttling)
+   *
+   * @remarks
+   * This controls the maximum frame rate of the entire rendering system.
+   * When 0, the system runs at display refresh rate.
+   */
+  get targetFPS(): number {
+    return this.stage.options.targetFPS || 0;
+  }
+
+  /**
+   * Sets the target FPS for the global render loop
+   *
+   * @param fps - The target FPS to set for the global render loop.
+   *              Set to 0 or a negative value to disable throttling.
+   *
+   * @remarks
+   * This setting affects the entire rendering system immediately.
+   * All animations, rendering, and frame updates will be throttled
+   * to this target FPS. Provides global performance control.
+   *
+   * @example
+   * ```typescript
+   * // Set global target to 30fps for better performance
+   * renderer.targetFPS = 30;
+   *
+   * // Disable global throttling (use display refresh rate)
+   * renderer.targetFPS = 0;
+   * ```
+   */
+  set targetFPS(fps: number) {
+    this.stage.options.targetFPS = fps > 0 ? fps : 0;
+    this.stage.updateTargetFrameTime();
+  }
 }

package/src/utils.ts

@@ -64,6 +64,15 @@ export function createWebGLContext(
   return gl;
 }
 
+/**
+ * Checks if we're in a development environment or not.
+ *
+ * @returns
+ */
+declare const __DEV__: boolean;
+export const isProductionEnvironment =
+  typeof __DEV__ !== 'undefined' ? !__DEV__ : true;
+
 /**
  * Asserts a condition is truthy, otherwise throws an error
  *
@@ -80,7 +89,7 @@ export function assertTruthy(
   condition: unknown,
   message?: string,
 ): asserts condition {
-  if (isProductionEnvironment() === true) return;
+  if (isProductionEnvironment === true) return;
   if (!condition) {
     throw new Error(message || 'Assertion failed');
   }
@@ -230,15 +239,6 @@ export function getImageAspectRatio(width: number, height: number): number {
   return width / height;
 }
 
-/**
- * Checks import.meta if env is production
- *
- * @returns
- */
-export function isProductionEnvironment(): boolean {
-  return import.meta.env && import.meta.env.PROD;
-}
-
 /**
  * Returns a new unique ID
  */