@lightningtv/renderer 2.16.1

package/dist/src/core/CoreTextureManager.js

@@ -0,0 +1,362 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2023 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ImageWorkerManager } from './lib/ImageWorker.js';
+import { ColorTexture } from './textures/ColorTexture.js';
+import { ImageTexture } from './textures/ImageTexture.js';
+import { NoiseTexture } from './textures/NoiseTexture.js';
+import { SubTexture } from './textures/SubTexture.js';
+import { RenderTexture } from './textures/RenderTexture.js';
+import { Texture, TextureType } from './textures/Texture.js';
+import { EventEmitter } from '../common/EventEmitter.js';
+import { getTimeStamp } from './platform.js';
+import { validateCreateImageBitmap, } from './lib/validateImageBitmap.js';
+export class CoreTextureManager extends EventEmitter {
+    /**
+     * Map of textures by cache key
+     */
+    keyCache = new Map();
+    /**
+     * Map of cache keys by texture
+     */
+    inverseKeyCache = new WeakMap();
+    /**
+     * Map of texture constructors by their type name
+     */
+    txConstructors = {};
+    priorityQueue = [];
+    uploadTextureQueue = [];
+    initialized = false;
+    stage;
+    numImageWorkers;
+    imageWorkerManager = null;
+    hasCreateImageBitmap = !!self.createImageBitmap;
+    imageBitmapSupported = {
+        basic: false,
+        options: false,
+        full: false,
+    };
+    hasWorker = !!self.Worker;
+    /**
+     * Renderer that this texture manager is associated with
+     *
+     * @remarks
+     * This MUST be set before the texture manager is used. Otherwise errors
+     * will occur when using the texture manager.
+     */
+    renderer;
+    /**
+     * The current frame time in milliseconds
+     *
+     * @remarks
+     * This is used to populate the `lastRenderableChangeTime` property of
+     * {@link Texture} instances when their renderable state changes.
+     *
+     * Set by stage via `updateFrameTime` method.
+     */
+    frameTime = 0;
+    constructor(stage, settings) {
+        super();
+        const { numImageWorkers, createImageBitmapSupport } = settings;
+        this.stage = stage;
+        this.numImageWorkers = numImageWorkers;
+        if (createImageBitmapSupport === 'auto') {
+            validateCreateImageBitmap()
+                .then((result) => {
+                this.initialize(result);
+            })
+                .catch(() => {
+                console.warn('[Lightning] createImageBitmap is not supported on this browser. ImageTexture will be slower.');
+                // initialized without image worker manager and createImageBitmap
+                this.initialized = true;
+                this.emit('initialized');
+            });
+        }
+        else {
+            this.initialize({
+                basic: createImageBitmapSupport === 'basic',
+                options: createImageBitmapSupport === 'options',
+                full: createImageBitmapSupport === 'full',
+            });
+        }
+        this.registerTextureType('ImageTexture', ImageTexture);
+        this.registerTextureType('ColorTexture', ColorTexture);
+        this.registerTextureType('NoiseTexture', NoiseTexture);
+        this.registerTextureType('SubTexture', SubTexture);
+        this.registerTextureType('RenderTexture', RenderTexture);
+    }
+    registerTextureType(textureType, textureClass) {
+        this.txConstructors[textureType] = textureClass;
+    }
+    initialize(support) {
+        this.hasCreateImageBitmap =
+            support.basic || support.options || support.full;
+        this.imageBitmapSupported = support;
+        if (!this.hasCreateImageBitmap) {
+            console.warn('[Lightning] createImageBitmap is not supported on this browser. ImageTexture will be slower.');
+        }
+        if (this.hasCreateImageBitmap &&
+            this.hasWorker &&
+            this.numImageWorkers > 0) {
+            this.imageWorkerManager = new ImageWorkerManager(this.numImageWorkers, support);
+        }
+        else {
+            console.warn('[Lightning] Imageworker is 0 or not supported on this browser. Image loading will be slower.');
+        }
+        this.initialized = true;
+        this.emit('initialized');
+    }
+    /**
+     * Enqueue a texture for uploading to the GPU.
+     *
+     * @param texture - The texture to upload
+     */
+    enqueueUploadTexture(texture) {
+        if (this.uploadTextureQueue.includes(texture) === false) {
+            this.uploadTextureQueue.push(texture);
+        }
+    }
+    /**
+     * Create a texture
+     *
+     * @param textureType - The type of texture to create
+     * @param props - The properties to use for the texture
+     */
+    createTexture(textureType, props) {
+        let texture;
+        const TextureClass = this.txConstructors[textureType];
+        if (!TextureClass) {
+            throw new Error(`Texture type "${textureType}" is not registered`);
+        }
+        const cacheKey = TextureClass.makeCacheKey(props);
+        if (cacheKey && this.keyCache.has(cacheKey)) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            texture = this.keyCache.get(cacheKey);
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
+            texture = new TextureClass(this, props);
+            if (cacheKey) {
+                this.initTextureToCache(texture, cacheKey);
+            }
+        }
+        return texture;
+    }
+    orphanTexture(texture) {
+        // if it is part of the download or upload queue, remove it
+        this.removeTextureFromQueue(texture);
+        if (texture.type === TextureType.subTexture) {
+            // ignore subtextures
+            return;
+        }
+        this.stage.txMemManager.addToOrphanedTextures(texture);
+    }
+    /**
+     * Override loadTexture to use the batched approach.
+     *
+     * @param texture - The texture to load
+     * @param immediate - Whether to prioritize the texture for immediate loading
+     */
+    loadTexture(texture, priority) {
+        this.stage.txMemManager.removeFromOrphanedTextures(texture);
+        if (texture.type === TextureType.subTexture) {
+            // ignore subtextures - they get loaded through their parent
+            return;
+        }
+        if (texture.state === 'loaded') {
+            // if the texture is already loaded, just return
+            return;
+        }
+        if (Texture.TRANSITIONAL_TEXTURE_STATES.includes(texture.state)) {
+            return;
+        }
+        // if we're not initialized, just queue the texture into the priority queue
+        if (this.initialized === false) {
+            this.priorityQueue.push(texture);
+            return;
+        }
+        // If the texture failed to load, we need to re-download it.
+        if (texture.state === 'failed') {
+            texture.free();
+            texture.freeTextureData();
+        }
+        texture.setState('loading');
+        // Get the texture data
+        texture
+            .getTextureData()
+            .then(() => {
+            if (texture.state !== 'fetched') {
+                texture.setState('failed');
+                return;
+            }
+            // For non-image textures, upload immediately
+            if (texture.type !== TextureType.image) {
+                this.uploadTexture(texture).catch((err) => {
+                    console.error('Failed to upload non-image texture:', err);
+                    texture.setState('failed');
+                });
+            }
+            else {
+                // For image textures, queue for throttled upload
+                // If it's a priority texture, upload it immediately
+                if (priority === true) {
+                    this.uploadTexture(texture).catch((err) => {
+                        console.error('Failed to upload priority texture:', err);
+                        texture.setState('failed');
+                    });
+                }
+                else {
+                    this.enqueueUploadTexture(texture);
+                }
+            }
+        })
+            .catch((err) => {
+            console.error(err);
+            texture.setState('failed');
+        });
+    }
+    /**
+     * Upload a texture to the GPU
+     *
+     * @param texture Texture to upload
+     * @returns Promise that resolves when the texture is fully loaded
+     */
+    async uploadTexture(texture) {
+        if (this.stage.txMemManager.doNotExceedCriticalThreshold === true &&
+            this.stage.txMemManager.criticalCleanupRequested === true) {
+            // we're at a critical memory threshold, don't upload textures
+            texture.setState('failed');
+            return;
+        }
+        const coreContext = texture.loadCtxTexture();
+        if (coreContext !== null && coreContext.state === 'loaded') {
+            texture.setState('loaded');
+            return;
+        }
+        await coreContext.load();
+    }
+    /**
+     * Check if a texture is being processed
+     */
+    isProcessingTexture(texture) {
+        return this.uploadTextureQueue.includes(texture) === true;
+    }
+    /**
+     * Process a limited number of uploads.
+     *
+     * @param maxProcessingTime - The maximum processing time in milliseconds
+     */
+    async processSome(maxProcessingTime) {
+        if (this.initialized === false) {
+            return;
+        }
+        const startTime = getTimeStamp();
+        // Process priority queue
+        while (this.priorityQueue.length > 0 &&
+            getTimeStamp() - startTime < maxProcessingTime) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const texture = this.priorityQueue.pop();
+            try {
+                await texture.getTextureData();
+                await this.uploadTexture(texture);
+            }
+            catch (error) {
+                console.error('Failed to process priority texture:', error);
+                // Continue with next texture instead of stopping entire queue
+            }
+        }
+        // Process uploads - await each upload to prevent GPU overload
+        while (this.uploadTextureQueue.length > 0 &&
+            getTimeStamp() - startTime < maxProcessingTime) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const texture = this.uploadTextureQueue.shift();
+            try {
+                await this.uploadTexture(texture);
+            }
+            catch (error) {
+                console.error('Failed to upload texture:', error);
+                // Continue with next texture instead of stopping entire queue
+            }
+        }
+    }
+    hasUpdates() {
+        return this.uploadTextureQueue.length > 0;
+    }
+    /**
+     * Initialize a texture to the cache
+     *
+     * @param texture Texture to cache
+     * @param cacheKey Cache key for the texture
+     */
+    initTextureToCache(texture, cacheKey) {
+        const { keyCache, inverseKeyCache } = this;
+        keyCache.set(cacheKey, texture);
+        inverseKeyCache.set(texture, cacheKey);
+    }
+    /**
+     * Get a texture from the cache
+     *
+     * @param cacheKey
+     */
+    getTextureFromCache(cacheKey) {
+        return this.keyCache.get(cacheKey);
+    }
+    /**
+     * Remove a texture from the cache
+     *
+     * @remarks
+     * Called by Texture Cleanup when a texture is freed.
+     *
+     * @param texture
+     */
+    removeTextureFromCache(texture) {
+        const { inverseKeyCache, keyCache } = this;
+        const cacheKey = inverseKeyCache.get(texture);
+        if (cacheKey) {
+            keyCache.delete(cacheKey);
+        }
+    }
+    /**
+     * Remove texture from the upload queue
+     *
+     * @param texture - The texture to remove
+     */
+    removeTextureFromQueue(texture) {
+        const uploadIndex = this.uploadTextureQueue.indexOf(texture);
+        if (uploadIndex !== -1) {
+            this.uploadTextureQueue.splice(uploadIndex, 1);
+        }
+    }
+    /**
+     * Resolve a parent texture from the cache or fallback to the provided texture.
+     *
+     * @param texture - The provided texture to resolve.
+     * @returns The cached or provided texture.
+     */
+    resolveParentTexture(texture) {
+        if (!texture?.props) {
+            return texture;
+        }
+        const cacheKey = ImageTexture.makeCacheKey(texture.props);
+        const cachedTexture = cacheKey
+            ? this.getTextureFromCache(cacheKey)
+            : undefined;
+        return cachedTexture ?? texture;
+    }
+}
+//# sourceMappingURL=CoreTextureManager.js.map

