@solidtv/renderer 1.0.0

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

@@ -0,0 +1,238 @@
+import { AnimationManager } from './animations/AnimationManager.js';
+import { CoreNode, type CoreNodeProps } from './CoreNode.js';
+import { CoreTextureManager } from './CoreTextureManager.js';
+import { CoreShaderManager } from './CoreShaderManager.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 { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
+import type { CoreShaderNode } from './renderers/CoreShaderNode.js';
+import { type Bound } from './lib/utils.js';
+import type { Texture } from './textures/Texture.js';
+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;
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    fpsUpdateInterval: number;
+    eventBus: EventEmitter;
+    platform: Platform | WebPlatform;
+    inspector: boolean;
+    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 {
+    options: StageOptions;
+    readonly animationManager: AnimationManager;
+    readonly txManager: CoreTextureManager;
+    readonly txMemManager: TextureMemoryManager;
+    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;
+    strictBound: Bound;
+    preloadBound: Bound;
+    readonly defaultTexture: Texture | null;
+    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
+     *
+     * @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.
+     */
+    readonly eventBus: EventEmitter;
+    startTime: number;
+    deltaTime: number;
+    lastFrameTime: number;
+    currentFrameTime: number;
+    elapsedTime: number;
+    private timedNodes;
+    private clrColor;
+    private fpsNumFrames;
+    private fpsElapsedTime;
+    private numQuadsRendered;
+    private numRenderOpsRendered;
+    private renderRequested;
+    private reprocessFrame;
+    private reprocessCallback;
+    private frameEventQueue;
+    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
+     */
+    createDefaultTexture(): void;
+    /**
+     * Update animations
+     */
+    updateAnimations(): boolean;
+    /**
+     * Check if the scene has updates
+     */
+    hasSceneUpdates(): boolean;
+    /**
+     * Start a new frame draw
+     */
+    drawFrame(hasActiveAnimations?: boolean): void;
+    /**
+     * 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): void;
+    /**
+     * 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(): void;
+    calculateFps(): void;
+    calculateRenderInfo(): 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.
+     *
+     * @remarks
+     * Will try to return a canvas renderer if no other suitable renderer can be resolved.
+     *
+     * @param fontFamily
+     * @param textRendererOverride
+     * @returns
+     */
+    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
+     *
+     * @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;
+    /**
+     * Cleanup Orphaned Textures
+     *
+     * @remarks
+     * This method is used to cleanup orphaned textures that are no longer in use.
+     */
+    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>;
+}