@lightningtv/renderer 3.0.0-beta1

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

@@ -0,0 +1,263 @@
+/*
+ * 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 type { NormalizedFontMetrics } from './font-face-types/TrFontFace.js';
+import type { WebTrFontFace } from './font-face-types/WebTrFontFace.js';
+
+/**
+ * Returns CSS font setting string for use in canvas context.
+ *
+ * @param fontFace
+ * @param fontStyle
+ * @param fontSize
+ * @param precision
+ * @param defaultFontFace
+ * @returns
+ */
+export function getFontSetting(
+  fontFace: string | string[],
+  fontStyle: string,
+  fontSize: number,
+  precision: number,
+  defaultFontFace: string,
+): string {
+  let ff = fontFace;
+
+  if (!Array.isArray(ff)) {
+    ff = [ff];
+  }
+
+  const ffs: string[] = [];
+  for (let i = 0, n = ff.length; i < n; i++) {
+    let curFf = ff[i];
+    // Replace the default font face `null` with the actual default font face set
+    // on the stage.
+    if (curFf === null || curFf === undefined) {
+      curFf = defaultFontFace;
+    }
+    if (curFf === 'serif' || curFf === 'sans-serif') {
+      ffs.push(curFf);
+    } else {
+      ffs.push(`"${curFf}"`);
+    }
+  }
+
+  return `${fontStyle} ${fontSize * precision}px ${ffs.join(',')}`;
+}
+
+/**
+ * Returns true if the given character is a zero-width space.
+ *
+ * @param space
+ */
+export function isZeroWidthSpace(space: string): boolean {
+  return space === '' || space === '\u200B';
+}
+
+/**
+ * Returns true if the given character is a zero-width space or a regular space.
+ *
+ * @param space
+ */
+export function isSpace(space: string): boolean {
+  return isZeroWidthSpace(space) || space === ' ';
+}
+
+/**
+ * Converts a string into an array of tokens and the words between them.
+ *
+ * @param tokenRegex
+ * @param text
+ */
+export function tokenizeString(tokenRegex: RegExp, text: string): string[] {
+  const delimeters = text.match(tokenRegex) || [];
+  const words = text.split(tokenRegex) || [];
+
+  const final: string[] = [];
+  for (let i = 0; i < words.length; i++) {
+    final.push(words[i]!, delimeters[i]!);
+  }
+  final.pop();
+  return final.filter((word) => word != '');
+}
+
+/**
+ * Measure the width of a string accounting for letter spacing.
+ *
+ * @param context
+ * @param word
+ * @param space
+ */
+export function measureText(
+  context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  word: string,
+  space = 0,
+): number {
+  if (!space) {
+    return context.measureText(word).width;
+  }
+  return word.split('').reduce((acc, char) => {
+    // Zero-width spaces should not include letter spacing.
+    // And since we know the width of a zero-width space is 0, we can skip
+    // measuring it.
+    if (isZeroWidthSpace(char)) {
+      return acc;
+    }
+    return acc + context.measureText(char).width + space;
+  }, 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 getWebFontMetrics(
+  context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  fontFace: WebTrFontFace,
+  fontSize: number,
+): NormalizedFontMetrics {
+  if (fontFace.metrics) {
+    return fontFace.metrics;
+  }
+  // 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 browserMetrics = context.measureText(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+  );
+  console.warn(
+    `Font metrics not provided for Canvas Web font ${fontFace.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.',
+  );
+  let metrics: NormalizedFontMetrics;
+  if (
+    browserMetrics.actualBoundingBoxDescent &&
+    browserMetrics.actualBoundingBoxAscent
+  ) {
+    metrics = {
+      ascender: browserMetrics.actualBoundingBoxAscent / fontSize,
+      descender: -browserMetrics.actualBoundingBoxDescent / fontSize,
+      lineGap: 0.2,
+    };
+  } else {
+    // If the browser doesn't support the font metrics API, we'll use some
+    // default values.
+    metrics = {
+      ascender: 0.8,
+      descender: -0.2,
+      lineGap: 0.2,
+    };
+  }
+  // Save the calculated metrics to the font face for future use.
+  (fontFace.metrics as NormalizedFontMetrics | null) = metrics;
+  return metrics;
+}
+
+export interface WrapTextResult {
+  l: string[];
+  n: number[];
+}
+
+/**
+ * Applies newlines to a string to have it optimally fit into the horizontal
+ * bounds set by the Text object's wordWrapWidth property.
+ *
+ * @param context
+ * @param text
+ * @param wordWrapWidth
+ * @param letterSpacing
+ * @param indent
+ */
+export function wrapText(
+  context: CanvasRenderingContext2D,
+  text: string,
+  wordWrapWidth: number,
+  letterSpacing: number,
+  indent: number,
+): WrapTextResult {
+  // Greedy wrapping algorithm that will wrap words as the line grows longer.
+  // than its horizontal bounds.
+  const spaceRegex = / |\u200B/g;
+  const lines = text.split(/\r?\n/g);
+  let allLines: string[] = [];
+  const realNewlines: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const resultLines: string[] = [];
+    let result = '';
+    let spaceLeft = wordWrapWidth - indent;
+    const words = lines[i]!.split(spaceRegex);
+    const spaces = lines[i]!.match(spaceRegex) || [];
+    for (let j = 0; j < words.length; j++) {
+      const space = spaces[j - 1] || '';
+      const word = words[j]!;
+      const wordWidth = measureText(context, word, letterSpacing);
+      const wordWidthWithSpace =
+        wordWidth + measureText(context, space, letterSpacing);
+      if (j === 0 || wordWidthWithSpace > spaceLeft) {
+        // Skip printing the newline if it's the first word of the line that is.
+        // greater than the word wrap width.
+        if (j > 0) {
+          resultLines.push(result);
+          result = '';
+        }
+        result += word;
+        spaceLeft = wordWrapWidth - wordWidth - (j === 0 ? indent : 0);
+      } else {
+        spaceLeft -= wordWidthWithSpace;
+        result += space + word;
+      }
+    }
+
+    resultLines.push(result);
+    result = '';
+
+    allLines = allLines.concat(resultLines);
+
+    if (i < lines.length - 1) {
+      realNewlines.push(allLines.length);
+    }
+  }
+
+  return { l: allLines, n: realNewlines };
+}

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

@@ -0,0 +1,183 @@
+/*
+ * 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 type { TrFontFace } from './font-face-types/TrFontFace.js';
+import type { TextRendererMap, TrFontProps } from './renderers/TextRenderer.js';
+
+const weightConversions: { [key: string]: number } = {
+  normal: 400,
+  bold: 700,
+  bolder: 900,
+  lighter: 100,
+};
+
+const fontWeightToNumber = (weight: string | number): number => {
+  if (typeof weight === 'number') {
+    return weight;
+  }
+
+  return weightConversions[weight] || 400;
+};
+
+function resolveFontToUse(
+  familyMapsByPriority: FontFamilyMap[],
+  family: string,
+  weightIn: string | number,
+  style: string,
+  stretch: string,
+): TrFontFace | undefined {
+  let weight = fontWeightToNumber(weightIn);
+
+  for (const fontFamiles of familyMapsByPriority) {
+    const fontFaces = fontFamiles[family];
+
+    if (!fontFaces) {
+      continue;
+    }
+
+    if (fontFaces.size === 1) {
+      // No Exact match found, find nearest weight match
+      console.warn(
+        `TrFontManager: Only one font face found for family: '${family}' - will be used for all weights and styles`,
+      );
+
+      return fontFaces.values().next().value as TrFontFace;
+    }
+
+    const weightMap = new Map<number, TrFontFace>();
+    for (const fontFace of fontFaces) {
+      const fontFamilyWeight = fontWeightToNumber(fontFace.descriptors.weight);
+      if (
+        fontFamilyWeight === weight &&
+        fontFace.descriptors.style === style &&
+        fontFace.descriptors.stretch === stretch
+      ) {
+        return fontFace;
+      }
+
+      weightMap.set(fontFamilyWeight, fontFace);
+    }
+
+    // No Exact match found, find nearest weight match
+    const msg = `TrFontManager: No exact match: '${family} Weight: ${weight} Style: ${style} Stretch: ${stretch}'`;
+    console.error(msg);
+
+    // Follow the CSS font-weight algorithm to find the nearest weight match
+    // https://www.w3.org/TR/2018/REC-css-fonts-3-20180920/#font-matching-algorithm
+
+    if (weight === 400 && weightMap.has(500)) {
+      return weightMap.get(500);
+    }
+
+    if (weight === 500 && weightMap.has(400)) {
+      return weightMap.get(400);
+    }
+
+    if (weight < 400) {
+      while (weight > 0) {
+        if (weightMap.has(weight)) {
+          return weightMap.get(weight);
+        }
+        weight -= 100;
+      }
+      // reset back for the next loop
+      weight = 600;
+    }
+
+    while (weight < 1000) {
+      if (weightMap.has(weight)) {
+        return weightMap.get(weight);
+      }
+      weight += 100;
+    }
+
+    // finally check lower again
+    weight = 500;
+    while (weight > 0) {
+      if (weightMap.has(weight)) {
+        return weightMap.get(weight);
+      }
+      weight -= 100;
+    }
+  }
+
+  return;
+}
+
+/**
+ * Structure mapping font family names to a set of font faces.
+ */
+export interface FontFamilyMap {
+  [familyName: string]: Set<TrFontFace>;
+}
+
+export class TrFontManager {
+  private fontCache = new Map<string, TrFontFace>();
+
+  constructor(private textRenderers: Partial<TextRendererMap>) {
+    // Intentionally left blank
+  }
+
+  public addFontFace(font: TrFontFace): void {
+    // All the font face to all of the text renderers that support it
+    for (const trId in this.textRenderers) {
+      const tr = this.textRenderers[trId as keyof TextRendererMap];
+      if (tr && tr.isFontFaceSupported(font)) {
+        tr.addFontFace(font);
+      }
+    }
+  }
+
+  /**
+   * Utility method to resolve a single font face from a list of prioritized family maps based on
+   * a set of font properties.
+   *
+   * @remarks
+   * These are to be used by a text renderer to resolve a font face if needed.
+   *
+   * @param familyMapsByPriority
+   * @param props
+   * @returns
+   */
+  public resolveFontFace(
+    familyMapsByPriority: FontFamilyMap[],
+    props: TrFontProps,
+    rendererType: 'canvas' | 'sdf',
+  ): TrFontFace | undefined {
+    const { fontFamily, fontWeight, fontStyle, fontStretch } = props;
+    const fontCacheString = `${rendererType}_${fontFamily}_${fontStyle}_${fontWeight}_${fontStretch}`;
+
+    if (this.fontCache.has(fontCacheString) === true) {
+      return this.fontCache.get(fontCacheString);
+    }
+
+    const resolvedFont = resolveFontToUse(
+      familyMapsByPriority,
+      fontFamily,
+      fontWeight,
+      fontStyle,
+      fontStretch,
+    );
+    if (resolvedFont !== undefined) {
+      this.fontCache.set(fontCacheString, resolvedFont);
+    }
+
+    return resolvedFont;
+  }
+}

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

@@ -0,0 +1,176 @@
+/*
+ * 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 type { Renderer } from '../../../Renderer';
+import { assertTruthy } from '../../../../utils.js';
+import type { Stage } from '../../../Stage.js';
+import { WebGlRenderer } from '../../../renderers/webgl/WebGlRenderer.js';
+import { ImageTexture } from '../../../textures/ImageTexture.js';
+import {
+  TrFontFace,
+  type NormalizedFontMetrics,
+  type TrFontFaceOptions,
+} from '../TrFontFace.js';
+import { fetchJson } from '../utils.js';
+import type { FontShaper } from './internal/FontShaper.js';
+import { SdfFontShaper, type SdfFontData } from './internal/SdfFontShaper.js';
+
+type SdfFontType = 'ssdf' | 'msdf';
+
+declare module '../TrFontFace.js' {
+  interface TrFontFaceMap {
+    ssdf: SdfTrFontFace<'ssdf'>;
+    msdf: SdfTrFontFace<'msdf'>;
+  }
+}
+
+interface GlyphAtlasEntry {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface SdfTrFontFaceOptions extends TrFontFaceOptions {
+  atlasUrl: string;
+  atlasDataUrl: string;
+  stage: Stage;
+}
+
+export class SdfTrFontFace<
+  FontTypeT extends SdfFontType = SdfFontType,
+> extends TrFontFace {
+  public readonly type: FontTypeT;
+  public readonly texture: ImageTexture;
+  /**
+   * Height of the tallest character in the font including the whitespace above it
+   * in SDF/vertex units.
+   */
+  public readonly maxCharHeight: number = 0;
+  public readonly shaper: FontShaper | undefined;
+  public readonly glyphMap: Map<number, SdfFontData['chars'][0]> = new Map();
+  public data: SdfFontData | undefined;
+
+  constructor(type: FontTypeT, options: SdfTrFontFaceOptions) {
+    super(options);
+    const { atlasUrl, atlasDataUrl, stage } = options;
+    this.type = type;
+    const renderer = stage.renderer;
+    assertTruthy(
+      renderer instanceof WebGlRenderer,
+      'SDF Font Faces can only be used with the WebGL Renderer',
+    );
+
+    // Load image
+    this.texture = stage.txManager.createTexture('ImageTexture', {
+      src: atlasUrl,
+      // IMPORTANT: The SDF shader requires the alpha channel to NOT be
+      // premultiplied on the atlas texture. If it is premultiplied, the
+      // rendering of SDF glyphs (especially single-channel SDF fonts) will
+      // be very jagged.
+      premultiplyAlpha: false,
+    });
+
+    // Load the texture
+    stage.txManager.loadTexture(this.texture, true);
+
+    // FIXME This is a stop-gap solution to avoid Font Face textures to be cleaned up
+    // Ideally we do want to clean up the textures if they're not being used to save as much memory as possible
+    // However, we need to make sure that the font face is reloaded if the texture is cleaned up and needed again
+    // and make sure the SdfFontRenderer is properly guarded against textures being reloaded
+    // for now this will do the trick and the increase on memory is not that big
+    this.texture.preventCleanup = true;
+
+    this.texture.on('loaded', () => {
+      this.checkLoaded();
+      // Make sure we mark the stage for a re-render (in case the font's texture was freed and reloaded)
+      stage.requestRender();
+    });
+
+    // Set this.data to the fetched data from dataUrl
+    fetchJson(atlasDataUrl)
+      .then((response) => {
+        this.data = JSON.parse(response as unknown as string) as SdfFontData;
+        assertTruthy(this.data);
+        // Add all the glyphs to the glyph map
+
+        let maxCharHeight = 0;
+        this.data.chars.forEach((glyph) => {
+          this.glyphMap.set(glyph.id, glyph);
+          const charHeight = glyph.yoffset + glyph.height;
+          if (charHeight > maxCharHeight) {
+            maxCharHeight = charHeight;
+          }
+        });
+
+        (this.maxCharHeight as number) = maxCharHeight;
+        // We know `data` is defined here, because we just set it
+
+        (this.shaper as FontShaper) = new SdfFontShaper(
+          this.data,
+          this.glyphMap,
+        );
+
+        // If the metrics aren't provided explicitly in the font face options,
+        // Gather them from the metrics added by the msdf-generator tool ()
+        // If they are missing then we throw an error.
+        if (!this.metrics) {
+          if (this.data?.lightningMetrics) {
+            const { ascender, descender, lineGap, unitsPerEm } =
+              this.data.lightningMetrics;
+            (this.metrics as NormalizedFontMetrics | null) = {
+              ascender: ascender / unitsPerEm,
+              descender: descender / unitsPerEm,
+              lineGap: lineGap / unitsPerEm,
+            };
+          } else {
+            throw new Error(
+              `Font metrics not found in ${this.type} font ${this.fontFamily}. ` +
+                'Make sure you are using the latest version of the Lightning ' +
+                '3 `msdf-generator` tool to generate your SDF fonts.',
+            );
+          }
+        }
+
+        this.checkLoaded();
+      })
+      .catch(console.error);
+  }
+
+  getAtlasEntry(glyphId: number): GlyphAtlasEntry {
+    const glyph = this.glyphMap.get(glyphId);
+    if (glyph === undefined) {
+      throw new Error(`Glyph ${glyphId} not found in font ${this.fontFamily}`);
+    }
+    return {
+      x: glyph.x,
+      y: glyph.y,
+      width: glyph.width,
+      height: glyph.height,
+    };
+  }
+
+  private checkLoaded(): void {
+    if (this.loaded) return;
+    if (this.texture.state === 'loaded' && this.data) {
+      (this.loaded as boolean) = true;
+      this.emit('loaded');
+    }
+  }
+}