[WIP] Text engine Refactor

README.md

@@ -98,11 +98,7 @@ and SDF fonts (SdfTrFontFace). Install that fonts that your applications needs
 at start up so they are ready when your application is rendered.
 
 ```ts
-import {
-  RendererMain,
-  WebTrFontFace,
-  SdfTrFontFace,
-} from '@lightningjs/renderer';
+import { RendererMain } from '@lightningjs/renderer';
 
 import {
   WebGlCoreRenderer,
@@ -121,27 +117,17 @@ const renderer = new RendererMain(
   'app', // id of div to insert Canvas.
 );
 
-// Load fonts into renderer
-renderer.stage.fontManager.addFontFace(
-  new WebTrFontFace('Ubuntu', {}, '/fonts/Ubuntu-Regular.ttf'),
-);
-
-renderer.stage.fontManager.addFontFace(
-  new SdfTrFontFace(
-    'Ubuntu',
-    {},
-    'msdf',
-    stage,
-    '/fonts/Ubuntu-Regular.msdf.png',
-    '/fonts/Ubuntu-Regular.msdf.json',
-  ),
-);
+// Load fonts by explicitly specifying the renderer type
+await stage.loadFont('canvas', {
+  fontFamily: 'myWebFont',
+  fontUrl: '/fonts/my-font.ttf',
+});
+
+await stage.loadFont('sdf', {
+  fontFamily: 'mySdfFont',
+  atlasUrl: '/fonts/my-font-atlas.png',
+  atlasDataUrl: '/fonts/my-font-data.json',
+});
 ```
 
-Please note that the WebGL renderer supports both SDF Fonts and Web Fonts, however the
-Canvas renderer only supports Web Fonts:
-
-| Font Type Renderer | SDF Font | Web Font |
-| ------------------ | -------- | -------- |
-| WebGL              | Y        | Y        |
-| Canvas             | N        | Y        |
+For more information see [Font Loading](./docs/fontLoading.md)

docs/fontLoading.md

@@ -0,0 +1,66 @@
+# Font Loading API Example
+
+This document demonstrates how to use the new font loading API on the Stage.
+
+## Basic Usage
+
+```typescript
+// Load Canvas fonts by explicitly specifying the renderer type
+await stage.loadFont('canvas', {
+  fontFamily: 'myCoolFont',
+  fontUrl: '/fonts/my-font.ttf',
+});
+
+// Load SDF fonts by explicitly specifying the renderer type
+await stage.loadFont('sdf', {
+  fontFamily: 'myCoolFont',
+  atlasUrl: '/fonts/my-font-atlas.png',
+  atlasDataUrl: '/fonts/my-font-data.json',
+});
+
+// Load fonts with custom metrics
+await stage.loadFont('canvas', {
+  fontFamily: 'MyFontWithMetrics',
+  fontUrl: '/fonts/my-font.ttf',
+  metrics: {
+    ascender: 800,
+    descender: -200,
+    lineGap: 0,
+    unitsPerEm: 1000,
+  },
+});
+```
+
+## API Requirements
+
+The `loadFont` method requires explicit renderer type specification:
+
+- **`rendererType`** (required): 'canvas' or 'sdf'
+- **`options`** (required): Font loading options specific to the renderer type
+
+### Canvas Font Options
+
+- `fontFamily`: Name of the font family
+- `fontUrl`: URL to the font file (.ttf, .woff, .woff2, etc.)
+- `metrics`: Optional font metrics for layout calculations
+
+### SDF Font Options
+
+- `fontFamily`: Name of the font family
+- `atlasUrl`: URL to the SDF atlas image (.png)
+- `atlasDataUrl`: URL to the SDF glyph data (.json)
+- `metrics`: Optional font metrics for layout calculations
+
+## Performance Considerations
+
+**SDF Fonts**: Better performance for scaled text and effects, but require pre-generated atlas files.
+
+**Canvas Fonts**: Universal compatibility with any web font format, but may have lower performance for complex scaling.
+
+Please note that the WebGL renderer supports both SDF Fonts and Web Fonts, however the
+Canvas renderer only supports Web Fonts:
+
+| Font Type Renderer | SDF Font | Web Font |
+| ------------------ | -------- | -------- |
+| WebGL              | Y        | Y        |
+| Canvas             | N        | Y        |

examples/common/constructTestRow.ts

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-import type { INode, RendererMain } from '@lightningjs/renderer';
+import type { INode, ITextNode, RendererMain } from '@lightningjs/renderer';
 import { waitForLoadedDimensions } from './utils.js';
 
 const CONTAINER_SIZE = 200;
