@lightningjs/renderer 3.0.0-beta14 → 3.0.0-beta15

package/src/core/text-rendering/CanvasFontHandler.ts

@@ -24,9 +24,19 @@ import type {
   NormalizedFontMetrics,
 } from './TextRenderer.js';
 import type { Stage } from '../Stage.js';
-import { calculateFontMetrics } from './Utils.js';
+import { hasZeroWidthSpace } from './Utils.js';
 import type { CoreTextNode } from '../CoreTextNode.js';
 import { UpdateType } from '../CoreNode.js';
+import {
+  defaultFontMetrics,
+  normalizeFontMetrics,
+} from './TextLayoutEngine.js';
+
+interface CanvasFont {
+  fontFamily: string;
+  fontFace?: FontFace;
+  metrics?: FontMetrics;
+}
 
 /**
  * Global font set regardless of if run in the main thread or a web worker
@@ -36,24 +46,19 @@ import { UpdateType } from '../CoreNode.js';
 
 // Global state variables for fontHandler
 const fontFamilies: Record<string, FontFace> = {};
-const loadedFonts = new Set<string>();
 const fontLoadPromises = new Map<string, Promise<void>>();
 const normalizedMetrics = new Map<string, NormalizedFontMetrics>();
-const nodesWaitingForFont: Record<string, CoreTextNode[]> = Object.create(null);
-let initialized = false;
-let context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+const nodesWaitingForFont: Record<string, CoreTextNode[]> = Object.create(
+  null,
+) as Record<string, CoreTextNode[]>;
 
-/**
- * Normalize font metrics to be in the range of 0 to 1
- */
-function normalizeMetrics(metrics: FontMetrics): NormalizedFontMetrics {
-  return {
-    ascender: metrics.ascender / metrics.unitsPerEm,
-    descender: metrics.descender / metrics.unitsPerEm,
-    lineGap: metrics.lineGap / metrics.unitsPerEm,
-  };
-}
+const fontCache = new Map<string, CanvasFont>();
 
+let initialized = false;
+let context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+let measureContext:
+  | CanvasRenderingContext2D
+  | OffscreenCanvasRenderingContext2D;
 /**
  * make fontface add not show errors
  */
@@ -69,6 +74,19 @@ export const canRenderFont = (): boolean => {
   return true;
 };
 
+const processFontData = (
+  fontFamily: string,
+  fontFace?: FontFace,
+  metrics?: FontMetrics,
+) => {
+  metrics = metrics || defaultFontMetrics;
+  fontCache.set(fontFamily, {
+    fontFamily,
+    fontFace,
+    metrics,
+  });
+};
+
 /**
  * Load a font by providing fontFamily, fontUrl, and optional metrics
  */
