@lightningjs/renderer 1.0.0 → 2.0.0

package/src/core/CoreNode.ts

@@ -405,6 +405,11 @@ export interface CoreNodeProps {
    */
   texture: Texture | null;
 
+  /**
+   * Whether to prevent the node from being cleaned up
+   * @default false
+   */
+  preventCleanup: boolean;
   /**
    * Options to associate with the Node's Texture
    */
@@ -613,6 +618,47 @@ export interface CoreNodeProps {
    * @default `undefined`
    */
   data?: CustomDataMap;
+
+  /**
+   * Image Type to explicitly set the image type that is being loaded
+   *
+   * @remarks
+   * This property must be used with a `src` that points at an image. In some cases
+   * the extension doesn't provide a reliable representation of the image type. In such
+   * cases set the ImageType explicitly.
+   *
+   * `regular` is used for normal images such as png, jpg, etc
+   * `compressed` is used for ETC1/ETC2 compressed images with a PVR or KTX container
+   * `svg` is used for scalable vector graphics
+   *
+   * @default `undefined`
+   */
+  imageType?: 'regular' | 'compressed' | 'svg' | null;
+
+  /**
+   * She width of the rectangle from which the Image Texture will be extracted.
+   * This value can be negative. If not provided, the image's source natural
+   * width will be used.
+   */
+  srcWidth?: number;
+  /**
+   * The height of the rectangle from which the Image Texture will be extracted.
+   * This value can be negative. If not provided, the image's source natural
+   * height will be used.
+   */
+  srcHeight?: number;
+  /**
+   * The x coordinate of the reference point of the rectangle from which the Texture
+   * will be extracted.  `width` and `height` are provided. And only works when
+   * createImageBitmap is available. Only works when createImageBitmap is supported on the browser.
+   */
+  srcX?: number;
+  /**
+   * The y coordinate of the reference point of the rectangle from which the Texture
+   * will be extracted. Only used when source `srcWidth` width and `srcHeight` height
+   * are provided. Only works when createImageBitmap is supported on the browser.
+   */
+  srcY?: number;
 }
 
 /**
@@ -704,6 +750,7 @@ export class CoreNode extends EventEmitter {
     // We do this in a microtask to allow listeners to be attached in the same
     // synchronous task after calling loadTexture()
     queueMicrotask(() => {
+      texture.preventCleanup = this.props.preventCleanup;
       // Preload texture if required
       if (this.textureOptions.preload) {
         texture.ctxTexture.load();
@@ -1387,6 +1434,14 @@ export class CoreNode extends EventEmitter {
     return this._id;
   }
 
+  get data(): CustomDataMap | undefined {
+    return this.props.data;
+  }
+
+  set data(d: CustomDataMap | undefined) {
+    this.props.data = d;
+  }
+
   get x(): number {
     return this.props.x;
   }
@@ -1401,12 +1456,17 @@ export class CoreNode extends EventEmitter {
   get absX(): number {
     return (
       this.props.x +
+      -this.props.width * this.props.mountX +
       (this.props.parent?.absX || this.props.parent?.globalTransform?.tx || 0)
     );
   }
 
   get absY(): number {
-    return this.props.y + (this.props.parent?.absY ?? 0);
+    return (
+      this.props.y +
+      -this.props.height * this.props.mountY +
+      (this.props.parent?.absY ?? 0)
+    );
   }
 
   get y(): number {
@@ -1767,6 +1827,14 @@ export class CoreNode extends EventEmitter {
     this.updateScaleRotateTransform();
   }
 
+  get preventCleanup(): boolean {
+    return this.props.preventCleanup;
+  }
+
+  set preventCleanup(value: boolean) {
+    this.props.preventCleanup = value;
+  }
+
   get rtt(): boolean {
     return this.props.rtt;
   }
@@ -1845,9 +1913,60 @@ export class CoreNode extends EventEmitter {
 
     this.texture = this.stage.txManager.loadTexture('ImageTexture', {
       src: imageUrl,
+      width: this.props.width,
+      height: this.props.height,
+      type: this.props.imageType,
+      sx: this.props.srcX,
+      sy: this.props.srcY,
+      sw: this.props.srcWidth,
+      sh: this.props.srcHeight,
     });
   }
 
+  set imageType(type: 'regular' | 'compressed' | 'svg' | null) {
+    if (this.props.imageType === type) {
+      return;
+    }
+
+    this.props.imageType = type;
+  }
+
+  get imageType() {
+    return this.props.imageType || null;
+  }
+
+  get srcHeight(): number | undefined {
+    return this.props.srcHeight;
+  }
+
+  set srcHeight(value: number) {
+    this.props.srcHeight = value;
+  }
+
+  get srcWidth(): number | undefined {
+    return this.props.srcWidth;
+  }
+
+  set srcWidth(value: number) {
+    this.props.srcWidth = value;
+  }
+
+  get srcX(): number | undefined {
+    return this.props.srcX;
+  }
+
+  set srcX(value: number) {
+    this.props.srcX = value;
+  }
+
+  get srcY(): number | undefined {
+    return this.props.srcY;
+  }
+
+  set srcY(value: number) {
+    this.props.srcY = value;
+  }
+
   /**
    * Returns the framebuffer dimensions of the node.
    * If the node has a render texture, the dimensions are the same as the node's dimensions.

package/src/core/CoreTextNode.ts

@@ -75,37 +75,41 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   private _textRendererOverride: CoreTextNodeProps['textRendererOverride'] =
     null;
 
-  constructor(stage: Stage, props: CoreTextNodeProps) {
+  constructor(
+    stage: Stage,
+    props: CoreTextNodeProps,
+    textRenderer: TextRenderer,
+  ) {
     super(stage, props);
     this._textRendererOverride = props.textRendererOverride;
-    const { resolvedTextRenderer, textRendererState } =
-      this.resolveTextRendererAndState({
-        x: this.absX,
-        y: this.absY,
-        width: props.width,
-        height: props.height,
-        textAlign: props.textAlign,
-        color: props.color,
-        zIndex: props.zIndex,
-        contain: props.contain,
-        scrollable: props.scrollable,
-        scrollY: props.scrollY,
-        offsetY: props.offsetY,
-        letterSpacing: props.letterSpacing,
-        debug: props.debug,
-        fontFamily: props.fontFamily,
-        fontSize: props.fontSize,
-        fontStretch: props.fontStretch,
-        fontStyle: props.fontStyle,
-        fontWeight: props.fontWeight,
-        text: props.text,
-        lineHeight: props.lineHeight,
-        maxLines: props.maxLines,
-        textBaseline: props.textBaseline,
-        verticalAlign: props.verticalAlign,
-        overflowSuffix: props.overflowSuffix,
-      });
-    this.textRenderer = resolvedTextRenderer;
+    this.textRenderer = textRenderer;
+    const textRendererState = this.createState({
+      x: this.absX,
+      y: this.absY,
+      width: props.width,
+      height: props.height,
+      textAlign: props.textAlign,
+      color: props.color,
+      zIndex: props.zIndex,
+      contain: props.contain,
+      scrollable: props.scrollable,
+      scrollY: props.scrollY,
+      offsetY: props.offsetY,
+      letterSpacing: props.letterSpacing,
+      debug: props.debug,
+      fontFamily: props.fontFamily,
+      fontSize: props.fontSize,
+      fontStretch: props.fontStretch,
+      fontStyle: props.fontStyle,
+      fontWeight: props.fontWeight,
+      text: props.text,
+      lineHeight: props.lineHeight,
+      maxLines: props.maxLines,
+      textBaseline: props.textBaseline,
+      verticalAlign: props.verticalAlign,
+      overflowSuffix: props.overflowSuffix,
+    });
+
     this.trState = textRendererState;
   }
 
@@ -199,13 +203,23 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
 
   set textRendererOverride(value: CoreTextNodeProps['textRendererOverride']) {
     this._textRendererOverride = value;
-
     this.textRenderer.destroyState(this.trState);
 
-    const { resolvedTextRenderer, textRendererState } =
-      this.resolveTextRendererAndState(this.trState.props);
-    this.textRenderer = resolvedTextRenderer;
-    this.trState = textRendererState;
+    const textRenderer = this.stage.resolveTextRenderer(
+      this.trState.props,
+      this._textRendererOverride,
+    );
+
+    if (!textRenderer) {
+      console.warn(
+        'Text Renderer not found for font',
+        this.trState.props.fontFamily,
+      );
+      return;
+    }
+
+    this.textRenderer = textRenderer;
+    this.trState = this.createState(this.trState.props);
   }
 
   get fontSize(): CoreTextNodeProps['fontSize'] {
@@ -301,9 +315,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   set lineHeight(value: CoreTextNodeProps['lineHeight']) {
-    if (this.textRenderer.set.lineHeight) {
-      this.textRenderer.set.lineHeight(this.trState, value);
-    }
+    this.textRenderer.set.lineHeight(this.trState, value);
   }
 
   get maxLines(): CoreTextNodeProps['maxLines'] {
@@ -311,9 +323,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   set maxLines(value: CoreTextNodeProps['maxLines']) {
-    if (this.textRenderer.set.maxLines) {
-      this.textRenderer.set.maxLines(this.trState, value);
-    }
+    this.textRenderer.set.maxLines(this.trState, value);
   }
 
   get textBaseline(): CoreTextNodeProps['textBaseline'] {
@@ -321,9 +331,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   set textBaseline(value: CoreTextNodeProps['textBaseline']) {
-    if (this.textRenderer.set.textBaseline) {
-      this.textRenderer.set.textBaseline(this.trState, value);
-    }
+    this.textRenderer.set.textBaseline(this.trState, value);
   }
 
   get verticalAlign(): CoreTextNodeProps['verticalAlign'] {
@@ -331,9 +339,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   set verticalAlign(value: CoreTextNodeProps['verticalAlign']) {
-    if (this.textRenderer.set.verticalAlign) {
-      this.textRenderer.set.verticalAlign(this.trState, value);
-    }
+    this.textRenderer.set.verticalAlign(this.trState, value);
   }
 
   get overflowSuffix(): CoreTextNodeProps['overflowSuffix'] {
@@ -341,9 +347,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   set overflowSuffix(value: CoreTextNodeProps['overflowSuffix']) {
-    if (this.textRenderer.set.overflowSuffix) {
-      this.textRenderer.set.overflowSuffix(this.trState, value);
-    }
+    this.textRenderer.set.overflowSuffix(this.trState, value);
   }
 
   get debug(): CoreTextNodeProps['debug'] {
@@ -365,7 +369,7 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   }
 
   override checkRenderProps(): boolean {
-    if (this.trState.props.text !== '') {
+    if (this.trState && this.trState.props.text !== '') {
       return true;
     }
     return super.checkRenderProps();
@@ -433,25 +437,14 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
    * @param props
    * @returns
    */
-  private resolveTextRendererAndState(props: TrProps): {
-    resolvedTextRenderer: TextRenderer;
-    textRendererState: TextRendererState;
-  } {
-    const resolvedTextRenderer = this.stage.resolveTextRenderer(
-      props,
-      this._textRendererOverride,
-    );
-
-    const textRendererState = resolvedTextRenderer.createState(props, this);
+  private createState(props: TrProps) {
+    const textRendererState = this.textRenderer.createState(props, this);
 
     textRendererState.emitter.on('loaded', this.onTextLoaded);
     textRendererState.emitter.on('failed', this.onTextFailed);
 
-    resolvedTextRenderer.scheduleUpdateState(textRendererState);
+    this.textRenderer.scheduleUpdateState(textRendererState);
 
-    return {
-      resolvedTextRenderer,
-      textRendererState,
-    };
+    return textRendererState;
   }
 }

package/src/core/Stage.ts

@@ -17,20 +17,18 @@
  * limitations under the License.
  */
 import { startLoop, getTimeStamp } from './platform.js';
-import { WebGlCoreRenderer } from './renderers/webgl/WebGlCoreRenderer.js';
 import { assertTruthy, setPremultiplyMode } from '../utils.js';
 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 type {
+import {
   TextRenderer,
-  TextRendererMap,
-  TrProps,
+  type TextRendererMap,
+  type TrProps,
 } from './text-rendering/renderers/TextRenderer.js';
-import { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-import { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
+
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
 import type {
@@ -41,14 +39,15 @@ import {
   TextureMemoryManager,
   type TextureMemoryManagerSettings,
 } from './TextureMemoryManager.js';
-import type {
-  CoreRenderer,
-  CoreRendererOptions,
-} from './renderers/CoreRenderer.js';
-import { CanvasCoreRenderer } from './renderers/canvas/CanvasCoreRenderer.js';
+import type { CoreRendererOptions } from './renderers/CoreRenderer.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 { santizeCustomDataMap } from '../main-api/utils.js';
+import type { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
+import type { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
 
 export interface StageOptions {
   appWidth: number;
@@ -62,9 +61,10 @@ export interface StageOptions {
   fpsUpdateInterval: number;
   enableContextSpy: boolean;
   numImageWorkers: number;
-  renderMode: 'webgl' | 'canvas';
+  renderEngine: typeof WebGlCoreRenderer | typeof CanvasCoreRenderer;
   eventBus: EventEmitter;
   quadBufferSize: number;
+  fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[];
 }
 
 export type StageFpsUpdateHandler = (
@@ -111,6 +111,8 @@ export class Stage {
   private fpsElapsedTime = 0;
   private renderRequested = false;
   private frameEventQueue: [name: string, payload: unknown][] = [];
+  private fontResolveMap: Record<string, CanvasTextRenderer | SdfTextRenderer> =
+    {};
 
   /// Debug data
   contextSpy: ContextSpy | null = null;
@@ -128,7 +130,8 @@ export class Stage {
       enableContextSpy,
       numImageWorkers,
       textureMemory,
-      renderMode,
+      renderEngine,
+      fontEngines,
     } = options;
 
     this.eventBus = options.eventBus;
@@ -159,26 +162,42 @@ export class Stage {
       contextSpy: this.contextSpy,
     };
 
-    if (renderMode === 'canvas') {
-      this.renderer = new CanvasCoreRenderer(rendererOptions);
-    } else {
-      this.renderer = new WebGlCoreRenderer(rendererOptions);
-    }
+    this.renderer = new renderEngine(rendererOptions);
+    const renderMode = this.renderer.mode || 'webgl';
+
     this.defShaderCtr = this.renderer.getDefShaderCtr();
     setPremultiplyMode(renderMode);
 
     // Must do this after renderer is created
     this.txManager.renderer = this.renderer;
 
-    this.textRenderers =
-      renderMode === 'webgl'
-        ? {
-            canvas: new CanvasTextRenderer(this),
-            sdf: new SdfTextRenderer(this),
-          }
-        : {
-            canvas: new CanvasTextRenderer(this),
-          };
+    // 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 as CanvasTextRenderer;
+        } else if (className === 'sdf') {
+          this.textRenderers['sdf'] = fontEngineInstance as SdfTextRenderer;
+        }
+      }
+    });
+
+    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
@@ -217,6 +236,7 @@ export class Stage {
       rtt: false,
       src: null,
       scale: 1,
+      preventCleanup: false,
     });
 
     this.root = rootNode;
@@ -393,7 +413,7 @@ export class Stage {
    * Given a font name, and possible renderer override, return the best compatible text renderer.
    *
    * @remarks
-   * Will always return at least a canvas renderer if no other suitable renderer can be resolved.
+   * Will try to return a canvas renderer if no other suitable renderer can be resolved.
    *
    * @param fontFamily
    * @param textRendererOverride
@@ -402,10 +422,20 @@ export class Stage {
   resolveTextRenderer(
     trProps: TrProps,
     textRendererOverride: keyof TextRendererMap | null = null,
-  ): TextRenderer {
-    let rendererId = textRendererOverride;
+  ): TextRenderer | 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] as unknown as TextRenderer;
+    }
 
+    // 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];
@@ -426,16 +456,12 @@ export class Stage {
     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 (trId === 'canvas') {
-          // Canvas is always a fallback
-          continue;
-        }
         if (tr.canRenderFont(trProps)) {
           rendererId = trId as keyof TextRendererMap;
           break;
         }
       }
-      if (!rendererId) {
+      if (!rendererId && this.textRenderers.canvas !== undefined) {
         // If no renderer can be found, use the canvas renderer
         rendererId = 'canvas';
       }
@@ -445,10 +471,19 @@ export class Stage {
       console.warn(`Falling back to text renderer ${String(rendererId)}`);
     }
 
+    if (!rendererId) {
+      // silently fail if no renderer can be found, the error is already created
+      // at the constructor level
+      return 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 as unknown as TextRenderer;
@@ -499,7 +534,18 @@ export class Stage {
       shaderProps: null,
     };
 
-    return new CoreTextNode(this, resolvedProps);
+    const resolvedTextRenderer = this.resolveTextRenderer(
+      resolvedProps,
+      props.textRendererOverride,
+    );
+
+    if (!resolvedTextRenderer) {
+      throw new Error(
+        `No compatible text renderer found for ${resolvedProps.fontFamily}`,
+      );
+    }
+
+    return new CoreTextNode(this, resolvedProps, resolvedTextRenderer);
   }
 
   /**
@@ -550,6 +596,10 @@ export class Stage {
       // 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,
@@ -562,6 +612,8 @@ export class Stage {
       rotation: props.rotation ?? 0,
       rtt: props.rtt ?? false,
       data: data,
+      preventCleanup: props.preventCleanup ?? false,
+      imageType: props.imageType,
     };
   }
 }

package/src/core/TextureMemoryManager.ts

@@ -227,8 +227,10 @@ export class TextureMemoryManager {
         // We don't want to free renderable textures because they will just likely be reloaded in the next frame
         break;
       }
-      texture.ctxTexture.free();
-      txManager.removeTextureFromCache(texture);
+      if (texture.preventCleanup === false) {
+        texture.ctxTexture.free();
+        txManager.removeTextureFromCache(texture);
+      }
       if (this.memUsed <= memTarget) {
         // Stop once we've freed enough textures to reach under the target threshold
         break;

package/src/core/animations/CoreAnimation.ts

@@ -60,7 +60,8 @@ export class CoreAnimation extends EventEmitter {
           this.propValuesMap['props'] = {};
         }
         this.propValuesMap['props'][key] = {
-          start: node[key as keyof Omit<CoreNodeAnimateProps, 'shaderProps'>],
+          start:
+            node[key as keyof Omit<CoreNodeAnimateProps, 'shaderProps'>] || 0,
           target: props[
             key as keyof Omit<CoreNodeAnimateProps, 'shaderProps'>
           ] as number,

package/src/core/animations/CoreAnimationController.ts

@@ -119,6 +119,7 @@ export class CoreAnimationController
     const { loop, stopMethod } = this.animation.settings;
 
     if (stopMethod === 'reverse') {
+      this.animation.once('finished', this.onFinished);
       this.animation.reverse();
       return;
     }