package/dist/src/core/CoreTextureManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoreTextureManager.js","sourceRoot":"","sources":["../../../src/core/CoreTextureManager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,210 @@
+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, type ShaderMap } from './CoreShaderManager.js';
+import { TextRenderer, type TextRendererMap, type TrProps } from './text-rendering/renderers/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 { WebGlCoreRenderer } from './renderers/webgl/WebGlCoreRenderer.js';
+import type { CanvasCoreRenderer } from './renderers/canvas/CanvasCoreRenderer.js';
+import type { BaseShaderController } from '../main-api/ShaderController.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 Bound } from './lib/utils.js';
+import type { Texture } from './textures/Texture.js';
+export interface StageOptions {
+    appWidth: number;
+    appHeight: number;
+    textureMemory: TextureMemoryManagerSettings;
+    boundsMargin: number | [number, number, number, number];
+    deviceLogicalPixelRatio: number;
+    devicePhysicalPixelRatio: number;
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    clearColor: number;
+    fpsUpdateInterval: number;
+    targetFPS: number;
+    enableContextSpy: boolean;
+    forceWebGL2: boolean;
+    numImageWorkers: number;
+    renderEngine: typeof WebGlCoreRenderer | typeof CanvasCoreRenderer;
+    eventBus: EventEmitter;
+    quadBufferSize: number;
+    fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[];
+    inspector: boolean;
+    strictBounds: boolean;
+    textureProcessingTimeLimit: number;
+    createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
+}
+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;
+    readonly animationManager: AnimationManager;
+    readonly txManager: CoreTextureManager;
+    readonly txMemManager: TextureMemoryManager;
+    readonly fontManager: TrFontManager;
+    readonly textRenderers: Partial<TextRendererMap>;
+    readonly shManager: CoreShaderManager;
+    readonly renderer: CoreRenderer;
+    readonly root: CoreNode;
+    readonly interactiveNodes: Set<CoreNode>;
+    boundsMargin: [number, number, number, number];
+    readonly defShaderCtr: BaseShaderController;
+    readonly strictBound: Bound;
+    readonly preloadBound: Bound;
+    readonly strictBounds: boolean;
+    readonly defaultTexture: Texture | null;
+    /**
+     * 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;
+    deltaTime: number;
+    lastFrameTime: number;
+    currentFrameTime: number;
+    private fpsNumFrames;
+    private fpsElapsedTime;
+    private numQuadsRendered;
+    private renderRequested;
+    private frameEventQueue;
+    private fontResolveMap;
+    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(): void;
+    /**
+     * Check if the scene has updates
+     */
+    hasSceneUpdates(): boolean;
+    /**
+     * Start a new frame draw
+     */
+    drawFrame(): 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;
+    calculateQuads(): void;
+    addQuads(node: CoreNode): void;
+    /**
+     * Request a render pass without forcing an update
+     */
+    requestRender(): 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;
+    /**
+     * 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 TextRendererMap | null): TextRenderer | null;
+    /**
+     * Create a shader controller instance
+     *
+     * @param type
+     * @param props
+     * @returns
+     */
+    createShaderCtr(type: keyof ShaderMap, props: Record<string, unknown>): BaseShaderController;
+    createNode(props: Partial<CoreNodeProps>): CoreNode;
+    createTextNode(props: Partial<CoreTextNodeProps>): CoreTextNode;
+    setBoundsMargin(value: number | [number, number, number, number]): 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(aggressive: boolean): void;
+}