@lightningjs/renderer 0.8.3 → 0.9.0

package/src/core/text-rendering/font-face-types/TrFontFace.ts

@@ -64,13 +64,98 @@ export interface TrFontFaceDescriptors {
   variant?: string;
 }
 
+export interface FontMetrics {
+  /**
+   * The distance, in font units, from the baseline to the highest point of the font.
+   */
+  ascender: number;
+  /**
+   * The distance, in font units, from the baseline to the lowest point of the font.
+   */
+  descender: number;
+  /**
+   * The additional space used in the calculation of the default line height in font units.
+   */
+  lineGap: number;
+  /**
+   * The number of font units per 1 EM.
+   */
+  unitsPerEm: number;
+}
+
+export interface NormalizedFontMetrics {
+  /**
+   * The distance, as a fraction of 1 EM, from the baseline to the highest point of the font.
+   *
+   * @remarks
+   * This value should be positive.
+   */
+  ascender: number;
+  /**
+   * The distance, as a fraction of 1 EM, from the baseline to the lowest point of the font.
+   *
+   * @remarks
+   * This value should be positive.
+   */
+  descender: number;
+  /**
+   * The additional space used in the calculation of the default line height as a fraction of 1 EM
+   *
+   * @remarks
+   * This value should be positive.
+   */
+  lineGap: number;
+}
+
+export interface TrFontFaceOptions {
+  fontFamily: string;
+  descriptors: Partial<TrFontFaceDescriptors>;
+  /**
+   * Font metrics used for layout and default line height calculations.
+   *
+   * @remarks
+   * Provides the font metrics in order to ensure consistent text layout across
+   * different font types (Canvas/Web, SDF, etc.).
+   *
+   * **Important**: We HIGHLY recommend providing these metrics for both SDF
+   * and Web/Canvas fonts. You can use the Lightning 3 [msdf-generator](https://github.com/lightning-js/msdf-generator/)
+   * tool to generate these metrics from a font file. The metrics generated by
+   * this tool can be used with both SDF and Web/Canvas fonts.
+   *
+   * If not provided, a warning will be logged and the text layout may not be
+   * consistent across different font types.
+   *
+   * If not provided, the metrics will be gathered depending on the font type.
+   * - For SDF fonts, the metrics will be gathered from the font atlas data.
+   *   If the font is generated using Lightning 3's msdf-generator tool, the
+   *   metrics will be the most accurate.
+   * - For Web/Canvas fonts, the metrics will be gathered from the
+   *   CanvasRenderingContext2D.measureText() method. The accuracy/consistency
+   *   of these metrics depends on the browser implementation. And will not
+   *   guarantee the line-by-line alignment of text with SDF fonts.
+   */
+  metrics?: FontMetrics;
+}
+
 export class TrFontFace extends EventEmitter {
   public readonly fontFamily: string;
   public readonly descriptors: TrFontFaceDescriptors;
   public readonly loaded: boolean = false;
+  public readonly metrics: NormalizedFontMetrics | null = null;
 
-  constructor(fontFamily: string, descriptors: Partial<TrFontFaceDescriptors>) {
+  constructor(options: TrFontFaceOptions) {
     super();
+    const { fontFamily, descriptors, metrics } = options;
+
+    if (metrics) {
+      // Normalize metrics to be in the range of 0 to 1
+      this.metrics = {
+        ascender: metrics.ascender / metrics.unitsPerEm,
+        descender: metrics.descender / metrics.unitsPerEm,
+        lineGap: metrics.lineGap / metrics.unitsPerEm,
+      };
+    }
+
     this.fontFamily = fontFamily;
     this.descriptors = {
       style: 'normal',

package/src/core/text-rendering/font-face-types/WebTrFontFace.ts

@@ -17,7 +17,11 @@
  * limitations under the License.
  */
 
-import { TrFontFace, type TrFontFaceDescriptors } from './TrFontFace.js';
+import {
+  TrFontFace,
+  type TrFontFaceDescriptors,
+  type TrFontFaceOptions,
+} from './TrFontFace.js';
 
 declare module './TrFontFace.js' {
   interface TrFontFaceMap {
@@ -25,16 +29,18 @@ declare module './TrFontFace.js' {
   }
 }
 
+export interface WebTrFontFaceOptions extends TrFontFaceOptions {
+  fontUrl: string;
+}
+
 export class WebTrFontFace extends TrFontFace {
   public readonly fontFace: FontFace;
   public readonly fontUrl: string;
 
-  constructor(
-    fontFamily: string,
-    descriptors: Partial<TrFontFaceDescriptors>,
-    fontUrl: string,
-  ) {
-    super(fontFamily, descriptors);
+  constructor(options: WebTrFontFaceOptions) {
+    super(options);
+
+    const { fontFamily, fontUrl } = options;
 
     // Filter out parentheses from fontUrl
     const fontUrlWithoutParentheses = fontUrl.replace(/\(|\)/g, '');

package/src/core/text-rendering/renderers/CanvasTextRenderer.ts

@@ -33,6 +33,7 @@ import {
   type RectWithValid,
 } from '../../lib/utils.js';
 import type { ImageTexture } from '../../textures/ImageTexture.js';
+import { TrFontManager, type FontFamilyMap } from '../TrFontManager.js';
 import type { TrFontFace } from '../font-face-types/TrFontFace.js';
 import { WebTrFontFace } from '../font-face-types/WebTrFontFace.js';
 import {
@@ -81,6 +82,7 @@ export interface CanvasTextRendererState extends TextRendererState {
   fontFaceLoadedHandler: (() => void) | undefined;
   fontInfo:
     | {
+        fontFace: WebTrFontFace;
         cssString: string;
         loaded: boolean;
       }
@@ -107,6 +109,12 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
     | OffscreenCanvasRenderingContext2D
     | CanvasRenderingContext2D;
   private rendererBounds: Bound;
+  /**
+   * Font family map used to store web font faces that were added to the
+   * canvas text renderer.
+   */
+  private fontFamilies: FontFamilyMap = {};
+  private fontFamilyArray: FontFamilyMap[] = [this.fontFamilies];
 
   constructor(stage: Stage) {
     super(stage);
@@ -135,6 +143,14 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
       x2: this.stage.options.appWidth,
       y2: this.stage.options.appHeight,
     };
+    // Install the default 'san-serif' font face
+    this.addFontFace(
+      new WebTrFontFace({
+        fontFamily: 'sans-serif',
+        descriptors: {},
+        fontUrl: '',
+      }),
+    );
   }
 
   //#region Overrides
@@ -259,10 +275,25 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
     // the `isFontFaceSupported` check)
     assertTruthy(fontFace instanceof WebTrFontFace);
 
-    // We simply add the font face to the document
-    // @ts-expect-error `add()` method should be available from a FontFaceSet
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-    globalFontSet.add(fontFace.fontFace);
+    // Add the font face to the document
+    // Except for the 'sans-serif' font family, which the Renderer provides
+    // as a special default fallback.
+    if (fontFace.fontFamily !== 'sans-serif') {
+      // @ts-expect-error `add()` method should be available from a FontFaceSet
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      globalFontSet.add(fontFace.fontFace);
+    }
+
+    const { fontFamilies } = this;
+    const familyName = fontFace.fontFace.family;
+
+    let faceSet = fontFamilies[familyName];
+    if (!faceSet) {
+      faceSet = new Set();
+      fontFamilies[familyName] = faceSet;
+    }
+
+    faceSet.add(fontFace);
   }
 
   override createState(props: TrProps): CanvasTextRendererState {
@@ -312,7 +343,13 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
     // If fontInfo is invalid, we need to establish it
     if (!state.fontInfo) {
       const cssString = getFontCssString(state.props);
+      const trFontFace = TrFontManager.resolveFontFace(
+        this.fontFamilyArray,
+        state.props,
+      ) as WebTrFontFace | undefined;
+      assertTruthy(trFontFace, `Could not resolve font face for ${cssString}`);
       state.fontInfo = {
+        fontFace: trFontFace,
         cssString: cssString,
         // TODO: For efficiency we would use this here but it's not reliable on WPE -> document.fonts.check(cssString),
         loaded: false,
@@ -333,22 +370,11 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
     }
 
     if (!state.renderInfo) {
-      const maxLines = state.props.maxLines;
-      const containedMaxLines =
-        state.props.contain === 'both'
-          ? Math.floor(
-              (state.props.height - state.props.offsetY) /
-                state.props.lineHeight,
-            )
-          : 0;
-      const calcMaxLines =
-        containedMaxLines > 0 && maxLines > 0
-          ? Math.min(containedMaxLines, maxLines)
-          : Math.max(containedMaxLines, maxLines);
       state.lightning2TextRenderer.settings = {
         text: state.props.text,
         textAlign: state.props.textAlign,
-        fontFace: state.props.fontFamily,
+        fontFamily: state.props.fontFamily,
+        trFontFace: state.fontInfo.fontFace,
         fontSize: state.props.fontSize,
         fontStyle: [
           state.props.fontStretch,
@@ -356,16 +382,21 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
           state.props.fontWeight,
         ].join(' '),
         textColor: getNormalizedRgbaComponents(state.props.color),
-        offsetY: state.props.fontSize + state.props.offsetY,
+        offsetY: state.props.offsetY,
         wordWrap: state.props.contain !== 'none',
         wordWrapWidth:
           state.props.contain === 'none' ? undefined : state.props.width,
         letterSpacing: state.props.letterSpacing,
-        lineHeight: state.props.lineHeight,
-        maxLines: calcMaxLines,
+        lineHeight: state.props.lineHeight ?? null,
+        maxLines: state.props.maxLines,
+        maxHeight:
+          state.props.contain === 'both'
+            ? state.props.height - state.props.offsetY
+            : null,
         textBaseline: state.props.textBaseline,
         verticalAlign: state.props.verticalAlign,
         overflowSuffix: state.props.overflowSuffix,
+        w: state.props.contain !== 'none' ? state.props.width : undefined,
       };
       // const renderInfoCalculateTime = performance.now();
       state.renderInfo = state.lightning2TextRenderer.calculateRenderInfo();
@@ -712,6 +743,7 @@ export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
   }
 
   override destroyState(state: CanvasTextRendererState): void {
+    super.destroyState(state);
     // Remove state object owner from any canvas page textures
     state.canvasPages?.forEach((pageInfo) => {
       pageInfo.texture?.setRenderableOwner(state, false);

package/src/core/text-rendering/renderers/LightningTextTextureRenderer.ts

@@ -19,7 +19,12 @@
 
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 
+import { assertTruthy } from '../../../utils.js';
 import { getRgbaString, type RGBA } from '../../lib/utils.js';
+import { calcDefaultLineHeight } from '../TextRenderingUtils.js';
+import { getWebFontMetrics } from '../TextTextureRendererUtils.js';
+import type { NormalizedFontMetrics } from '../font-face-types/TrFontFace.js';
+import type { WebTrFontFace } from '../font-face-types/WebTrFontFace.js';
 
 const MAX_TEXTURE_DIMENSION = 2048;
 
@@ -62,7 +67,8 @@ export interface Settings {
   fontStyle: string;
   fontSize: number;
   fontBaselineRatio: number;
-  fontFace: string | null;
+  fontFamily: string | null;
+  trFontFace: WebTrFontFace | null;
   wordWrap: boolean;
   wordWrapWidth: number;
   wordBreak: boolean;
@@ -73,6 +79,7 @@ export interface Settings {
   verticalAlign: TextVerticalAlign;
   offsetY: number | null;
   maxLines: number;
+  maxHeight: number | null;
   overflowSuffix: string;
   precision: number;
   textColor: RGBA;
@@ -117,12 +124,14 @@ export interface RenderInfo {
   cutEx: number;
   cutEy: number;
   lineHeight: number;
+  defLineHeight: number;
   lineWidths: number[];
   offsetY: number;
   paddingLeft: number;
   paddingRight: number;
   letterSpacing: number;
   textIndent: number;
+  metrics: NormalizedFontMetrics;
 }
 
 /**
@@ -186,7 +195,7 @@ export class LightningTextTextureRenderer {
   }
 
   _getFontSetting() {
-    const ff = [this._settings.fontFace];
+    const ff = [this._settings.fontFamily];
 
     const ffs = [];
     for (let i = 0, n = ff.length; i < n; i++) {
@@ -238,7 +247,6 @@ export class LightningTextTextureRenderer {
       this._settings.offsetY === null
         ? null
         : this._settings.offsetY * precision;
-    let lineHeight = (this._settings.lineHeight || fontSize) * precision;
     const w = this._settings.w * precision;
     const h = this._settings.h * precision;
     let wordWrapWidth = this._settings.wordWrapWidth * precision;
@@ -248,10 +256,31 @@ export class LightningTextTextureRenderer {
     const cutEy = this._settings.cutEy * precision;
     const letterSpacing = (this._settings.letterSpacing || 0) * precision;
     const textIndent = this._settings.textIndent * precision;
+    const trFontFace = this._settings.trFontFace;
 
     // Set font properties.
     this.setFontProperties();
 
+    assertTruthy(trFontFace);
+    const metrics = getWebFontMetrics(this._context, trFontFace, fontSize);
+    const defLineHeight = calcDefaultLineHeight(metrics, fontSize) * precision;
+    const lineHeight =
+      this._settings.lineHeight !== null
+        ? this._settings.lineHeight * precision
+        : defLineHeight;
+
+    const maxHeight = this._settings.maxHeight;
+    const containedMaxLines =
+      maxHeight !== null && lineHeight > 0
+        ? Math.floor(maxHeight / lineHeight)
+        : 0;
+
+    const setMaxLines = this._settings.maxLines;
+    const calcMaxLines =
+      containedMaxLines > 0 && setMaxLines > 0
+        ? Math.min(containedMaxLines, setMaxLines)
+        : Math.max(containedMaxLines, setMaxLines);
+
     // Total width.
     let width = w || 2048 / this.getPrecision();
 
@@ -305,8 +334,8 @@ export class LightningTextTextureRenderer {
     }
     let lines = linesInfo.l;
 
-    if (this._settings.maxLines && lines.length > this._settings.maxLines) {
-      const usedLines = lines.slice(0, this._settings.maxLines);
+    if (calcMaxLines && lines.length > calcMaxLines) {
+      const usedLines = lines.slice(0, calcMaxLines);
 
       let otherLines = null;
       if (this._settings.overflowSuffix) {
@@ -333,7 +362,7 @@ export class LightningTextTextureRenderer {
       const n = lines.length;
       let j = 0;
       const m = linesInfo.n.length;
-      for (i = this._settings.maxLines; i < n; i++) {
+      for (i = calcMaxLines; i < n; i++) {
         otherLines[j] += `${otherLines[j] ? ' ' : ''}${lines[i]!}`;
         if (i + 1 < m && linesInfo.n[i + 1]) {
           j++;
@@ -368,9 +397,6 @@ export class LightningTextTextureRenderer {
       innerWidth = maxLineWidth;
     }
 
-    // calculate text height
-    lineHeight = lineHeight || fontSize;
-
     let height;
     if (h) {
       height = h;
@@ -420,12 +446,14 @@ export class LightningTextTextureRenderer {
     renderInfo.cutEx = cutEx;
     renderInfo.cutEy = cutEy;
     renderInfo.lineHeight = lineHeight;
+    renderInfo.defLineHeight = defLineHeight;
     renderInfo.lineWidths = lineWidths;
     renderInfo.offsetY = offsetY;
     renderInfo.paddingLeft = paddingLeft;
     renderInfo.paddingRight = paddingRight;
     renderInfo.letterSpacing = letterSpacing;
     renderInfo.textIndent = textIndent;
+    renderInfo.metrics = metrics;
 
     return renderInfo as RenderInfo;
   }
@@ -477,17 +505,33 @@ export class LightningTextTextureRenderer {
 
     const drawLines = [];
 
+    const { metrics } = renderInfo;
+
+    /**
+     * Ascender (in pixels)
+     */
+    const ascenderPx = metrics
+      ? metrics.ascender * renderInfo.fontSize
+      : renderInfo.fontSize;
+
+    /**
+     * Bare line height is the distance between the ascender and descender of the font.
+     * without the line gap metric.
+     */
+    const bareLineHeightPx =
+      (metrics.ascender - metrics.descender) * renderInfo.fontSize;
+
     // Draw lines line by line.
     for (let i = 0, n = lines.length; i < n; i++) {
       linePositionX = i === 0 ? renderInfo.textIndent : 0;
 
       // By default, text is aligned to top
-      linePositionY = i * renderInfo.lineHeight + renderInfo.offsetY;
+      linePositionY = i * renderInfo.lineHeight + ascenderPx;
 
       if (this._settings.verticalAlign == 'middle') {
-        linePositionY += (renderInfo.lineHeight - renderInfo.fontSize) / 2;
+        linePositionY += (renderInfo.lineHeight - bareLineHeightPx) / 2;
       } else if (this._settings.verticalAlign == 'bottom') {
-        linePositionY += renderInfo.lineHeight - renderInfo.fontSize;
+        linePositionY += renderInfo.lineHeight - bareLineHeightPx;
       }
 
       if (this._settings.textAlign === 'right') {
@@ -699,7 +743,8 @@ export class LightningTextTextureRenderer {
       h: 0,
       fontStyle: 'normal',
       fontSize: 40,
-      fontFace: null,
+      fontFamily: null,
+      trFontFace: null,
       wordWrap: true,
       wordWrapWidth: 0,
       wordBreak: false,
@@ -710,6 +755,7 @@ export class LightningTextTextureRenderer {
       verticalAlign: 'top',
       offsetY: null,
       maxLines: 0,
+      maxHeight: null,
       overflowSuffix: '...',
       textColor: [1.0, 1.0, 1.0, 1.0],
       paddingLeft: 0,

package/src/core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.ts

@@ -56,7 +56,9 @@ import type {
 import type { WebGlCoreCtxTexture } from '../../../renderers/webgl/WebGlCoreCtxTexture.js';
 import { EventEmitter } from '../../../../common/EventEmitter.js';
 import type { Matrix3d } from '../../../lib/Matrix3d.js';
+import type { Dimensions } from '../../../../common/CommonTypes.js';
 import { WebGlCoreRenderer } from '../../../renderers/webgl/WebGlCoreRenderer.js';
+import { calcDefaultLineHeight } from '../../TextRenderingUtils.js';
 
 declare module '../TextRenderer.js' {
   interface TextRendererMap {
@@ -104,6 +106,11 @@ export interface SdfTextRendererState extends TextRendererState {
   distanceRange: number;
 
   trFontFace: SdfTrFontFace | undefined;
+
+  /**
+   * Resolved line height in logical screen pixel units
+   */
+  resLineHeight: number | undefined;
 }
 
 /**
@@ -250,6 +257,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       },
       lineHeight: (state, value) => {
         state.props.lineHeight = value;
+        state.resLineHeight = undefined;
         this.invalidateLayoutCache(state);
       },
       maxLines: (state, value) => {
@@ -362,6 +370,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       distanceRange: 0,
       trFontFace: undefined,
       isRenderable: false,
+      resLineHeight: undefined,
       debugData: {
         updateCount: 0,
         layoutCount: 0,
@@ -408,6 +417,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
 
     // If the font is loaded then so should the data
     assertTruthy(trFontFace.data, 'Font face data should be loaded');
+    assertTruthy(trFontFace.metrics, 'Font face metrics should be loaded');
 
     const {
       text,
@@ -417,7 +427,6 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       contain,
       width,
       height,
-      lineHeight,
       verticalAlign,
       scrollable,
       overflowSuffix,
@@ -440,8 +449,21 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
      */
     const fontSizeRatio = fontSize / sdfFontSize;
 
+    // If not already resolved, resolve the line height and store it in the state
+    let resLineHeight = state.resLineHeight;
+    if (resLineHeight === undefined) {
+      const lineHeight = state.props.lineHeight;
+      // If lineHeight is undefined, use the maxCharHeight from the font face
+      if (lineHeight === undefined) {
+        resLineHeight = calcDefaultLineHeight(trFontFace.metrics, fontSize);
+      } else {
+        resLineHeight = lineHeight;
+      }
+      state.resLineHeight = resLineHeight;
+    }
+
     // Needed in renderWindow calculation
-    const sdfLineHeight = lineHeight / fontSizeRatio;
+    const sdfLineHeight = resLineHeight / fontSizeRatio;
 
     state.distanceRange =
       fontSizeRatio * trFontFace.data.distanceField.distanceRange;
@@ -498,7 +520,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
         x,
         y,
         scrollY,
-        lineHeight,
+        resLineHeight,
         contain === 'both' ? elementBounds.y2 - elementBounds.y1 : 0,
         elementBounds,
         fontSizeRatio,
@@ -509,7 +531,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
     const start = getStartConditions(
       sdfFontSize,
       sdfLineHeight,
-      lineHeight,
+      trFontFace,
       verticalAlign,
       offsetY,
       fontSizeRatio,
@@ -536,7 +558,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       width,
       height,
       fontSize,
-      lineHeight,
+      resLineHeight,
       letterSpacing,
       vertexBuffer,
       contain,
@@ -560,7 +582,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
     // If we didn't exit early, we know we have completely computed w/h
     if (out2.fullyProcessed) {
       state.textW = out2.maxX * fontSizeRatio;
-      state.textH = out2.maxY * fontSizeRatio;
+      state.textH = out2.numLines * sdfLineHeight * fontSizeRatio;
     }
 
     // if (state.props.debug.printLayoutTime) {
@@ -575,13 +597,15 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
     transform: Matrix3d,
     clippingRect: Readonly<RectWithValid>,
     alpha: number,
+    parentHasRenderTexture: boolean,
+    framebufferDimensions: Dimensions,
   ): void {
     if (!state.vertexBuffer) {
       // Nothing to draw
       return;
     }
 
-    const renderer: WebGlCoreRenderer = this.stage.renderer as WebGlCoreRenderer;
+    const renderer = this.stage.renderer;
     assertTruthy(renderer instanceof WebGlCoreRenderer);
 
     const { fontSize, color, contain, scrollable, zIndex, debug } = state.props;
@@ -666,7 +690,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       webGlBuffers,
       this.sdfShader,
       {
-        transform: transform.data,
+        transform: transform.getFloatArr(),
         // IMPORTANT: The SDF Shader expects the color NOT to be premultiplied
         // for the best blending results. Which is why we use `mergeColorAlpha`
         // instead of `mergeColorAlphaPremultiplied` here.
@@ -681,6 +705,9 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
       { height: textH, width: textW },
       0,
       zIndex,
+      false,
+      parentHasRenderTexture,
+      framebufferDimensions,
     );
 
     const texture = state.trFontFace?.texture;
@@ -773,6 +800,7 @@ export class SdfTextRenderer extends TextRenderer<SdfTextRendererState> {
    * @param state
    */
   protected releaseFontFace(state: SdfTextRendererState) {
+    state.resLineHeight = undefined;
     if (state.trFontFace) {
       state.trFontFace.texture.setRenderableOwner(state, false);
       state.trFontFace = undefined;