@lightningtv/renderer 2.16.1

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

@@ -0,0 +1,543 @@
+import type { EffectMap, ShaderMap } from '../core/CoreShaderManager.js';
+import type { ExtractProps, TextureMap } from '../core/CoreTextureManager.js';
+import { EventEmitter } from '../common/EventEmitter.js';
+import { Stage } from '../core/Stage.js';
+import { CoreNode } from '../core/CoreNode.js';
+import type { BaseShaderController, ShaderController } from './ShaderController.js';
+import type { INode, INodeProps, ITextNode, ITextNodeProps } from './INode.js';
+import type { DynamicEffects, DynamicShaderController } from './DynamicShaderController.js';
+import type { EffectDesc } from '../core/renderers/webgl/shaders/effects/ShaderEffect.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 { WebGlCoreRenderer } from '../core/renderers/webgl/WebGlCoreRenderer.js';
+import type { CanvasCoreRenderer } from '../core/renderers/canvas/CanvasCoreRenderer.js';
+import type { Inspector } from './Inspector.js';
+/**
+ * An immutable reference to a specific Shader type
+ *
+ * @remarks
+ * See {@link ShaderRef} for more details.
+ */
+export interface SpecificShaderRef<ShType extends keyof ShaderMap> {
+    readonly descType: 'shader';
+    readonly shType: ShType;
+    readonly props: ExtractProps<ShaderMap[ShType]>;
+}
+type MapShaderRefs<ShType extends keyof ShaderMap> = ShType extends keyof ShaderMap ? SpecificShaderRef<ShType> : never;
+/**
+ * An immutable reference to a Shader
+ *
+ * @remarks
+ * This structure should only be created by the RendererMain's `createShader`
+ * method. The structure is immutable and should not be modified once created.
+ *
+ * A `ShaderRef` exists in the Main API Space and is used to point to an actual
+ * `Shader` instance in the Core API Space. The `ShaderRef` is used to
+ * communicate with the Core API Space to create, load, and destroy the
+ * `Shader` instance.
+ *
+ * This type is technically a discriminated union of all possible shader types.
+ * If you'd like to represent a specific shader type, you can use the
+ * `SpecificShaderRef` generic type.
+ */
+export type ShaderRef = MapShaderRefs<keyof ShaderMap>;
+/**
+ * Configuration settings for {@link RendererMain}
+ */
+export interface RendererMainSettings {
+    /**
+     * Authored logical pixel width of the application
+     *
+     * @defaultValue `1920`
+     */
+    appWidth?: number;
+    /**
+     * Authored logical pixel height of the application
+     *
+     * @defaultValue `1080`
+     */
+    appHeight?: number;
+    /**
+     * Texture Memory Manager Settings
+     */
+    textureMemory?: Partial<TextureMemoryManagerSettings>;
+    /**
+     * Bounds margin to extend the boundary in which a Node is added as Quad.
+     */
+    boundsMargin?: number | [number, number, number, number];
+    /**
+     * Factor to convert app-authored logical coorindates to device logical coordinates
+     *
+     * @remarks
+     * This value allows auto-scaling to support larger/small resolutions than the
+     * app was authored for.
+     *
+     * If the app was authored for 1920x1080 and this value is 2, the app's canvas
+     * will be rendered at 3840x2160 logical pixels.
+     *
+     * Likewise, if the app was authored for 1920x1080 and this value is 0.66667,
+     * the app's canvas will be rendered at 1280x720 logical pixels.
+     *
+     * @defaultValue `1`
+     */
+    deviceLogicalPixelRatio?: number;
+    /**
+     * Factor to convert device logical coordinates to device physical coordinates
+     *
+     * @remarks
+     * This value allows auto-scaling to support devices with different pixel densities.
+     *
+     * This controls the number of physical pixels that are used to render each logical
+     * pixel. For example, if the device has a pixel density of 2, each logical pixel
+     * will be rendered using 2x2 physical pixels.
+     *
+     * By default, it will be set to `window.devicePixelRatio` which is the pixel
+     * density of the device the app is running on reported by the browser.
+     *
+     * @defaultValue `window.devicePixelRatio`
+     */
+    devicePhysicalPixelRatio?: number;
+    /**
+     * RGBA encoded number of the background to use
+     *
+     * @defaultValue `0x00000000`
+     */
+    clearColor?: number;
+    /**
+     * Interval in milliseconds to receive FPS updates
+     *
+     * @remarks
+     * If set to `0`, FPS updates will be disabled.
+     *
+     * @defaultValue `0` (disabled)
+     */
+    fpsUpdateInterval?: 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;
+    /**
+     * Include context call (i.e. WebGL) information in FPS updates
+     *
+     * @remarks
+     * When enabled the number of calls to each context method over the
+     * `fpsUpdateInterval` will be included in the FPS update payload's
+     * `contextSpyData` property.
+     *
+     * Enabling the context spy has a serious impact on performance so only use it
+     * when you need to extract context call information.
+     *
+     * @defaultValue `false` (disabled)
+     */
+    enableContextSpy?: boolean;
+    /**
+     * Number or Image Workers to use
+     *
+     * @remarks
+     * On devices with multiple cores, this can be used to improve image loading
+     * as well as reduce the impact of image loading on the main thread.
+     * Set to 0 to disable image workers.
+     *
+     * @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;
+    /**
+     * Renderer Engine
+     *
+     * @remarks
+     * The renderer engine to use. Spawns a WebGL or Canvas renderer.
+     * WebGL is more performant and supports more features. Canvas is
+     * supported on most platforms.
+     *
+     * Note: When using CanvasCoreRenderer you can only use
+     * CanvasTextRenderer. The WebGLCoreRenderer supports
+     * both CanvasTextRenderer and SdfTextRenderer for Text Rendering.
+     *
+     */
+    renderEngine: typeof CanvasCoreRenderer | typeof WebGlCoreRenderer;
+    /**
+     * Quad buffer size in bytes
+     *
+     * @defaultValue 4 * 1024 * 1024
+     */
+    quadBufferSize?: number;
+    /**
+     * Font Engines
+     *
+     * @remarks
+     * The font engines to use for text rendering. CanvasTextRenderer is supported
+     * on all platforms. SdfTextRenderer is a more performant renderer.
+     * When using `renderEngine=CanvasCoreRenderer` you can only use `CanvasTextRenderer`.
+     * The `renderEngine=WebGLCoreRenderer` supports both `CanvasTextRenderer` and `SdfTextRenderer`.
+     *
+     * This setting is used to enable tree shaking of unused font engines. Please
+     * import your font engine(s) as follows:
+     * ```
+     * import { CanvasTextRenderer } from '@lightning/renderer/canvas';
+     * import { SdfTextRenderer } from '@lightning/renderer/webgl';
+     * ```
+     *
+     * If both CanvasTextRenderer and SdfTextRenderer are provided, the first renderer
+     * provided will be asked first if it can render the font. If it cannot render the
+     * font, the next renderer will be asked. If no renderer can render the font, the
+     * text will not be rendered.
+     *
+     * **Note** that if you have fonts available in both engines the second font engine
+     * will not be used. This is because the first font engine will always be asked first.
+     *
+     * @defaultValue '[]'
+     *
+     *
+     */
+    fontEngines: (typeof SdfTextRenderer | typeof CanvasTextRenderer)[];
+    /**
+     * Force WebGL2
+     *
+     * @remarks
+     * Force the renderer to use WebGL2. This can be used to force the renderer to
+     * use WebGL2 even if the browser supports WebGL1.
+     *
+     * @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;
+    /**
+     * Canvas object to use for rendering
+     *
+     * @remarks
+     * 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;
+    /**
+     * createImageBitmap support for the runtime
+     *
+     * @remarks
+     * This is used to determine if and which version of the createImageBitmap API
+     * is supported by the runtime. This is used to determine if the renderer can
+     * use createImageBitmap to load images.
+     *
+     * Options supported
+     * - Auto - Automatically determine the supported version
+     * - Basic - Supports createImageBitmap(image)
+     * - Options - Supports createImageBitmap(image, options)
+     * - Full - Supports createImageBitmap(image, sx, sy, sw, sh, options)
+     *
+     * Note with auto detection, the renderer will attempt to use the most advanced
+     * version of the API available. If the API is not available, the renderer will
+     * fall back to the next available version.
+     *
+     * This will affect startup performance as the renderer will need to determine
+     * the supported version of the API.
+     *
+     * @defaultValue `full`
+     */
+    createImageBitmapSupport?: 'auto' | 'basic' | 'options' | 'full';
+}
+/**
+ * The Renderer Main API
+ *
+ * @remarks
+ * This is the primary class used to configure and operate the Renderer.
+ *
+ * It is used to create and destroy Nodes, as well as Texture and Shader
+ * references.
+ *
+ * Example:
+ * ```ts
+ * import { RendererMain, MainCoreDriver } from '@lightningjs/renderer';
+ *
+ * // Initialize the Renderer
+ * const renderer = new RendererMain(
+ *   {
+ *     appWidth: 1920,
+ *     appHeight: 1080
+ *   },
+ *   'app',
+ *   new MainCoreDriver(),
+ * );
+ * ```
+ *
+ * ## 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)
+ */
+export declare class RendererMain extends EventEmitter {
+    readonly root: INode<ShaderController<'DefaultShader'>>;
+    readonly canvas: HTMLCanvasElement;
+    readonly settings: Readonly<Required<RendererMainSettings>>;
+    readonly stage: Stage;
+    private inspector;
+    /**
+     * Constructs a new Renderer instance
+     *
+     * @param settings Renderer settings
+     * @param target Element ID or HTMLElement to insert the canvas into
+     * @param driver Core Driver to use
+     */
+    constructor(settings: RendererMainSettings, target: string | HTMLElement);
+    /**
+     * Create a new scene graph node
+     *
+     * @remarks
+     * A node is the main graphical building block of the Renderer scene graph. It
+     * can be a container for other nodes, or it can be a leaf node that renders a
+     * solid color, gradient, image, or specific texture, using a specific shader.
+     *
+     * To create a text node, see {@link createTextNode}.
+     *
+     * See {@link CoreNode} for more details.
+     *
+     * @param props
+     * @returns
+     */
+    createNode<ShCtr extends BaseShaderController = ShaderController<'DefaultShader'>>(props: Partial<INodeProps<ShCtr>>): INode<ShCtr>;
+    /**
+     * Create a new scene graph text node
+     *
+     * @remarks
+     * A text node is the second graphical building block of the Renderer scene
+     * graph. It renders text using a specific text renderer that is automatically
+     * chosen based on the font requested and what type of fonts are installed
+     * into an app.
+     *
+     * See {@link ITextNode} for more details.
+     *
+     * @param props
+     * @returns
+     */
+    createTextNode(props: Partial<ITextNodeProps>): ITextNode;
+    /**
+     * Destroy a node
+     *
+     * @remarks
+     * This method destroys a node
+     *
+     * @param node
+     * @returns
+     */
+    destroyNode(node: INode): void;
+    /**
+     * Create a new texture reference
+     *
+     * @remarks
+     * This method creates a new reference to a texture. The texture is not
+     * loaded until it is used on a node.
+     *
+     * It can be assigned to a node's `texture` property, or it can be used
+     * when creating a SubTexture.
+     *
+     * @param textureType
+     * @param props
+     * @param options
+     * @returns
+     */
+    createTexture<TxType extends keyof TextureMap>(textureType: TxType, props: ExtractProps<TextureMap[TxType]>): InstanceType<TextureMap[TxType]>;
+    /**
+     * Create a new shader controller for a shader type
+     *
+     * @remarks
+     * This method creates a new Shader Controller for a specific shader type.
+     *
+     * If the shader has not been loaded yet, it will be loaded. Otherwise, the
+     * existing shader will be reused.
+     *
+     * It can be assigned to a Node's `shader` property.
+     *
+     * @param shaderType
+     * @param props
+     * @returns
+     */
+    createShader<ShType extends keyof ShaderMap>(shaderType: ShType, props?: ExtractProps<ShaderMap[ShType]>): ShaderController<ShType>;
+    /**
+     * Create a new Dynamic Shader controller
+     *
+     * @remarks
+     * A Dynamic Shader is a shader that can be composed of an array of mulitple
+     * effects. Each effect can be animated or changed after creation (provided
+     * the effect is given a name).
+     *
+     * Example:
+     * ```ts
+     * renderer.createNode({
+     *   shader: renderer.createDynamicShader([
+     *     renderer.createEffect('radius', {
+     *       radius: 0
+     *     }, 'effect1'),
+     *     renderer.createEffect('border', {
+     *       color: 0xff00ffff,
+     *       width: 10,
+     *     }, 'effect2'),
+     *   ]),
+     * });
+     * ```
+     *
+     * @param effects
+     * @returns
+     */
+    createDynamicShader<T extends DynamicEffects<[...{
+        name?: string;
+        type: keyof EffectMap;
+    }[]]>>(effects: [...T]): DynamicShaderController<T>;
+    /**
+     * Create an effect to be used in a Dynamic Shader
+     *
+     * @remark
+     * The {name} parameter is optional but required if you want to animate the effect
+     * or change the effect's properties after creation.
+     *
+     * See {@link createDynamicShader} for an example.
+     *
+     * @param type
+     * @param props
+     * @param name
+     * @returns
+     */
+    createEffect<Type extends keyof EffectMap, Name extends string | undefined = undefined>(type: Type, props: EffectDesc<{
+        name: Name;
+        type: Type;
+    }>['props'], name?: Name): EffectDesc<{
+        name: Name;
+        type: Type;
+    }>;
+    /**
+     * Get a Node by its ID
+     *
+     * @param id
+     * @returns
+     */
+    getNodeById(id: number): CoreNode | null;
+    toggleFreeze(): void;
+    advanceFrame(): void;
+    getBufferInfo(): import("../core/renderers/CoreRenderer.js").BufferInfo | null;
+    /**
+     * Re-render the current frame without advancing any running animations.
+     *
+     * @remarks
+     * Any state changes will be reflected in the re-rendered frame. Useful for
+     * debugging.
+     *
+     * May not do anything if the render loop is running on a separate worker.
+     */
+    rerender(): void;
+    /**
+     * Cleanup textures that are not being used
+     *
+     * @param aggressive - If true, will cleanup all textures, regardless of render status
+     *
+     * @remarks
+     * This can be used to free up GFX memory used by textures that are no longer
+     * being displayed.
+     *
+     * This routine is also called automatically when the memory used by textures
+     * exceeds the critical threshold on frame generation **OR** when the renderer
+     * is idle and the memory used by textures exceeds the target threshold.
+     *
+     * **NOTE**: This is a heavy operation and should be used sparingly.
+     * **NOTE2**: This will not cleanup textures that are currently being displayed.
+     * **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;
+    /**
+     * Sets the clear color for the stage.
+     *
+     * @param color - The color to set as the clear color.
+     */
+    setClearColor(color: number): void;
+    /**
+     * 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);
+}
+export {};