@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta20

package/dist/src/main-api/Renderer.d.ts

@@ -1,40 +1,155 @@
 import type { ExtractProps, TextureMap } from '../core/CoreTextureManager.js';
 import { EventEmitter } from '../common/EventEmitter.js';
-import { Stage } from '../core/Stage.js';
+import { Stage, type StageOptions } from '../core/Stage.js';
 import { CoreNode } from '../core/CoreNode.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 { Inspector } from './Inspector.js';
+import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
+import type { Inspector, InspectorOptions } from './Inspector.js';
 import type { CoreShaderNode } from '../core/renderers/CoreShaderNode.js';
 import type { ExtractShaderProps, OptionalShaderProps, ShaderMap } from '../core/CoreShaderManager.js';
+import { Platform } from '../core/platforms/Platform.js';
 /**
- * Configuration settings for {@link RendererMain}
+ * FPS Update Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('fpsUpdate', (data) => {
+ *   console.log(`Current FPS: ${data.fps}`);
+ *   if (data.contextSpyData) {
+ *     console.log('WebGL calls:', data.contextSpyData);
+ *   }
+ * });
+ * ```
+ */
+export interface RendererMainFpsUpdateEvent {
+    /** Current frames per second */
+    fps: number;
+    /** Context spy data (if enabled) - contains WebGL call statistics */
+    contextSpyData?: unknown;
+}
+/**
+ * Frame Tick Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('frameTick', (data) => {
+ *   console.log(`Frame time: ${data.time}ms, delta: ${data.delta}ms`);
+ * });
+ * ```
+ */
+export interface RendererMainFrameTickEvent {
+    /** Current timestamp */
+    time: number;
+    /** Time delta since last frame */
+    delta: number;
+}
+/**
+ * Quads Update Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('quadsUpdate', (data) => {
+ *   console.log(`Rendered quads: ${data.quads}`);
+ * });
+ * ```
+ */
+export interface RendererMainQuadsUpdateEvent {
+    /** Number of rendered quads */
+    quads: number;
+}
+/**
+ * Idle Event Data
+ *
+ * @category Events
+ * @remarks
+ * This event is emitted when the renderer has no scene updates to process.
+ * The event has no payload - use this for performance optimizations during idle periods.
+ *
+ * @example
+ * ```typescript
+ * renderer.on('idle', () => {
+ *   // Renderer is idle - perfect time for cleanup, analytics, etc.
+ *   console.log('Renderer is idle - no scene changes');
+ *
+ *   // Example: Perform background tasks
+ *   performBackgroundCleanup();
+ *   sendAnalytics();
+ * });
+ * ```
+ */
+export interface RendererMainIdleEvent {
+    /** This event has no payload - listen without parameters */
+    readonly __eventHasNoPayload?: never;
+}
+/**
+ * Critical Cleanup Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('criticalCleanup', (data) => {
+ *   console.log(`Memory cleanup triggered!`);
+ *   console.log(`Memory used: ${data.memUsed} bytes`);
+ *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
+ * });
+ * ```
+ */
+export interface RendererMainCriticalCleanupEvent {
+    /** Memory used before cleanup (bytes) */
+    memUsed: number;
+    /** Critical threshold (bytes) */
+    criticalThreshold: number;
+}
+/**
+ * Critical Cleanup Failed Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('criticalCleanupFailed', (data) => {
+ *   console.warn(`Memory cleanup failed!`);
+ *   console.log(`Memory still used: ${data.memUsed} bytes`);
+ *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
+ *   // Consider reducing texture usage or forcing cleanup
+ * });
+ * ```
  */
