@lightningtv/renderer 3.0.0-beta1 → 3.2.4

package/dist/src/core/Stage.d.ts

@@ -1,64 +1,65 @@
 import { AnimationManager } from './animations/AnimationManager.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 { TextRenderer, type TextRendererMap, type TrProps } from './text-rendering/renderers/TextRenderer.js';
+import { type FontHandler, type FontLoadOptions, type TextRenderer, type TextRenderers, type TrProps } from './text-rendering/TextRenderer.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
 import type { FpsUpdatePayload, FrameTickPayload } from '../common/CommonTypes.js';
 import { TextureMemoryManager, type TextureMemoryManagerSettings } from './TextureMemoryManager.js';
 import { CoreRenderer } from './renderers/CoreRenderer.js';
-import type { WebGlRenderer } from './renderers/webgl/WebGlRenderer.js';
-import type { CanvasRenderer } from './renderers/canvas/CanvasRenderer.js';
 import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
-import type { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-import type { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
 import type { CoreShaderNode } from './renderers/CoreShaderNode.js';
 import { type Bound } from './lib/utils.js';
 import type { Texture } from './textures/Texture.js';
-export interface StageOptions {
-    appWidth: number;
-    appHeight: number;
+import type { Platform } from './platforms/Platform.js';
+import type { WebPlatform } from './platforms/web/WebPlatform.js';
+import type { RendererMainSettings } from '../main-api/Renderer.js';
+export type StageOptions = Omit<RendererMainSettings, 'inspector' | 'platform' | 'maxRetryCount'> & {
     textureMemory: TextureMemoryManagerSettings;
-    boundsMargin: number | [number, number, number, number];
-    deviceLogicalPixelRatio: number;
-    devicePhysicalPixelRatio: number;
     canvas: HTMLCanvasElement | OffscreenCanvas;
-    clearColor: number;
     fpsUpdateInterval: number;
-    enableContextSpy: boolean;
-    forceWebGL2: boolean;
-    numImageWorkers: number;
-    renderEngine: typeof WebGlRenderer | typeof CanvasRenderer;
     eventBus: EventEmitter;
-    quadBufferSize: number;
-    fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[];
+    platform: Platform | WebPlatform;
     inspector: boolean;
-    strictBounds: boolean;
-    textureProcessingTimeLimit: number;
-    createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
-}
+    maxRetryCount: number;
+    enableClear: boolean;
+};
 export type StageFpsUpdateHandler = (stage: Stage, fpsData: FpsUpdatePayload) => void;
 export type StageFrameTickHandler = (stage: Stage, frameTickData: FrameTickPayload) => void;
+export interface Point {
+    x: number;
+    y: number;
+}
 export declare class Stage {
-    readonly options: StageOptions;
+    options: StageOptions;
     readonly animationManager: AnimationManager;
     readonly txManager: CoreTextureManager;
     readonly txMemManager: TextureMemoryManager;
-    readonly fontManager: TrFontManager;
-    readonly textRenderers: Partial<TextRendererMap>;
+    readonly textRenderers: Record<string, TextRenderer>;
+    readonly fontHandlers: Record<string, FontHandler>;
     readonly shManager: CoreShaderManager;
     readonly renderer: CoreRenderer;
     readonly root: CoreNode;
+    readonly interactiveNodes: Set<CoreNode>;
     boundsMargin: [number, number, number, number];
     readonly defShaderNode: CoreShaderNode | null;
-    readonly strictBound: Bound;
-    readonly preloadBound: Bound;
-    readonly strictBounds: boolean;
+    strictBound: Bound;
+    preloadBound: Bound;
     readonly defaultTexture: Texture | null;
-    readonly pixelRatio: number;
+    pixelRatio: number;
     readonly bufferMemory: number;
+    readonly platform: Platform | WebPlatform;
+    readonly calculateTextureCoord: boolean;
+    /**
+     * Target frame time in milliseconds (calculated from targetFPS)
+     *
+     * @remarks
+     * This is pre-calculated to avoid recalculating on every frame.
+     * - 0 means no throttling (use display refresh rate)
+     * - >0 means throttle to this frame time (1000 / targetFPS)
+     */
+    targetFrameTime: number;
     /**
      * Renderer Event Bus for the Stage to emit events onto
      *
@@ -68,22 +69,43 @@ export declare class Stage {
      * without having to set up forwarding handlers.
      */
     readonly eventBus: EventEmitter;
+    startTime: number;
     deltaTime: number;
     lastFrameTime: number;
     currentFrameTime: number;
+    elapsedTime: number;
+    private timedNodes;
     private clrColor;
     private fpsNumFrames;
     private fpsElapsedTime;
     private numQuadsRendered;
     private renderRequested;
+    private reprocessFrame;
+    private reprocessCallback;
     private frameEventQueue;
-    private fontResolveMap;
+    renderList: CoreNode[];
+    renderListDirty: boolean;
+    private hasOnlyOneFontEngine;
+    private hasOnlyCanvasFontEngine;
+    private hasCanvasEngine;
+    private singleFontEngine;
+    private singleFontHandler;
     contextSpy: ContextSpy | null;
     /**
      * Stage constructor
      */
     constructor(options: StageOptions);
     setClearColor(color: number): void;
+    /**
+     * Update the target frame time based on the current targetFPS setting
+     *
+     * @remarks
+     * This should be called whenever the targetFPS option is changed
+     * to ensure targetFrameTime stays in sync.
+     * targetFPS of 0 means no throttling (targetFrameTime = 0)
+     * targetFPS > 0 means throttle to 1000/targetFPS milliseconds
+     */
+    updateTargetFrameTime(): void;
     updateFrameTime(): void;
     /**
      * Create default PixelTexture
@@ -92,7 +114,7 @@ export declare class Stage {
     /**
      * Update animations
      */
-    updateAnimations(): void;
+    updateAnimations(): boolean;
     /**
      * Check if the scene has updates
      */
@@ -100,7 +122,7 @@ export declare class Stage {
     /**
      * Start a new frame draw
      */
-    drawFrame(): void;
+    drawFrame(hasActiveAnimations?: boolean): void;
     /**
      * Queue an event to be emitted after the current/next frame is rendered
      *
@@ -128,11 +150,13 @@ export declare class Stage {
     flushFrameEvents(): void;
     calculateFps(): void;
     calculateQuads(): void;
-    addQuads(node: CoreNode): void;
+    requestRenderListUpdate(): void;
+    buildRenderList(node: CoreNode): void;
     /**
      * Request a render pass without forcing an update
      */
     requestRender(): void;
+    reprocessUpdates(callback?: () => void): void;
     /**
      * Given a font name, and possible renderer override, return the best compatible text renderer.
      *
@@ -143,10 +167,36 @@ export declare class Stage {
      * @param textRendererOverride
      * @returns
      */
-    resolveTextRenderer(trProps: TrProps, textRendererOverride?: keyof TextRendererMap | null): TextRenderer | null;
+    resolveTextRenderer(trProps: TrProps, textRendererOverride?: keyof TextRenderers | null): TextRenderer | null;
     createNode(props: Partial<CoreNodeProps>): CoreNode;
     createTextNode(props: Partial<CoreTextNodeProps>): CoreTextNode;
     setBoundsMargin(value: number | [number, number, number, number]): void;
+    /**
+     * Update the viewport bounds
+     */
+    updateViewportBounds(): void;
+    /** Find all nodes at a given point
+     * @param data
+     */
+    findNodesAtPoint(data: Point): CoreNode[];
+    /**
+     * Find the top node at a given point
+     * @param data
+     * @returns
+     */
+    getNodeFromPosition(data: Point): CoreNode | null;
+    /**
+     * add node to timeNodes arrays
+     * @param node
+     * @returns
+     */
+    trackTimedNode(node: CoreNode): void;
+    /**
+     * remove node from timeNodes arrays
+     * @param node
+     * @returns
+     */
+    untrackTimedNode(node: CoreNode): void;
     /**
      * Resolves the default property values for a Node
      *
@@ -165,7 +215,23 @@ export declare class Stage {
      * @remarks
      * This method is used to cleanup orphaned textures that are no longer in use.
      */
-    cleanup(aggressive: boolean): void;
+    cleanup(full?: boolean): void;
     set clearColor(value: number);
     get clearColor(): number;
+    /**
+     * Load a font using a specific text renderer type
+     *
+     * @remarks
+     * This method allows consumers to explicitly load fonts for a specific
+     * text renderer type (e.g., 'canvas', 'sdf'). Consumers must specify
+     * the renderer type to ensure fonts are loaded with the correct pipeline.
+     *
+     * For Canvas fonts, provide fontUrl (e.g., .ttf, .woff, .woff2)
+     * For SDF fonts, provide atlasUrl (image) and atlasDataUrl (JSON glyph data)
+     *
+     * @param rendererType - The type of text renderer ('canvas', 'sdf', etc.)
+     * @param options - Font loading options specific to the renderer type
+     * @returns Promise that resolves when the font is loaded
+     */
+    loadFont(rendererType: TextRenderers, options: FontLoadOptions): Promise<void>;
 }