@lightningjs/renderer 0.6.1 → 0.7.0

package/src/main-api/RendererMain.ts

@@ -211,6 +211,33 @@ export interface RendererMainSettings {
    * @defaultValue `0` (disabled)
    */
   fpsUpdateInterval?: 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;
 }
 
 /**
@@ -278,6 +305,9 @@ export class RendererMain extends EventEmitter {
         settings.experimental_FinalizationRegistryTextureUsageTracker ?? false,
       textureCleanupOptions: settings.textureCleanupOptions || {},
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+      numImageWorkers:
+        settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
+      enableContextSpy: settings.enableContextSpy ?? false,
     };
     this.settings = resolvedSettings;
 
@@ -335,8 +365,8 @@ export class RendererMain extends EventEmitter {
       this.nodes.delete(node.id);
     };
 
-    driver.onFpsUpdate = (fps) => {
-      this.emit('fpsUpdate', fps);
+    driver.onFpsUpdate = (fpsData) => {
+      this.emit('fpsUpdate', fpsData);
     };
 
     targetEl.appendChild(canvas);
@@ -389,11 +419,12 @@ export class RendererMain extends EventEmitter {
    * @returns
    */
   createTextNode(props: Partial<ITextNodeWritableProps>): ITextNode {
-    return this.driver.createTextNode({
+    const fontSize = props.fontSize ?? 16;
+    const data = {
       ...this.resolveNodeDefaults(props),
       text: props.text ?? '',
       textRendererOverride: props.textRendererOverride ?? null,
-      fontSize: props.fontSize ?? 16,
+      fontSize,
       fontFamily: props.fontFamily ?? 'sans-serif',
       fontStyle: props.fontStyle ?? 'normal',
       fontWeight: props.fontWeight ?? 'normal',
@@ -404,8 +435,15 @@ export class RendererMain extends EventEmitter {
       scrollY: props.scrollY ?? 0,
       offsetY: props.offsetY ?? 0,
       letterSpacing: props.letterSpacing ?? 0,
+      lineHeight: props.lineHeight ?? fontSize,
+      maxLines: props.maxLines ?? 0,
+      textBaseline: props.textBaseline ?? 'alphabetic',
+      verticalAlign: props.verticalAlign ?? 'top',
+      overflowSuffix: props.overflowSuffix ?? '...',
       debug: props.debug ?? {},
-    });
+    };
+
+    return this.driver.createTextNode(data);
   }
 
   /**

package/src/render-drivers/main/MainCoreDriver.ts

@@ -25,13 +25,14 @@ import type {
   ITextNodeWritableProps,
 } from '../../main-api/INode.js';
 import { MainOnlyNode, getNewId } from './MainOnlyNode.js';
-import { Stage } from '../../core/Stage.js';
+import { Stage, type StageFpsUpdateHandler } from '../../core/Stage.js';
 import type {
   RendererMain,
   RendererMainSettings,
 } from '../../main-api/RendererMain.js';
 import { MainOnlyTextNode } from './MainOnlyTextNode.js';
 import { loadCoreExtension } from '../utils.js';
+import type { FpsUpdatePayload } from '../../common/CommonTypes.js';
 
 export class MainCoreDriver implements ICoreDriver {
   private root: MainOnlyNode | null = null;
@@ -52,6 +53,8 @@ export class MainCoreDriver implements ICoreDriver {
       clearColor: rendererSettings.clearColor,
       canvas,
       fpsUpdateInterval: rendererSettings.fpsUpdateInterval,
+      enableContextSpy: rendererSettings.enableContextSpy,
+      numImageWorkers: rendererSettings.numImageWorkers,
       debug: {
         monitorTextureCache: false,
       },
@@ -74,9 +77,9 @@ export class MainCoreDriver implements ICoreDriver {
     }
 
     // Forward fpsUpdate events from the stage to RendererMain
-    this.stage.on('fpsUpdate', (stage: Stage, fps: number) => {
-      this.onFpsUpdate(fps);
-    });
+    this.stage.on('fpsUpdate', ((stage, fpsData) => {
+      this.onFpsUpdate(fpsData);
+    }) satisfies StageFpsUpdateHandler);
   }
 
   createNode(props: INodeWritableProps): INode {
@@ -123,7 +126,7 @@ export class MainCoreDriver implements ICoreDriver {
     throw new Error('Method not implemented.');
   }
 
-  onFpsUpdate(fps: number) {
+  onFpsUpdate(fpsData: FpsUpdatePayload) {
     throw new Error('Method not implemented.');
   }
   //#endregion

package/src/render-drivers/main/MainOnlyTextNode.ts

@@ -81,8 +81,12 @@ export class MainOnlyTextNode extends MainOnlyNode implements ITextNode {
         scrollY: props.scrollY,
         offsetY: props.offsetY,
         textRendererOverride: props.textRendererOverride,
+        lineHeight: props.lineHeight,
+        maxLines: props.maxLines,
+        textBaseline: props.textBaseline,
+        verticalAlign: props.verticalAlign,
+        overflowSuffix: props.overflowSuffix,
         debug: props.debug,
-
         // These properties will get set appropriately in the base MainOnlyNode class
         parent: null,
         texture: null,
@@ -197,6 +201,56 @@ export class MainOnlyTextNode extends MainOnlyNode implements ITextNode {
     this.coreNode.letterSpacing = value;
   }
 
+  get lineHeight(): ITextNode['lineHeight'] {
+    return this.coreNode.lineHeight;
+  }
+
+  set lineHeight(value: ITextNode['lineHeight']) {
+    if (value) {
+      this.coreNode.lineHeight = value;
+    }
+  }
+
+  get maxLines(): ITextNode['maxLines'] {
+    return this.coreNode.maxLines;
+  }
+
+  set maxLines(value: ITextNode['maxLines']) {
+    if (value) {
+      this.coreNode.maxLines = value;
+    }
+  }
+
+  get textBaseline(): ITextNode['textBaseline'] {
+    return this.coreNode.textBaseline;
+  }
+
+  set textBaseline(value: ITextNode['textBaseline']) {
+    if (value) {
+      this.coreNode.textBaseline = value;
+    }
+  }
+
+  get verticalAlign(): ITextNode['verticalAlign'] {
+    return this.coreNode.verticalAlign;
+  }
+
+  set verticalAlign(value: ITextNode['verticalAlign']) {
+    if (value) {
+      this.coreNode.verticalAlign = value;
+    }
+  }
+
+  get overflowSuffix(): ITextNode['overflowSuffix'] {
+    return this.coreNode.overflowSuffix;
+  }
+
+  set overflowSuffix(value: ITextNode['overflowSuffix']) {
+    if (value) {
+      this.coreNode.overflowSuffix = value;
+    }
+  }
+
   get debug(): ITextNode['debug'] {
     return this.coreNode.debug;
   }

package/src/render-drivers/threadx/TextNodeStruct.ts

@@ -163,4 +163,49 @@ export class TextNodeStruct
   set letterSpacing(value: TextNodeStructWritableProps['letterSpacing']) {
     // Decorator will handle this
   }
+
+  @structProp('number')
+  get lineHeight(): TextNodeStructWritableProps['lineHeight'] {
+    return 0;
+  }
+
+  set lineHeight(value: TextNodeStructWritableProps['lineHeight']) {
+    // Decorator will handle this
+  }
+
+  @structProp('number')
+  get maxLines(): TextNodeStructWritableProps['maxLines'] {
+    return 0;
+  }
+
+  set maxLines(value: TextNodeStructWritableProps['maxLines']) {
+    // Decorator will handle this
+  }
+
+  @structProp('string')
+  get textBaseline(): TextNodeStructWritableProps['textBaseline'] {
+    return 'alphabetic';
+  }
+
+  set textBaseline(value: TextNodeStructWritableProps['textBaseline']) {
+    // Decorator will handle this
+  }
+
+  @structProp('string')
+  get verticalAlign(): TextNodeStructWritableProps['verticalAlign'] {
+    return 'middle';
+  }
+
+  set verticalAlign(value: TextNodeStructWritableProps['verticalAlign']) {
+    // Decorator will handle this
+  }
+
+  @structProp('string')
+  get overflowSuffix(): TextNodeStructWritableProps['overflowSuffix'] {
+    return '...';
+  }
+
+  set overflowSuffix(value: TextNodeStructWritableProps['overflowSuffix']) {
+    // Decorator will handle this
+  }
 }

package/src/render-drivers/threadx/ThreadXCoreDriver.ts

@@ -42,6 +42,7 @@ import {
   type TextNodeStructWritableProps,
 } from './TextNodeStruct.js';
 import { ThreadXMainTextNode } from './ThreadXMainTextNode.js';
+import type { FpsUpdatePayload } from '../../common/CommonTypes.js';
 
 export interface ThreadXRendererSettings {
   coreWorkerUrl: string;
@@ -79,7 +80,7 @@ export class ThreadXCoreDriver implements ICoreDriver {
       onMessage: async (message) => {
         // Forward fpsUpdate events from the renderer worker's Stage to RendererMain
         if (isThreadXRendererMessage('fpsUpdate', message)) {
-          this.onFpsUpdate(message.fps);
+          this.onFpsUpdate(message.fpsData);
         }
       },
     });
@@ -108,6 +109,8 @@ export class ThreadXCoreDriver implements ICoreDriver {
         clearColor: rendererSettings.clearColor,
         coreExtensionModule: rendererSettings.coreExtensionModule,
         fpsUpdateInterval: rendererSettings.fpsUpdateInterval,
+        enableContextSpy: rendererSettings.enableContextSpy,
+        numImageWorkers: rendererSettings.numImageWorkers,
       } satisfies ThreadXRendererInitMessage,
       [offscreenCanvas],
     )) as number;
@@ -215,8 +218,13 @@ export class ThreadXCoreDriver implements ICoreDriver {
       fontWeight: props.fontWeight,
       fontStretch: props.fontStretch,
       fontStyle: props.fontStyle,
+      lineHeight: props.lineHeight,
+      maxLines: props.maxLines,
+      textBaseline: props.textBaseline,
+      verticalAlign: props.verticalAlign,
       contain: props.contain,
       letterSpacing: props.letterSpacing,
+      overflowSuffix: props.overflowSuffix,
       offsetY: props.offsetY,
       textAlign: props.textAlign,
       scrollable: props.scrollable,
@@ -258,7 +266,7 @@ export class ThreadXCoreDriver implements ICoreDriver {
     throw new Error('Method not implemented.');
   }
 
-  onFpsUpdate(fps: number): void {
+  onFpsUpdate(fps: FpsUpdatePayload): void {
     throw new Error('Method not implemented.');
   }
   //#endregion

package/src/render-drivers/threadx/ThreadXMainTextNode.ts

@@ -38,12 +38,17 @@ export class ThreadXMainTextNode extends ThreadXMainNode implements ITextNode {
       fontStretch: sharedNodeStruct.fontStretch,
       fontStyle: sharedNodeStruct.fontStyle,
       fontWeight: sharedNodeStruct.fontWeight,
+      lineHeight: sharedNodeStruct.lineHeight,
+      maxLines: sharedNodeStruct.maxLines,
+      textBaseline: sharedNodeStruct.textBaseline,
+      verticalAlign: sharedNodeStruct.verticalAlign,
       contain: sharedNodeStruct.contain,
       letterSpacing: sharedNodeStruct.letterSpacing,
       offsetY: sharedNodeStruct.offsetY,
       scrollable: sharedNodeStruct.scrollable,
       scrollY: sharedNodeStruct.scrollY,
       textAlign: sharedNodeStruct.textAlign,
+      overflowSuffix: sharedNodeStruct.overflowSuffix,
     } satisfies Omit<TextNodeStructWritableProps, keyof NodeStructWritableProps>);
   }
 
@@ -54,12 +59,17 @@ export class ThreadXMainTextNode extends ThreadXMainNode implements ITextNode {
   declare fontStretch: ITextNode['fontStretch'];
   declare fontStyle: ITextNode['fontStyle'];
   declare fontWeight: ITextNode['fontWeight'];
+  declare lineHeight: ITextNode['lineHeight'];
+  declare maxLines: ITextNode['maxLines'];
+  declare textBaseline: ITextNode['textBaseline'];
+  declare verticalAlign: ITextNode['verticalAlign'];
   declare textAlign: ITextNode['textAlign'];
   declare contain: ITextNode['contain'];
   declare scrollable: ITextNode['scrollable'];
   declare scrollY: ITextNode['scrollY'];
   declare offsetY: ITextNode['offsetY'];
   declare letterSpacing: ITextNode['letterSpacing'];
+  declare overflowSuffix: ITextNode['overflowSuffix'];
 
   get debug(): ITextNode['debug'] {
     return this._debug;

package/src/render-drivers/threadx/ThreadXRendererMessage.ts

@@ -17,6 +17,8 @@
  * limitations under the License.
  */
 
+import type { FpsUpdatePayload } from '../../common/CommonTypes.js';
+
 /**
  * @module
  * @description
@@ -43,6 +45,8 @@ export interface ThreadXRendererInitMessage extends ThreadXRendererMessage {
   devicePhysicalPixelRatio: number;
   clearColor: number;
   fpsUpdateInterval: number;
+  enableContextSpy: boolean;
+  numImageWorkers: number;
   coreExtensionModule: string | null;
 }
 
@@ -62,7 +66,7 @@ export interface ThreadXRendererReleaseTextureMessage
 export interface ThreadXRendererFpsUpdateMessage
   extends ThreadXRendererMessage {
   type: 'fpsUpdate';
-  fps: number;
+  fpsData: FpsUpdatePayload;
 }
 
 /**

package/src/render-drivers/threadx/worker/ThreadXRendererTextNode.ts

@@ -85,6 +85,11 @@ export class ThreadXRendererTextNode extends ThreadXRendererNode {
         fontWeight: sharedNodeStruct.fontWeight,
         fontStretch: sharedNodeStruct.fontStretch,
         fontStyle: sharedNodeStruct.fontStyle,
+        lineHeight: sharedNodeStruct.lineHeight,
+        maxLines: sharedNodeStruct.maxLines,
+        textBaseline: sharedNodeStruct.textBaseline,
+        verticalAlign: sharedNodeStruct.verticalAlign,
+        overflowSuffix: sharedNodeStruct.overflowSuffix,
         contain: sharedNodeStruct.contain,
         letterSpacing: sharedNodeStruct.letterSpacing,
         offsetY: sharedNodeStruct.offsetY,
@@ -101,6 +106,11 @@ export class ThreadXRendererTextNode extends ThreadXRendererNode {
         fontWeight: sharedNodeStruct.fontWeight,
         fontStretch: sharedNodeStruct.fontStretch,
         fontStyle: sharedNodeStruct.fontStyle,
+        lineHeight: sharedNodeStruct.lineHeight,
+        maxLines: sharedNodeStruct.maxLines,
+        textBaseline: sharedNodeStruct.textBaseline,
+        verticalAlign: sharedNodeStruct.verticalAlign,
+        overflowSuffix: sharedNodeStruct.overflowSuffix,
         contain: sharedNodeStruct.contain,
         letterSpacing: sharedNodeStruct.letterSpacing,
         offsetY: sharedNodeStruct.offsetY,
@@ -125,6 +135,11 @@ export class ThreadXRendererTextNode extends ThreadXRendererNode {
   declare fontWeight: TextNodeStructWritableProps['fontWeight'];
   declare fontStretch: TextNodeStructWritableProps['fontStretch'];
   declare fontStyle: TextNodeStructWritableProps['fontStyle'];
+  declare lineHeight: TextNodeStructWritableProps['lineHeight'];
+  declare maxLines: TextNodeStructWritableProps['maxLines'];
+  declare textBaseline: TextNodeStructWritableProps['textBaseline'];
+  declare verticalAlign: TextNodeStructWritableProps['verticalAlign'];
+  declare overflowSuffix: TextNodeStructWritableProps['overflowSuffix'];
   declare contain: TextNodeStructWritableProps['contain'];
   declare letterSpacing: TextNodeStructWritableProps['letterSpacing'];
   declare offsetY: TextNodeStructWritableProps['offsetY'];

package/src/render-drivers/threadx/worker/renderer.ts

@@ -20,7 +20,7 @@
 import { ThreadX, BufferStruct } from '@lightningjs/threadx';
 import { NodeStruct, type NodeStructWritableProps } from '../NodeStruct.js';
 import { ThreadXRendererNode } from './ThreadXRendererNode.js';
-import { Stage } from '../../../core/Stage.js';
+import { Stage, type StageFpsUpdateHandler } from '../../../core/Stage.js';
 import { assertTruthy } from '../../../utils.js';
 import {
   isThreadXRendererMessage,
@@ -71,6 +71,8 @@ const threadx = ThreadX.init({
         clearColor: message.clearColor,
         canvas,
         fpsUpdateInterval: message.fpsUpdateInterval,
+        enableContextSpy: message.enableContextSpy,
+        numImageWorkers: message.numImageWorkers,
         debug: {
           monitorTextureCache: false,
         },
@@ -120,12 +122,12 @@ const threadx = ThreadX.init({
       }
 
       // Forward FPS updates to the main worker.
-      stage.on('fpsUpdate', (stage: Stage, fps: number) => {
+      stage.on('fpsUpdate', ((stage, fpsData) => {
         threadx.sendMessage('parent', {
           type: 'fpsUpdate',
-          fps,
+          fpsData: fpsData,
         } satisfies ThreadXRendererFpsUpdateMessage);
-      });
+      }) satisfies StageFpsUpdateHandler);
 
       // Return its ID so the main worker can retrieve it from the shared object
       // store.

package/src/utils.ts

@@ -17,9 +17,12 @@
  * limitations under the License.
  */
 
+import type { ContextSpy } from './core/lib/ContextSpy.js';
+
 export function createWebGLContext(
   canvas: HTMLCanvasElement | OffscreenCanvas,
-): WebGLRenderingContext | null {
+  contextSpy: ContextSpy | null,
+): WebGLRenderingContext {
   const config: WebGLContextAttributes = {
     alpha: true,
     antialias: false,
@@ -32,15 +35,32 @@ export function createWebGLContext(
     premultipliedAlpha: true,
     preserveDrawingBuffer: false,
   };
-  return (
+  const gl =
     // TODO: Remove this assertion once this issue is fixed in TypeScript
     // https://github.com/microsoft/TypeScript/issues/53614
     (canvas.getContext('webgl', config) ||
       canvas.getContext(
         'experimental-webgl' as 'webgl',
         config,
-      )) as unknown as WebGLRenderingContext | null
-  );
+      )) as unknown as WebGLRenderingContext | null;
+  if (!gl) {
+    throw new Error('Unable to create WebGL context');
+  }
+  if (contextSpy) {
+    // Proxy the GL context to log all GL calls
+    return new Proxy(gl, {
+      get(target, prop) {
+        const value = target[prop as never] as unknown;
+        if (typeof value === 'function') {
+          contextSpy.increment(String(prop));
+          return value.bind(target);
+        }
+        return value;
+      },
+    });
+  }
+
+  return gl;
 }
 
 /**
@@ -59,6 +79,7 @@ export function assertTruthy(
   condition: unknown,
   message?: string,
 ): asserts condition {
+  if (import.meta.env.PROD) return;
   if (!condition) {
     throw new Error(message || 'Assertion failed');
   }

package/src/core/text-rendering/renderers/SdfTextRenderer/internal/makeRenderWindow.test.ts

@@ -1,136 +0,0 @@
-/*
- * 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 { expect, describe, it } from 'vitest';
-import { makeRenderWindow } from './makeRenderWindow.js';
-
-describe('makeRenderWindow', () => {
-  it('should return a empty window when all inputs are zero / empty', () => {
-    expect(
-      makeRenderWindow(0, 0, 0, 0, 0, { x1: 0, y1: 0, x2: 0, y2: 0 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 0,
-      y2: 0,
-    });
-    // Visible window is empty
-    expect(
-      makeRenderWindow(0, 0, 0, 0, 0, { x1: 100, y1: 100, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 0,
-      y2: 0,
-    });
-  });
-
-  it('should return an empty window when the visible window is empty regardless of other inputs', () => {
-    expect(
-      makeRenderWindow(100, 200, 300, 10, 3, { x1: 0, y1: 0, x2: 0, y2: 0 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 0,
-      y2: 0,
-    });
-    expect(
-      makeRenderWindow(400, 500, 100, 20, 2, {
-        x1: 100,
-        y1: 100,
-        x2: 100,
-        y2: 100,
-      }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 0,
-      y2: 0,
-    });
-  });
-
-  it('should return a window with no margin around the visible area if lineHeight and/or numExtraLines set are zero', () => {
-    expect(
-      makeRenderWindow(0, 0, 0, 0, 0, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 100,
-      y2: 100,
-    });
-
-    expect(
-      makeRenderWindow(0, 0, 0, 10, 0, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 100,
-      y2: 100,
-    });
-
-    expect(
-      makeRenderWindow(0, 0, 0, 0, 2, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 0,
-      x2: 100,
-      y2: 100,
-    });
-  });
-
-  it('should return a window with a margin around the visible area (if lineHeight/numExtraLines set)', () => {
-    expect(
-      makeRenderWindow(0, 0, 0, 10, 1, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: -10,
-      x2: 100,
-      y2: 110,
-    });
-
-    expect(
-      makeRenderWindow(0, 0, 0, 5, 3, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: -15,
-      x2: 100,
-      y2: 115,
-    });
-  });
-
-  it('should return a window scrolled to scrollY when set', () => {
-    expect(
-      makeRenderWindow(0, 0, 100, 10, 1, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 90,
-      x2: 100,
-      y2: 210,
-    });
-
-    expect(
-      makeRenderWindow(0, 0, 200, 10, 1, { x1: 0, y1: 0, x2: 100, y2: 100 }),
-    ).toEqual({
-      x1: 0,
-      y1: 190,
-      x2: 100,
-      y2: 310,
-    });
-  });
-});