@lightningjs/renderer 3.0.0-beta9 → 3.0.1

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

@@ -0,0 +1,304 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2025 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 type {
+  FontFamilyMap,
+  FontLoadOptions,
+  FontMetrics,
+  NormalizedFontMetrics,
+} from './TextRenderer.js';
+import type { Stage } from '../Stage.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
+ */
+// const globalFontSet: FontFaceSet = (resolvedGlobal.document?.fonts ||
+//   (resolvedGlobal as unknown as { fonts: FontFaceSet }).fonts) as FontFaceSet;
+
+// Global state variables for fontHandler
+const fontFamilies: Record<string, FontFace> = {};
+const fontLoadPromises = new Map<string, Promise<void>>();
+const normalizedMetrics = new Map<string, NormalizedFontMetrics>();
+const nodesWaitingForFont: Record<string, CoreTextNode[]> = Object.create(
+  null,
+) as Record<string, CoreTextNode[]>;
+
+const fontCache = new Map<string, CanvasFont>();
+
+let initialized = false;
+let context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+let measureContext:
+  | CanvasRenderingContext2D
+  | OffscreenCanvasRenderingContext2D;
+
+/**
+ * Check if a font can be rendered
+ */
+export const canRenderFont = (): boolean => {
+  // Canvas can always render any font family (assuming the browser supports it)
+  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
+ */
+export const loadFont = async (
+  stage: Stage,
+  options: FontLoadOptions,
+): Promise<void> => {
+  const { fontFamily, fontUrl, metrics } = options;
+
+  // If already loaded, return immediately
+  if (fontCache.has(fontFamily) === true) {
+    return;
+  }
+
+  const existingPromise = fontLoadPromises.get(fontFamily);
+  // If already loading, return the existing promise
+  if (existingPromise !== undefined) {
+    return existingPromise;
+  }
+
+  const nwff: CoreTextNode[] = (nodesWaitingForFont[fontFamily] = []);
+  // Create and store the loading promise
+  const loadPromise = new FontFace(fontFamily, `url(${fontUrl})`)
+    .load()
+    .then((loadedFont) => {
+      stage.platform.addFont(loadedFont);
+      processFontData(fontFamily, loadedFont, metrics);
+      fontLoadPromises.delete(fontFamily);
+      for (let key in nwff) {
+        nwff[key]!.setUpdateType(UpdateType.Local);
+      }
+      delete nodesWaitingForFont[fontFamily];
+    })
+    .catch((error) => {
+      fontLoadPromises.delete(fontFamily);
+      console.error(`Failed to load font: ${fontFamily}`, error);
+      throw error;
+    });
+
+  fontLoadPromises.set(fontFamily, loadPromise);
+  return loadPromise;
+};
+
+/**
+ * Get the font families map for resolving fonts
+ */
+export const getFontFamilies = (): FontFamilyMap => {
+  return fontFamilies;
+};
+
+/**
+ * Initialize the global font handler
+ */
+export const init = (
+  c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  mc: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+): void => {
+  if (initialized === true) {
+    return;
+  }
+
+  if (c === undefined) {
+    throw new Error(
+      'Canvas context is not provided for font handler initialization',
+    );
+  }
+
+  context = c;
+  measureContext = mc;
+
+  // Register the default 'sans-serif' font face
+  const defaultMetrics: FontMetrics = {
+    ascender: 800,
+    descender: -200,
+    lineGap: 200,
+    unitsPerEm: 1000,
+  };
+
+  processFontData('sans-serif', undefined, defaultMetrics);
+  initialized = true;
+};
+
+export const type = 'canvas';
+
+/**
+ * Check if a font is already loaded by font family
+ */
+export const isFontLoaded = (fontFamily: string): boolean => {
+  return fontCache.has(fontFamily);
+};
+
+/**
+ * Wait for a font to load
+ *
+ * @param fontFamily
+ * @param node
+ */
+export const waitingForFont = (fontFamily: string, node: CoreTextNode) => {
+  if (nodesWaitingForFont[fontFamily] === undefined) {
+    return;
+  }
+  nodesWaitingForFont[fontFamily]![node.id] = node;
+};
+
+/**
+ * Stop waiting for a font to load
+ *
+ * @param fontFamily
+ * @param node
+ * @returns
+ */
+export const stopWaitingForFont = (fontFamily: string, node: CoreTextNode) => {
+  if (nodesWaitingForFont[fontFamily] === undefined) {
+    return;
+  }
+
+  delete nodesWaitingForFont[fontFamily][node.id];
+};
+
+export const getFontMetrics = (
+  fontFamily: string,
+  fontSize: number,
+): NormalizedFontMetrics => {
+  const out = normalizedMetrics.get(fontFamily + fontSize);
+  if (out !== undefined) {
+    return out;
+  }
+  let metrics = fontCache.get(fontFamily)!.metrics;
+  if (metrics === undefined) {
+    metrics = calculateFontMetrics(fontFamily, fontSize);
+  }
+  return processFontMetrics(fontFamily, fontSize, metrics);
+};
+
+export const processFontMetrics = (
+  fontFamily: string,
+  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),
+  };
+}

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