-export interface RendererMainSettings {
+export interface RendererMainCriticalCleanupFailedEvent {
+    /** Memory used after cleanup (bytes) */
+    memUsed: number;
+    /** Critical threshold (bytes) */
+    criticalThreshold: number;
+}
+/**
+ * Settings for the Renderer that can be updated during runtime.
+ */
+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
      *
@@ -50,7 +165,7 @@ export interface RendererMainSettings {
      *
      * @defaultValue `1`
      */
-    deviceLogicalPixelRatio?: number;
+    deviceLogicalPixelRatio: number;
     /**
      * Factor to convert device logical coordinates to device physical coordinates
      *
@@ -66,13 +181,13 @@ 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
      *
@@ -81,7 +196,55 @@ 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;
+    /**
+     * Inspector Options
+     *
+     * @remarks
+     * Configuration options for the Inspector's performance monitoring features.
+     * Only used when inspector is enabled.
+     */
+    inspectorOptions?: Partial<InspectorOptions>;
+    /**
+     * 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
      *
@@ -95,7 +258,7 @@ export interface RendererMainSettings {
      *
      * @defaultValue `false` (disabled)
      */
-    enableContextSpy?: boolean;
+    enableContextSpy: boolean;
     /**
      * Number or Image Workers to use
      *
@@ -106,16 +269,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
      *
@@ -135,7 +289,7 @@ export interface RendererMainSettings {
      *
      * @defaultValue 4 * 1024 * 1024
      */
-    quadBufferSize?: number;
+    quadBufferSize: number;
     /**
      * Font Engines
      *
@@ -164,7 +318,7 @@ export interface RendererMainSettings {
      *
      *
      */
-    fontEngines: (typeof SdfTextRenderer | typeof CanvasTextRenderer)[];
+    fontEngines: TextRenderer[];
     /**
      * Force WebGL2
      *
@@ -174,28 +328,7 @@ export interface RendererMainSettings {
      *
      * @defaultValue `false`
      */
-    forceWebGL2?: boolean;
-    /**
-     * Enable strictBounds
-     *
-     * @remarks
-     * Enable strict bounds for the renderer. This will ensure that the renderer
-     * will not render outside the bounds of the canvas.
-     *
-     * @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;
+    forceWebGL2: boolean;
     /**
      * Canvas object to use for rendering
      *
@@ -203,7 +336,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
      *
@@ -227,8 +360,32 @@ 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;
+    /**
+     * Number of times to retry loading a failed texture
+     *
+     * @remarks
+     * When a texture fails to load, Lightning will retry up to this many times
+     * before permanently giving up. Each retry will clear the texture ownership
+     * and then re-establish it to trigger a new load attempt.
+     *
+     * Set to null to disable retries. Set to 0 to always try once and never retry.
+     * This is typically only used on ImageTexture instances.
+     *
+     */
+    maxRetryCount?: number;
+};
 /**
  * The Renderer Main API
  *
@@ -253,36 +410,36 @@ export interface RendererMainSettings {
  * );
  * ```
  *
- * ## Events
- * - `fpsUpdate`
- *   - Emitted every `fpsUpdateInterval` milliseconds with the current FPS
- * - `frameTick`
- *   - Emitted every frame tick
- * - `quadsUpdate`
- *  - Emitted when number of quads rendered is updated
- * - `idle`
- *   - Emitted when the renderer is idle (no changes to the scene
- *     graph/animations running)
- * - `criticalCleanup`
- *  - Emitted when the Texture Memory Manager Cleanup process is triggered
- *  - Payload: { memUsed: number, criticalThreshold: number }
- *    - `memUsed` - The amount of memory (in bytes) used by textures before the
- *       cleanup process
- *    - `criticalThreshold` - The critical threshold (in bytes)
- * - `criticalCleanupFailed`
- *   - Emitted when the Texture Memory Manager Cleanup process is unable to free
- *     up enough texture memory to reach below the critical threshold.
- *     This can happen when there is not enough non-renderable textures to
- *     free up.
- *   - Payload (object with keys):
- *     - `memUsed` - The amount of memory (in bytes) used by textures after
- *       the cleanup process
- *     - `criticalThreshold` - The critical threshold (in bytes)
+ * ## Event Handling
+ *
+ * Listen to events using the standard EventEmitter API:
+ * ```typescript
+ * renderer.on('fpsUpdate', (data: RendererMainFpsUpdateEvent) => {
+ *   console.log(`FPS: ${data.fps}`);
+ * });
+ *
+ * renderer.on('idle', (data: RendererMainIdleEvent) => {
+ *   // Renderer is idle - no scene changes
+ * });
+ * ```
+ *
+ * @see {@link RendererMainFpsUpdateEvent}
+ * @see {@link RendererMainFrameTickEvent}
+ * @see {@link RendererMainQuadsUpdateEvent}
+ * @see {@link RendererMainIdleEvent}
+ * @see {@link RendererMainCriticalCleanupEvent}
+ * @see {@link RendererMainCriticalCleanupFailedEvent}
+ *
+ * @fires RendererMain#fpsUpdate
+ * @fires RendererMain#frameTick
+ * @fires RendererMain#quadsUpdate
+ * @fires RendererMain#idle
+ * @fires RendererMain#criticalCleanup
+ * @fires RendererMain#criticalCleanupFailed
  */
 export declare class RendererMain extends EventEmitter {
     readonly root: INode;
     readonly canvas: HTMLCanvasElement;
-    readonly settings: Readonly<Required<RendererMainSettings>>;
     readonly stage: Stage;
     private inspector;
     /**
@@ -292,7 +449,14 @@ export declare 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);
+    /**
+     * Resolves the Texture Memory Manager values
+     *
+     * @param props
+     * @returns
+     */
+    private resolveTxSettings;
     /**
      * Create a new scene graph node
      *
@@ -365,7 +529,7 @@ export declare class RendererMain extends EventEmitter {
      * @param props
      * @returns
      */
-    createShader<ShType extends keyof ShaderMap>(shType: ShType, props?: OptionalShaderProps<ShType>): CoreShaderNode<ExtractShaderProps<ShType>>;
+    createShader<ShType extends keyof ShaderMap>(shType: ShType, props?: OptionalShaderProps<ShType>): CoreShaderNode<NonNullable<ExtractShaderProps<ShType>>>;
     /**
      * Get a Node by its ID
      *
@@ -404,11 +568,50 @@ export declare class RendererMain extends EventEmitter {
      * **NOTE3**: This will not cleanup textures that are marked as `preventCleanup`.
      * **NOTE4**: This has nothing to do with the garbage collection of JavaScript.
      */
-    cleanup(aggressive?: boolean): void;
+    cleanup(): void;
     /**
      * Sets the clear color for the stage.
      *
      * @param color - The color to set as the clear color.
      */
     setClearColor(color: number): void;
+    /**
+     * Set options for the renderer
+     *
+     * @param options
+     */
+    setOptions(options: Partial<RendererRuntimeSettings>): void;
+    private updateAppDimensions;
+    get settings(): Readonly<StageOptions>;
+    /**
+     * 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;
+    /**
+     * 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);
 }