@@ -79,7 +97,7 @@ export const loadFont = async (
   const { fontFamily, fontUrl, metrics } = options;
 
   // If already loaded, return immediately
-  if (loadedFonts.has(fontFamily) === true) {
+  if (fontCache.has(fontFamily) === true) {
     return;
   }
 
@@ -95,12 +113,8 @@ export const loadFont = async (
     .load()
     .then((loadedFont) => {
       (document.fonts as FontFaceSetWithAdd).add(loadedFont);
-      loadedFonts.add(fontFamily);
+      processFontData(fontFamily, loadedFont, metrics);
       fontLoadPromises.delete(fontFamily);
-      // Store normalized metrics if provided
-      if (metrics) {
-        setFontMetrics(fontFamily, normalizeMetrics(metrics));
-      }
       for (let key in nwff) {
         nwff[key]!.setUpdateType(UpdateType.Local);
       }
@@ -127,7 +141,8 @@ export const getFontFamilies = (): FontFamilyMap => {
  * Initialize the global font handler
  */
 export const init = (
-  c?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  mc: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
 ): void => {
   if (initialized === true) {
     return;
@@ -140,16 +155,17 @@ export const init = (
   }
 
   context = c;
+  measureContext = mc;
 
   // Register the default 'sans-serif' font face
-  const defaultMetrics: NormalizedFontMetrics = {
-    ascender: 0.8,
-    descender: -0.2,
-    lineGap: 0.2,
+  const defaultMetrics: FontMetrics = {
+    ascender: 800,
+    descender: -200,
+    lineGap: 200,
+    unitsPerEm: 1000,
   };
 
-  setFontMetrics('sans-serif', defaultMetrics);
-  loadedFonts.add('sans-serif');
+  processFontData('sans-serif', undefined, defaultMetrics);
   initialized = true;
 };
 
@@ -159,7 +175,7 @@ export const type = 'canvas';
  * Check if a font is already loaded by font family
  */
 export const isFontLoaded = (fontFamily: string): boolean => {
-  return loadedFonts.has(fontFamily) || fontFamily === 'sans-serif';
+  return fontCache.has(fontFamily);
 };
 
 /**
@@ -191,20 +207,101 @@ export const getFontMetrics = (
   fontFamily: string,
   fontSize: number,
 ): NormalizedFontMetrics => {
-  let out =
-    normalizedMetrics.get(fontFamily) ||
-    normalizedMetrics.get(fontFamily + fontSize);
+  const out = normalizedMetrics.get(fontFamily + fontSize);
   if (out !== undefined) {
     return out;
   }
-  out = calculateFontMetrics(context, fontFamily, fontSize);
-  normalizedMetrics.set(fontFamily + fontSize, out);
-  return out;
+  let metrics = fontCache.get(fontFamily)!.metrics;
+  if (metrics === undefined) {
+    metrics = calculateFontMetrics(fontFamily, fontSize);
+  }
+  return processFontMetrics(fontFamily, fontSize, metrics);
 };
 
-export const setFontMetrics = (
+export const processFontMetrics = (
   fontFamily: string,
-  metrics: NormalizedFontMetrics,
-): void => {
-  normalizedMetrics.set(fontFamily, metrics);
+  fontSize: number,
+  metrics: FontMetrics,
+): NormalizedFontMetrics => {
+  const label = fontFamily + fontSize;
+  const normalized = normalizeFontMetrics(metrics, fontSize);
+  normalizedMetrics.set(label, normalized);
+  return normalized;
 };
+
+export const measureText = (
+  text: string,
+  fontFamily: string,
+  letterSpacing: number,
+) => {
+  if (letterSpacing === 0) {
+    return measureContext.measureText(text).width;
+  }
+  if (hasZeroWidthSpace(text) === false) {
+    return measureContext.measureText(text).width + letterSpacing * text.length;
+  }
+  return text.split('').reduce((acc, char) => {
+    if (hasZeroWidthSpace(char) === true) {
+      return acc;
+    }
+    return acc + measureContext.measureText(char).width + letterSpacing;
+  }, 0);
+};
+
+/**
+ * Get the font metrics for a font face.
+ *
+ * @remarks
+ * This function will attempt to grab the explicitly defined metrics from the
+ * font face first. If the font face does not have metrics defined, it will
+ * attempt to calculate the metrics using the browser's measureText method.
+ *
+ * If the browser does not support the font metrics API, it will use some
+ * default values.
+ *
+ * @param context
+ * @param fontFace
+ * @param fontSize
+ * @returns
+ */
+export function calculateFontMetrics(
+  fontFamily: string,
+  fontSize: number,
+): FontMetrics {
+  // If the font face doesn't have metrics defined, we fallback to using the
+  // browser's measureText method to calculate take a best guess at the font
+  // actual font's metrics.
+  // - fontBoundingBox[Ascent|Descent] is the best estimate but only supported
+  //   in Chrome 87+ (2020), Firefox 116+ (2023), and Safari 11.1+ (2018).
+  //   - It is an estimate as it can vary between browsers.
+  // - actualBoundingBox[Ascent|Descent] is less accurate and supported in
+  //   Chrome 77+ (2019), Firefox 74+ (2020), and Safari 11.1+ (2018).
+  // - If neither are supported, we'll use some default values which will
+  //   get text on the screen but likely not be great.
+  // NOTE: It's been decided not to rely on fontBoundingBox[Ascent|Descent]
+  // as it's browser support is limited and it also tends to produce higher than
+  // expected values. It is instead HIGHLY RECOMMENDED that developers provide
+  // explicit metrics in the font face definition.
+  const metrics = measureContext.measureText(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+  );
+  console.warn(
+    `Font metrics not provided for Canvas Web font ${fontFamily}. ` +
+      'Using fallback values. It is HIGHLY recommended you use the latest ' +
+      'version of the Lightning 3 `msdf-generator` tool to extract the default ' +
+      'metrics for the font and provide them in the Canvas Web font definition.',
+  );
+  const ascender =
+    metrics.fontBoundingBoxAscent ?? metrics.actualBoundingBoxAscent ?? 0;
+  const descender =
+    metrics.fontBoundingBoxDescent ?? metrics.actualBoundingBoxDescent ?? 0;
+  return {
+    ascender,
+    descender: -descender,
+    lineGap:
+      (metrics.emHeightAscent ?? 0) +
+      (metrics.emHeightDescent ?? 0) -
+      (ascender + descender),
+    unitsPerEm: (metrics.emHeightAscent ?? 0) + (metrics.emHeightDescent ?? 0),
+  };
+}