@@ -0,0 +1,255 @@
+/*
+ * 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 { assertTruthy } from '../../utils.js';
+import type { Stage } from '../Stage.js';
+import type { TextLineStruct, TextRenderInfo } from './TextRenderer.js';
+import * as CanvasFontHandler from './CanvasFontHandler.js';
+import type { CoreTextNodeProps } from '../CoreTextNode.js';
+import { hasZeroWidthSpace } from './Utils.js';
+import { mapTextLayout } from './TextLayoutEngine.js';
+
+const MAX_TEXTURE_DIMENSION = 4096;
+
+const type = 'canvas' as const;
+
+let canvas: HTMLCanvasElement | OffscreenCanvas | null = null;
+let context:
+  | CanvasRenderingContext2D
+  | OffscreenCanvasRenderingContext2D
+  | null = null;
+
+// Separate canvas and context for text measurements
+let measureCanvas: HTMLCanvasElement | OffscreenCanvas | null = null;
+let measureContext:
+  | CanvasRenderingContext2D
+  | OffscreenCanvasRenderingContext2D
+  | null = null;
+
+// Cache for text layout calculations
+const layoutCache = new Map<
+  string,
+  {
+    lines: string[];
+    lineWidths: number[];
+    maxLineWidth: number;
+    remainingText: string;
+    moreTextLines: boolean;
+  }
+>();
+
+// Initialize the Text Renderer
+const init = (stage: Stage): void => {
+  const dpr = stage.options.devicePhysicalPixelRatio;
+
+  // Drawing canvas and context
+  canvas = stage.platform.createCanvas() as HTMLCanvasElement | OffscreenCanvas;
+  context = canvas.getContext('2d', { willReadFrequently: true }) as
+    | CanvasRenderingContext2D
+    | OffscreenCanvasRenderingContext2D;
+
+  context.setTransform(dpr, 0, 0, dpr, 0, 0);
+  context.textRendering = 'optimizeSpeed';
+
+  // Separate measuring canvas and context
+  measureCanvas = stage.platform.createCanvas() as
+    | HTMLCanvasElement
+    | OffscreenCanvas;
+  measureContext = measureCanvas.getContext('2d') as
+    | CanvasRenderingContext2D
+    | OffscreenCanvasRenderingContext2D;
+
+  measureContext.setTransform(dpr, 0, 0, dpr, 0, 0);
+  measureContext.textRendering = 'optimizeSpeed';
+
+  // Set up a minimal size for the measuring canvas since we only use it for measurements
+  measureCanvas.width = 1;
+  measureCanvas.height = 1;
+
+  CanvasFontHandler.init(context, measureContext);
+};
+
+/**
+ * Canvas text renderer
+ *
+ * @param stage - Stage instance for font resolution
+ * @param props - Text rendering properties
+ * @returns Object containing ImageData and dimensions
+ */
+const renderText = (props: CoreTextNodeProps): TextRenderInfo => {
+  assertTruthy(canvas, 'Canvas is not initialized');
+  assertTruthy(context, 'Canvas context is not available');
+  assertTruthy(measureContext, 'Canvas measureContext is not available');
+  // Extract already normalized properties
+  const {
+    text,
+    fontFamily,
+    fontStyle,
+    fontSize,
+    textAlign,
+    maxLines,
+    lineHeight,
+    verticalAlign,
+    overflowSuffix,
+    maxWidth,
+    maxHeight,
+    wordBreak,
+  } = props;
+
+  const font = `${fontStyle} ${fontSize}px Unknown, ${fontFamily}`;
+  // Get font metrics and calculate line height
+  measureContext.font = font;
+  measureContext.textBaseline = 'hanging';
+
+  const metrics = CanvasFontHandler.getFontMetrics(fontFamily, fontSize);
+
+  const letterSpacing = props.letterSpacing;
+
+  const [
+    lines,
+    remainingLines,
+    hasRemainingText,
+    bareLineHeight,
+    lineHeightPx,
+    effectiveWidth,
+    effectiveHeight,
+  ] = mapTextLayout(
+    CanvasFontHandler.measureText,
+    metrics,
+    text,
+    textAlign,
+    fontFamily,
+    lineHeight,
+    overflowSuffix,
+    wordBreak,
+    letterSpacing,
+    maxLines,
+    maxWidth,
+    maxHeight,
+  );
+  const lineAmount = lines.length;
+  const canvasW = Math.ceil(effectiveWidth);
+  const canvasH = Math.ceil(effectiveHeight);
+
+  canvas.width = canvasW;
+  canvas.height = canvasH;
+  context.fillStyle = 'white';
+  context.font = font;
+  context.textBaseline = 'hanging';
+
+  // Performance optimization for large fonts
+  if (fontSize >= 128) {
+    context.globalAlpha = 0.01;
+    context.fillRect(0, 0, 0.01, 0.01);
+    context.globalAlpha = 1.0;
+  }
+
+  for (let i = 0; i < lineAmount; i++) {
+    const line = lines[i] as TextLineStruct;
+    const textLine = line[0];
+    let currentX = Math.ceil(line[3]);
+    const currentY = Math.ceil(line[4]);
+    if (letterSpacing === 0) {
+      context.fillText(textLine, currentX, currentY);
+    } else {
+      const textLineLength = textLine.length;
+      for (let j = 0; j < textLineLength; j++) {
+        const char = textLine.charAt(j);
+        if (hasZeroWidthSpace(char) === true) {
+          continue;
+        }
+        context.fillText(char, currentX, currentY);
+        currentX += CanvasFontHandler.measureText(
+          char,
+          fontFamily,
+          letterSpacing,
+        );
+      }
+    }
+  }
+
+  // Extract image data
+  let imageData: ImageData | null = null;
+  if (canvas.width > 0 && canvas.height > 0) {
+    imageData = context.getImageData(0, 0, canvasW, canvasH);
+  }
+  return {
+    imageData,
+    width: effectiveWidth,
+    height: effectiveHeight,
+    remainingLines,
+    hasRemainingText,
+  };
+};
+
+/**
+ * Generate a cache key for text layout calculations
+ */
+function generateLayoutCacheKey(
+  text: string,
+  fontFamily: string,
+  fontSize: number,
+  fontStyle: string,
+  wordWrap: boolean,
+  wordWrapWidth: number,
+  letterSpacing: number,
+  maxLines: number,
+  overflowSuffix: string,
+): string {
+  return `${text}-${fontFamily}-${fontSize}-${fontStyle}-${wordWrap}-${wordWrapWidth}-${letterSpacing}-${maxLines}-${overflowSuffix}`;
+}
+
+/**
+ * Clear layout cache for memory management
+ */
+const clearLayoutCache = (): void => {
+  layoutCache.clear();
+};
+
+/**
+ * Add quads for rendering (Canvas doesn't use quads)
+ */
+const addQuads = (): Float32Array | null => {
+  // Canvas renderer doesn't use quad-based rendering
+  // Return null for interface compatibility
+  return null;
+};
+
+/**
+ * Render quads for Canvas renderer (Canvas doesn't use quad-based rendering)
+ */
+const renderQuads = (): void => {
+  // Canvas renderer doesn't use quad-based rendering
+  // This method is for interface compatibility only
+};
+
+/**
+ * Canvas Text Renderer - implements TextRenderer interface
+ */
+const CanvasTextRenderer = {
+  type,
+  font: CanvasFontHandler,
+  renderText,
+  addQuads,
+  renderQuads,
+  init,
+  clearLayoutCache,
+};
+
+export default CanvasTextRenderer;