@@ -35,7 +35,7 @@ export interface TestRowOptions {
 
 export async function constructTestRow(
   options: TestRowOptions,
-  testNodes: (INode | string)[],
+  testNodes: (INode | ITextNode | string)[],
 ): Promise<number> {
   const {
     renderer,

examples/common/installFonts.ts

@@ -17,120 +17,89 @@
  * limitations under the License.
  */
 
-import {
-  WebTrFontFace,
-  type Stage,
-  SdfTrFontFace,
-  type FontMetrics,
-} from '@lightningjs/renderer';
+import { type Stage } from '@lightningjs/renderer';
 
-export function installFonts(stage: Stage) {
-  stage.fontManager.addFontFace(
-    new WebTrFontFace({
-      fontFamily: 'NotoSans',
-      descriptors: {},
-      fontUrl: './fonts/NotoSans-Regular.ttf',
-      metrics: {
-        ascender: 1069,
-        descender: -293,
-        lineGap: 0,
-        unitsPerEm: 1000,
-      },
-    }),
-  );
+export async function installFonts(stage: Stage) {
+  // Load Canvas fonts using the new unified API
+  stage.loadFont('canvas', {
+    fontFamily: 'NotoSans',
+    fontUrl: './fonts/NotoSans-Regular.ttf',
+    metrics: {
+      ascender: 1069,
+      descender: -293,
+      lineGap: 0,
+      unitsPerEm: 1000,
+    },
+  });
 
-  stage.fontManager.addFontFace(
-    new WebTrFontFace({
-      fontFamily: 'Ubuntu',
-      descriptors: {},
-      fontUrl: './fonts/Ubuntu-Regular.ttf',
-      metrics: {
-        ascender: 776,
-        descender: -185,
-        lineGap: 56,
-        unitsPerEm: 1000,
-      },
-    }),
-  );
+  await stage.loadFont('canvas', {
+    fontFamily: 'Ubuntu',
+    fontUrl: './fonts/Ubuntu-Regular.ttf',
+    metrics: {
+      ascender: 776,
+      descender: -185,
+      lineGap: 56,
+      unitsPerEm: 1000,
+    },
+  });
 
-  stage.fontManager.addFontFace(
-    new WebTrFontFace({
-      fontFamily: 'Ubuntu-No-Metrics',
-      descriptors: {},
-      fontUrl: './fonts/Ubuntu-Regular.ttf',
-    }),
-  );
+  await stage.loadFont('canvas', {
+    fontFamily: 'Ubuntu-No-Metrics',
+    fontUrl: './fonts/Ubuntu-Regular.ttf',
+  });
 
-  const ubuntuModifiedMetrics: FontMetrics = {
+  const ubuntuModifiedMetrics = {
     ascender: 850,
     descender: -250,
     lineGap: 60,
     unitsPerEm: 1000,
   };
 
-  stage.fontManager.addFontFace(
-    new WebTrFontFace({
-      fontFamily: 'Ubuntu-Modified-Metrics',
-      descriptors: {},
-      fontUrl: './fonts/Ubuntu-Regular.ttf',
-      metrics: ubuntuModifiedMetrics,
-    }),
-  );
+  await stage.loadFont('canvas', {
+    fontFamily: 'Ubuntu-Modified-Metrics',
+    fontUrl: './fonts/Ubuntu-Regular.ttf',
+    metrics: ubuntuModifiedMetrics,
+  });
 
+  // Load SDF fonts for WebGL renderer using the new unified API
   if (stage.renderer.mode === 'webgl') {
-    stage.fontManager.addFontFace(
-      new SdfTrFontFace('ssdf', {
-        fontFamily: 'NotoSans',
-        descriptors: {},
-        atlasUrl: './fonts/NotoSans-Regular.ssdf.png',
-        atlasDataUrl: './fonts/NotoSans-Regular.ssdf.json',
-        stage,
-        metrics: {
-          ascender: 1000,
-          descender: -200,
-          lineGap: 0,
-          unitsPerEm: 1000,
-        },
-      }),
-    );
+    await stage.loadFont('sdf', {
+      fontFamily: 'NotoSans',
+      atlasUrl: './fonts/NotoSans-Regular.ssdf.png',
+      atlasDataUrl: './fonts/NotoSans-Regular.ssdf.json',
+      metrics: {
+        ascender: 1000,
+        descender: -200,
+        lineGap: 0,
+        unitsPerEm: 1000,
+      },
+    });
 
-    stage.fontManager.addFontFace(
-      new SdfTrFontFace('msdf', {
-        fontFamily: 'Ubuntu',
-        descriptors: {},
-        atlasUrl: './fonts/Ubuntu-Regular.msdf.png',
-        atlasDataUrl: './fonts/Ubuntu-Regular.msdf.json',
-        stage,
-        // Instead of suppling `metrics` this font will rely on the ones
-        // encoded in the json file under `lightningMetrics`.
-      }),
-    );
+    await stage.loadFont('sdf', {
+      fontFamily: 'Ubuntu',
+      atlasUrl: './fonts/Ubuntu-Regular.msdf.png',
+      atlasDataUrl: './fonts/Ubuntu-Regular.msdf.json',
+      // Instead of supplying `metrics` this font will rely on the ones
+      // encoded in the json file under `lightningMetrics`.
+    });
 
-    stage.fontManager.addFontFace(
-      new SdfTrFontFace('msdf', {
-        fontFamily: 'Ubuntu-Modified-Metrics',
-        descriptors: {},
-        atlasUrl: './fonts/Ubuntu-Regular.msdf.png',
-        atlasDataUrl: './fonts/Ubuntu-Regular.msdf.json',
-        stage,
-        metrics: ubuntuModifiedMetrics,
-      }),
-    );
+    await stage.loadFont('sdf', {
+      fontFamily: 'Ubuntu-Modified-Metrics',
+      atlasUrl: './fonts/Ubuntu-Regular.msdf.png',
+      atlasDataUrl: './fonts/Ubuntu-Regular.msdf.json',
+      metrics: ubuntuModifiedMetrics,
+    });
 
-    stage.fontManager.addFontFace(
-      new SdfTrFontFace('ssdf', {
-        fontFamily: 'Ubuntu-ssdf',
-        descriptors: {},
-        atlasUrl: './fonts/Ubuntu-Regular.ssdf.png',
-        atlasDataUrl: './fonts/Ubuntu-Regular.ssdf.json',
-        stage,
-        metrics: {
-          ascender: 776,
-          descender: -185,
-          lineGap: 56,
-          unitsPerEm: 1000,
-        },
-      }),
-    );
+    await stage.loadFont('sdf', {
+      fontFamily: 'Ubuntu-ssdf',
+      atlasUrl: './fonts/Ubuntu-Regular.ssdf.png',
+      atlasDataUrl: './fonts/Ubuntu-Regular.ssdf.json',
+      metrics: {
+        ascender: 776,
+        descender: -185,
+        lineGap: 56,
+        unitsPerEm: 1000,
+      },
+    });
   }
 }

examples/index.ts

@@ -259,7 +259,7 @@ async function initRenderer(
     'app',
   );
   await installShaders(renderer.stage, renderMode);
-  installFonts(renderer.stage);
+  await installFonts(renderer.stage);
 
   /**
    * Sample data captured

examples/tests/alpha-blending.ts

@@ -85,8 +85,7 @@ export default async function test(settings: ExampleSettings) {
     fontFamily: 'Ubuntu',
     fontSize: HEADER_FONT_SIZE,
     color: 0xffffffff,
-    contain: 'width',
-    width: renderer.settings.appWidth / 2,
+    maxWidth: renderer.settings.appWidth / 2,
     y: PADDING,
     textAlign: 'center',
     parent: testRoot,
@@ -97,8 +96,7 @@ export default async function test(settings: ExampleSettings) {
     fontFamily: 'Ubuntu',
     fontSize: HEADER_FONT_SIZE,
     color: 0xffffffff,
-    contain: 'width',
-    width: renderer.settings.appWidth / 2,
+    maxWidth: renderer.settings.appWidth / 2,
     x: renderer.settings.appWidth / 2,
     y: PADDING,
     textAlign: 'center',

examples/tests/render-settings.ts

@@ -51,8 +51,7 @@ export default async function test({ renderer, testRoot }: ExampleSettings) {
     fontFamily: 'Ubuntu-ssdf',
     x: 10,
     y: 810,
-    contain: 'width',
-    width: renderer.root.width - 20,
+    maxWidth: renderer.root.width - 20,
     parent: testRoot,
   });
 

examples/tests/stress-single-level-text.ts

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-import { type INode } from '@lightningjs/renderer';
+import { type INode, type ITextNode } from '@lightningjs/renderer';
 import type { ExampleSettings } from '../common/ExampleSettings.js';
 
 const randomIntBetween = (from: number, to: number) =>
@@ -30,7 +30,7 @@ export default async function ({
 }: ExampleSettings) {
   // create 100 nodes
   const numOuterNodes = 100 * perfMultiplier;
-  const nodes: INode[] = [];
+  const nodes: ITextNode[] = [];
 
   const startMin = -1000;
   const startMax = 3000;