@lightningjs/renderer 3.0.0-beta1 → 3.0.0-beta11

package/dist/src/core/Stage.js

@@ -16,20 +16,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { startLoop, getTimeStamp } from './platform.js';
 import { assertTruthy, setPremultiplyMode } from '../utils.js';
 import { AnimationManager } from './animations/AnimationManager.js';
 import { UpdateType, CoreNode, CoreNodeRenderState, } from './CoreNode.js';
 import { CoreTextureManager } from './CoreTextureManager.js';
-import { TrFontManager } from './text-rendering/TrFontManager.js';
 import { CoreShaderManager } from './CoreShaderManager.js';
-import { TextRenderer, } from './text-rendering/renderers/TextRenderer.js';
+import {} from './text-rendering/TextRenderer.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
 import { TextureMemoryManager, } from './TextureMemoryManager.js';
 import { CoreRenderer } from './renderers/CoreRenderer.js';
 import { CoreTextNode } from './CoreTextNode.js';
 import { santizeCustomDataMap } from '../main-api/utils.js';
+import { pointInBound } from './lib/utils.js';
 import { createBound, createPreloadBounds } from './lib/utils.js';
 import { ColorTexture } from './textures/ColorTexture.js';
 const autoStart = true;
@@ -39,11 +38,12 @@ export class Stage {
     animationManager;
     txManager;
     txMemManager;
-    fontManager;
-    textRenderers;
+    textRenderers = {};
+    fontHandlers = {};
     shManager;
     renderer;
     root;
+    interactiveNodes = new Set();
     boundsMargin;
     defShaderNode = null;
     strictBound;
@@ -52,6 +52,17 @@ export class Stage {
     defaultTexture = null;
     pixelRatio;
     bufferMemory = 2e6;
+    platform;
+    calculateTextureCoord;
+    /**
+     * 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 = 0;
     /**
      * Renderer Event Bus for the Stage to emit events onto
      *
@@ -71,16 +82,25 @@ export class Stage {
     numQuadsRendered = 0;
     renderRequested = false;
     frameEventQueue = [];
-    fontResolveMap = {};
-    /// Debug data
+    // Font resolve optimisation flags
+    hasOnlyOneFontEngine;
+    hasOnlyCanvasFontEngine;
+    hasCanvasEngine;
+    singleFontEngine = null;
+    singleFontHandler = null;
+    // Debug data
     contextSpy = null;
     /**
      * Stage constructor
      */
     constructor(options) {
         this.options = options;
-        const { canvas, clearColor, appWidth, appHeight, boundsMargin, enableContextSpy, forceWebGL2, numImageWorkers, textureMemory, renderEngine, fontEngines, createImageBitmapSupport, } = options;
+        const { canvas, clearColor, appWidth, appHeight, boundsMargin, enableContextSpy, forceWebGL2, numImageWorkers, textureMemory, renderEngine, fontEngines, createImageBitmapSupport, platform, } = options;
+        assertTruthy(platform !== null, 'A CorePlatform is not provided in the options');
+        this.platform = platform;
         this.eventBus = options.eventBus;
+        // Calculate target frame time from targetFPS option
+        this.targetFrameTime = options.targetFPS > 0 ? 1000 / options.targetFPS : 0;
         this.txManager = new CoreTextureManager(this, {
             numImageWorkers,
             createImageBitmapSupport,
@@ -115,34 +135,79 @@ export class Stage {
         });
         this.shManager = new CoreShaderManager(this);
         this.defShaderNode = this.renderer.getDefaultShaderNode();
+        this.calculateTextureCoord = this.renderer.getTextureCoords !== undefined;
         const renderMode = this.renderer.mode || 'webgl';
         this.createDefaultTexture();
         setPremultiplyMode(renderMode);
         // Must do this after renderer is created
         this.txManager.renderer = this.renderer;
         // Create text renderers
-        this.textRenderers = {};
-        fontEngines.forEach((fontEngineConstructor) => {
-            const fontEngineInstance = new fontEngineConstructor(this);
-            const className = fontEngineInstance.type;
-            if (className === 'sdf' && renderMode === 'canvas') {
-                console.warn('SdfTextRenderer is not compatible with Canvas renderer. Skipping...');
-                return;
-            }
-            if (fontEngineInstance instanceof TextRenderer) {
-                if (className === 'canvas') {
-                    this.textRenderers['canvas'] =
-                        fontEngineInstance;
+        this.hasOnlyOneFontEngine = fontEngines.length === 1;
+        this.hasOnlyCanvasFontEngine =
+            fontEngines.length === 1 && fontEngines[0].type === 'canvas';
+        this.hasCanvasEngine = false;
+        this.singleFontEngine = this.hasOnlyOneFontEngine
+            ? fontEngines[0]
+            : null;
+        this.singleFontHandler = this.hasOnlyOneFontEngine
+            ? fontEngines[0]?.font
+            : null;
+        if (this.singleFontEngine === null) {
+            // Multiple font engines case
+            // Filter out incompatible engines first
+            const compatibleEngines = fontEngines.filter((fontEngine) => {
+                const type = fontEngine.type;
+                if (type === 'sdf' && renderMode === 'canvas') {
+                    console.warn('MsdfTextRenderer is not compatible with Canvas renderer. Skipping...');
+                    return false;
                 }
-                else if (className === 'sdf') {
-                    this.textRenderers['sdf'] = fontEngineInstance;
+                if (type === 'canvas') {
+                    this.hasCanvasEngine = true;
                 }
+                return true;
+            });
+            // Sort engines: SDF first, Canvas last, others in between
+            const sortedEngines = compatibleEngines.sort((a, b) => {
+                if (a.type === 'sdf')
+                    return -1;
+                if (b.type === 'sdf')
+                    return 1;
+                if (a.type === 'canvas')
+                    return 1;
+                if (b.type === 'canvas')
+                    return -1;
+                return 0;
+            });
+            // Initialize engines in sorted order
+            sortedEngines.forEach((fontEngine) => {
+                const type = fontEngine.type;
+                // Add to map for type-based access
+                this.textRenderers[type] = fontEngine;
+                this.textRenderers[type].init(this);
+                this.fontHandlers[type] = fontEngine.font;
+            });
+        }
+        else {
+            // Single font engine case - initialize it directly
+            const fontEngine = this.singleFontEngine;
+            const type = fontEngine.type;
+            // Check compatibility
+            if (type === 'sdf' && renderMode === 'canvas') {
+                console.warn('MsdfTextRenderer is not compatible with Canvas renderer. Skipping...');
             }
-        });
+            else {
+                if (type === 'canvas') {
+                    this.hasCanvasEngine = true;
+                }
+                // Add to map for type-based access
+                this.textRenderers[type] = fontEngine;
+                this.fontHandlers[type] = fontEngine.font;
+                this.textRenderers[type].init(this);
+            }
+        }
         if (Object.keys(this.textRenderers).length === 0) {
             console.warn('No text renderers available. Your text will not render.');
         }
-        this.fontManager = new TrFontManager(this.textRenderers);
         // create root node
         const rootNode = new CoreNode(this, {
             x: 0,
@@ -180,13 +245,12 @@ export class Stage {
             rtt: false,
             src: null,
             scale: 1,
-            preventCleanup: false,
             strictBounds: this.strictBounds,
         });
         this.root = rootNode;
         // execute platform start loop
-        if (autoStart) {
-            startLoop(this);
+        if (autoStart === true) {
+            this.platform.startLoop(this);
         }
     }
     setClearColor(color) {
@@ -194,8 +258,21 @@ export class Stage {
         this.renderer.updateClearColor(color);
         this.renderRequested = true;
     }
+    /**
+     * 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() {
+        this.targetFrameTime =
+            this.options.targetFPS > 0 ? 1000 / this.options.targetFPS : 0;
+    }
     updateFrameTime() {
-        const newFrameTime = getTimeStamp();
+        const newFrameTime = this.platform.getTimeStamp();
         this.lastFrameTime = this.currentFrameTime;
         this.currentFrameTime = newFrameTime;
         this.deltaTime = !this.lastFrameTime
@@ -214,7 +291,6 @@ export class Stage {
      * Create default PixelTexture
      */
     createDefaultTexture() {
-        console.log('Creating default texture');
         this.defaultTexture = this.txManager.createTexture('ColorTexture', {
             color: 0xffffffff,
         });
@@ -253,22 +329,27 @@ export class Stage {
      * Start a new frame draw
      */
     drawFrame() {
-        const { renderer, renderRequested } = this;
-        assertTruthy(renderer);
+        const { renderer, renderRequested, root } = this;
+        const txMemManager = this.txMemManager;
         // Update tree if needed
-        if (this.root.updateType !== 0) {
-            this.root.update(this.deltaTime, this.root.clippingRect);
+        if (root.updateType !== 0) {
+            root.update(this.deltaTime, root.clippingRect);
         }
-        // Process some textures
-        this.txManager.processSome(this.options.textureProcessingTimeLimit);
+        // Process some textures asynchronously but don't block the frame
+        // Use a background task to prevent frame drops
+        this.txManager
+            .processSome(this.options.textureProcessingTimeLimit)
+            .catch((err) => {
+            console.error('Error processing textures:', err);
+        });
         // Reset render operations and clear the canvas
         renderer.reset();
         // Check if we need to cleanup textures
-        if (this.txMemManager.criticalCleanupRequested === true) {
-            this.txMemManager.cleanup(false);
-            if (this.txMemManager.criticalCleanupRequested === true) {
+        if (txMemManager.criticalCleanupRequested === true) {
+            txMemManager.cleanup(false);
+            if (txMemManager.criticalCleanupRequested === true) {
                 // If we still need to cleanup, request another but aggressive cleanup
-                this.txMemManager.cleanup(true);
+                txMemManager.cleanup(true);
             }
         }
         // If we have RTT nodes draw them first
@@ -279,11 +360,11 @@ export class Stage {
         // Fill quads buffer
         this.addQuads(this.root);
         // Perform render pass
-        renderer?.render();
+        renderer.render();
         this.calculateFps();
         this.calculateQuads();
         // Reset renderRequested flag if it was set
-        if (renderRequested) {
+        if (renderRequested === true) {
             this.renderRequested = false;
         }
     }
@@ -383,88 +464,68 @@ export class Stage {
      * @returns
      */
     resolveTextRenderer(trProps, textRendererOverride = null) {
-        const fontCacheString = `${trProps.fontFamily}${trProps.fontStyle}${trProps.fontWeight}${trProps.fontStretch}${textRendererOverride ? textRendererOverride : ''}`;
-        // check our resolve cache first
-        if (this.fontResolveMap[fontCacheString] !== undefined) {
-            return this.fontResolveMap[fontCacheString];
-        }
-        // Resolve the text renderer
-        let rendererId = textRendererOverride;
-        let overrideFallback = false;
-        // Check if the override is valid (if one is provided)
-        if (rendererId) {
-            const possibleRenderer = this.textRenderers[rendererId];
-            if (!possibleRenderer) {
-                console.warn(`Text renderer override '${rendererId}' not found.`);
-                rendererId = null;
-                overrideFallback = true;
-            }
-            else if (!possibleRenderer.canRenderFont(trProps)) {
-                console.warn(`Cannot use override text renderer '${rendererId}' for font`, trProps);
-                rendererId = null;
-                overrideFallback = true;
+        // If we have an overide, return it
+        if (textRendererOverride !== null) {
+            const overrideKey = String(textRendererOverride);
+            if (this.textRenderers[overrideKey] === undefined) {
+                console.warn(`Text renderer override '${overrideKey}' not found.`);
+                return null;
             }
+            return this.textRenderers[overrideKey];
         }
-        if (!rendererId) {
-            // Iterate through the text renderers and find the first one that can render the font
-            for (const [trId, tr] of Object.entries(this.textRenderers)) {
-                if (tr.canRenderFont(trProps)) {
-                    rendererId = trId;
-                    break;
-                }
+        // If we have only one font engine early return it
+        if (this.singleFontEngine !== null) {
+            // If we have only one font engine and its the canvas engine, we can just return it
+            if (this.hasOnlyCanvasFontEngine === true) {
+                return this.singleFontEngine;
             }
-            if (!rendererId && this.textRenderers.canvas !== undefined) {
-                // If no renderer can be found, use the canvas renderer
-                rendererId = 'canvas';
+            // If we have only one font engine and it can render the font, return it
+            if (this.singleFontHandler?.canRenderFont(trProps) === true) {
+                return this.singleFontEngine;
             }
+            // If we have only one font engine and it cannot render the font, return null
+            console.warn(`Text renderer cannot render font`, trProps);
+            return null;
         }
-        if (overrideFallback) {
-            console.warn(`Falling back to text renderer ${String(rendererId)}`);
+        // Multi font handling  - If we have multiple font engines, we need to resolve the best one
+        // First check SDF
+        if (this.fontHandlers['sdf']?.canRenderFont(trProps) === true) {
+            return this.textRenderers.sdf || null;
         }
-        if (!rendererId) {
-            // silently fail if no renderer can be found, the error is already created
-            // at the constructor level
-            return null;
+        // If we have a canvas engine, we can return it (it can render all fonts)
+        if (this.hasCanvasEngine === true) {
+            return this.textRenderers.canvas || null;
         }
-        // By now we are guaranteed to have a valid rendererId (at least Canvas);
-        const resolvedTextRenderer = this.textRenderers[rendererId];
-        assertTruthy(resolvedTextRenderer, 'resolvedTextRenderer undefined');
-        // cache the resolved renderer for future use with these trProps
-        this.fontResolveMap[fontCacheString] = resolvedTextRenderer;
-        // Need to explicitly cast to TextRenderer because TS doesn't like
-        // the covariant state argument in the setter method map
-        return resolvedTextRenderer;
+        // If we have no font engines, return null
+        console.warn('No text renderers available. Your text will not render.');
+        return null;
     }
     createNode(props) {
         const resolvedProps = this.resolveNodeDefaults(props);
         return new CoreNode(this, resolvedProps);
     }
     createTextNode(props) {
-        const fontSize = props.fontSize ?? 16;
-        const resolvedProps = {
-            ...this.resolveNodeDefaults(props),
-            text: props.text ?? '',
-            textRendererOverride: props.textRendererOverride ?? null,
+        const fontSize = props.fontSize || 16;
+        const resolvedProps = Object.assign(this.resolveNodeDefaults(props), {
+            text: props.text || '',
+            textRendererOverride: props.textRendererOverride || null,
             fontSize,
-            fontFamily: props.fontFamily ?? 'sans-serif',
-            fontStyle: props.fontStyle ?? 'normal',
-            fontWeight: props.fontWeight ?? 'normal',
-            fontStretch: props.fontStretch ?? 'normal',
-            textAlign: props.textAlign ?? 'left',
-            contain: props.contain ?? 'none',
-            scrollable: props.scrollable ?? false,
-            scrollY: props.scrollY ?? 0,
-            offsetY: props.offsetY ?? 0,
-            letterSpacing: props.letterSpacing ?? 0,
-            lineHeight: props.lineHeight, // `undefined` is a valid value
-            maxLines: props.maxLines ?? 0,
-            textBaseline: props.textBaseline ?? 'alphabetic',
-            verticalAlign: props.verticalAlign ?? 'middle',
-            overflowSuffix: props.overflowSuffix ?? '...',
-            debug: props.debug ?? {},
-            shaderProps: null,
-        };
-        const resolvedTextRenderer = this.resolveTextRenderer(resolvedProps, props.textRendererOverride);
+            fontFamily: props.fontFamily || 'sans-serif',
+            fontStyle: props.fontStyle || 'normal',
+            textAlign: props.textAlign || 'left',
+            offsetY: props.offsetY || 0,
+            letterSpacing: props.letterSpacing || 0,
+            lineHeight: props.lineHeight || 0,
+            maxLines: props.maxLines || 0,
+            textBaseline: props.textBaseline || 'alphabetic',
+            verticalAlign: props.verticalAlign || 'middle',
+            overflowSuffix: props.overflowSuffix || '...',
+            wordBreak: props.wordBreak || 'normal',
+            maxWidth: props.maxWidth || 0,
+            maxHeight: props.maxHeight || 0,
+            forceLoad: props.forceLoad || false,
+        });
+        const resolvedTextRenderer = this.resolveTextRenderer(resolvedProps, resolvedProps.textRendererOverride);
         if (!resolvedTextRenderer) {
             throw new Error(`No compatible text renderer found for ${resolvedProps.fontFamily}`);
         }
@@ -476,6 +537,51 @@ export class Stage {
             : [value, value, value, value];
         this.root.setUpdateType(UpdateType.RenderBounds);
     }
+    /**
+     * Update the viewport bounds
+     */
+    updateViewportBounds() {
+        const { appWidth, appHeight } = this.options;
+        this.strictBound = createBound(0, 0, appWidth, appHeight);
+        this.preloadBound = createPreloadBounds(this.strictBound, this.boundsMargin);
+        this.root.setUpdateType(UpdateType.RenderBounds | UpdateType.Children);
+        this.root.childUpdateType |= UpdateType.RenderBounds;
+    }
+    /** Find all nodes at a given point
+     * @param data
+     */
+    findNodesAtPoint(data) {
+        const x = data.x / this.options.deviceLogicalPixelRatio;
+        const y = data.y / this.options.deviceLogicalPixelRatio;
+        const nodes = [];
+        for (const node of this.interactiveNodes) {
+            if (node.isRenderable === false) {
+                continue;
+            }
+            if (pointInBound(x, y, node.renderBound) === true) {
+                nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+    /**
+     * Find the top node at a given point
+     * @param data
+     * @returns
+     */
+    getNodeFromPosition(data) {
+        const nodes = this.findNodesAtPoint(data);
+        if (nodes.length === 0) {
+            return null;
+        }
+        let topNode = nodes[0];
+        for (let i = 0; i < nodes.length; i++) {
+            if (nodes[i].zIndex > topNode.zIndex) {
+                topNode = nodes[i];
+            }
+        }
+        return topNode || null;
+    }
     /**
      * Resolves the default property values for a Node
      *
@@ -488,15 +594,22 @@ export class Stage {
      * @returns
      */
     resolveNodeDefaults(props) {
+        const { colorTop: top, colorBottom: bottom, colorLeft: left, colorRight: right, } = props;
         const color = props.color ?? 0xffffffff;
-        const colorTl = props.colorTl ?? props.colorTop ?? props.colorLeft ?? color;
-        const colorTr = props.colorTr ?? props.colorTop ?? props.colorRight ?? color;
-        const colorBl = props.colorBl ?? props.colorBottom ?? props.colorLeft ?? color;
-        const colorBr = props.colorBr ?? props.colorBottom ?? props.colorRight ?? color;
-        let data = {};
-        if (this.options.inspector === true) {
-            data = santizeCustomDataMap(props.data ?? {});
-        }
+        const colorTop = top ?? color;
+        const colorBottom = bottom ?? color;
+        const colorLeft = left ?? color;
+        const colorRight = right ?? color;
+        const colorTl = props.colorTl ?? top ?? left ?? color;
+        const colorTr = props.colorTr ?? top ?? right ?? color;
+        const colorBl = props.colorBl ?? bottom ?? left ?? color;
+        const colorBr = props.colorBr ?? bottom ?? right ?? color;
+        const scale = props.scale ?? null;
+        const mount = props.mount ?? 0;
+        const pivot = props.pivot ?? 0.5;
+        const data = this.options.inspector
+            ? santizeCustomDataMap(props.data ?? {})
+            : {};
         return {
             x: props.x ?? 0,
             y: props.y ?? 0,
@@ -507,41 +620,39 @@ export class Stage {
             boundsMargin: props.boundsMargin ?? null,
             clipping: props.clipping ?? false,
             color,
-            colorTop: props.colorTop ?? color,
-            colorBottom: props.colorBottom ?? color,
-            colorLeft: props.colorLeft ?? color,
-            colorRight: props.colorRight ?? color,
-            colorBl,
-            colorBr,
+            colorTop,
+            colorBottom,
+            colorLeft,
+            colorRight,
             colorTl,
             colorTr,
+            colorBl,
+            colorBr,
             zIndex: props.zIndex ?? 0,
             zIndexLocked: props.zIndexLocked ?? 0,
             parent: props.parent ?? null,
             texture: props.texture ?? null,
             textureOptions: props.textureOptions ?? {},
             shader: props.shader ?? this.defShaderNode,
-            // Since setting the `src` will trigger a texture load, we need to set it after
-            // we set the texture. Otherwise, problems happen.
             src: props.src ?? null,
             srcHeight: props.srcHeight,
             srcWidth: props.srcWidth,
             srcX: props.srcX,
             srcY: props.srcY,
-            scale: props.scale ?? null,
-            scaleX: props.scaleX ?? props.scale ?? 1,
-            scaleY: props.scaleY ?? props.scale ?? 1,
-            mount: props.mount ?? 0,
-            mountX: props.mountX ?? props.mount ?? 0,
-            mountY: props.mountY ?? props.mount ?? 0,
-            pivot: props.pivot ?? 0.5,
-            pivotX: props.pivotX ?? props.pivot ?? 0.5,
-            pivotY: props.pivotY ?? props.pivot ?? 0.5,
+            scale,
+            scaleX: props.scaleX ?? scale ?? 1,
+            scaleY: props.scaleY ?? scale ?? 1,
+            mount,
+            mountX: props.mountX ?? mount,
+            mountY: props.mountY ?? mount,
+            pivot,
+            pivotX: props.pivotX ?? pivot,
+            pivotY: props.pivotY ?? pivot,
             rotation: props.rotation ?? 0,
             rtt: props.rtt ?? false,
-            data: data,
-            preventCleanup: props.preventCleanup ?? false,
+            data,
             imageType: props.imageType,
+            interactive: props.interactive ?? false,
             strictBounds: props.strictBounds ?? this.strictBounds,
         };
     }
@@ -562,5 +673,28 @@ export class Stage {
     get clearColor() {
         return this.clrColor;
     }
+    /**
+     * 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
+     */
+    async loadFont(rendererType, options) {
+        const rendererTypeKey = String(rendererType);
+        const fontHandler = this.fontHandlers[rendererTypeKey];
+        if (!fontHandler) {
+            throw new Error(`Font handler for renderer type '${rendererTypeKey}' not found. Available types: ${Object.keys(this.fontHandlers).join(', ')}`);
+        }
+        return fontHandler.loadFont(this, options);
+    }
 }
 //# sourceMappingURL=Stage.js.map