@lightningjs/renderer 0.3.0 → 0.3.2

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

@@ -0,0 +1,96 @@
+/*
+ * 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 { SdfTrFontFace } from './font-face-types/SdfTrFontFace/SdfTrFontFace.js';
+import type { TrFontFace } from './font-face-types/TrFontFace.js';
+import { WebTrFontFace } from './font-face-types/WebTrFontFace.js';
+import type { TextRendererMap, TrFontProps } from './renderers/TextRenderer.js';
+
+/**
+ * Structure mapping font family names to a set of font faces.
+ */
+export interface FontFamilyMap {
+  [familyName: string]: Set<TrFontFace>;
+}
+
+export class TrFontManager {
+  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 static resolveFontFace(
+    familyMapsByPriority: FontFamilyMap[],
+    props: TrFontProps,
+  ): TrFontFace | undefined {
+    const closeFaces: WebTrFontFace[] = [];
+    const exactMatch = familyMapsByPriority.reduce<TrFontFace | undefined>(
+      (prev, fontFamiles) => {
+        if (prev) {
+          return prev;
+        }
+        const fontFaces = fontFamiles[props.fontFamily];
+        if (!fontFaces) {
+          return undefined;
+        }
+        const fontFacesCopy = new Set(fontFaces);
+
+        // Remove any font faces that don't match the style exactly
+        // TODO: In the future we may enhance this to find the best match
+        // based on font weight, style, etc.
+        // See https://www.w3.org/TR/2018/REC-css-fonts-3-20180920/#font-matching-algorithm
+        for (const fontFace of fontFacesCopy) {
+          if (
+            fontFace.descriptors.stretch !== props.fontStretch ||
+            fontFace.descriptors.style !== props.fontStyle ||
+            fontFace.descriptors.weight !== props.fontWeight
+          ) {
+            fontFacesCopy.delete(fontFace);
+          }
+        }
+
+        // Return the first font face that matches the style exactly
+        return fontFacesCopy.values().next().value;
+      },
+      undefined,
+    );
+
+    return exactMatch || closeFaces[0];
+  }
+}

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

@@ -0,0 +1,128 @@
+/*
+ * 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 { WebGlCoreRenderer } from '../../../renderers/webgl/WebGlCoreRenderer.js';
+import { ImageTexture } from '../../../textures/ImageTexture.js';
+import { TrFontFace, type TrFontFaceDescriptors } from '../TrFontFace.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 class SdfTrFontFace<
+  FontTypeT extends SdfFontType = SdfFontType,
+> extends TrFontFace {
+  public readonly type: FontTypeT;
+  public readonly texture: ImageTexture;
+  public readonly data: SdfFontData | undefined;
+  public readonly shaper: FontShaper | undefined;
+  public readonly glyphMap: Map<number, SdfFontData['chars'][0]> = new Map();
+
+  constructor(
+    fontFamily: string,
+    descriptors: Partial<TrFontFaceDescriptors>,
+    type: FontTypeT,
+    stage: Stage,
+    atlasUrl: string,
+    atlasDataUrl: string,
+  ) {
+    super(fontFamily, descriptors);
+    this.type = type;
+    const renderer = stage.renderer;
+    assertTruthy(
+      renderer instanceof WebGlCoreRenderer,
+      'SDF Font Faces can only be used with the WebGL Renderer',
+    );
+
+    this.texture = stage.txManager.loadTexture(
+      '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,
+      },
+      {
+        preload: true,
+      },
+    );
+
+    // TODO: Add texture loaded support
+    // this.texture.on('loaded', () => {
+    //   this.checkLoaded();
+    // });
+
+    // Set this.data to the fetched data from dataUrl
+    fetch(atlasDataUrl)
+      .then(async (response) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        (this.data as SdfFontData) = await response.json();
+        // We know `data` is defined here, because we just set it
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        (this.shaper as FontShaper) = new SdfFontShaper(this.data!);
+        // Add all the glyphs to the glyph map
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        this.data!.chars.forEach((glyph) => {
+          this.glyphMap.set(glyph.id, glyph);
+        });
+        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.loaded && */ this.data) {
+      (this.loaded as boolean) = true;
+      this.emit('loaded');
+    }
+  }
+}

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

@@ -0,0 +1,139 @@
+/*
+ * 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 { PeekableIterator } from '../../../renderers/SdfTextRenderer/internal/PeekableGenerator.js';
+
+/**
+ * HarfBuzz compatible glyph position info
+ */
+export interface GlyphPosition {
+  /**
+   * how much the line advances after drawing this glyph when setting text in horizontal direction.
+   */
+  xAdvance: number;
+  /**
+   * how much the line advances after drawing this glyph when setting text in vertical direction.
+   */
+  yAdvance: number;
+  /**
+   * how much the glyph moves on the X-axis before drawing it, this should not affect how much the line advances.
+   */
+  xOffset: number;
+  /**
+   * how much the glyph moves on the Y-axis before drawing it, this should not affect how much the line advances.
+   */
+  yOffset: number;
+}
+
+/**
+ * HarfBuzz compatible glyph info
+ */
+export interface GlyphInfo {
+  /**
+   * Glyph ID
+   */
+  glyphId: number;
+
+  /**
+   * First codepoint in the cluster this glyph was mapped from.
+   */
+  codepoint: number;
+
+  /**
+   * the index of the character in the original text that corresponds to this hb_glyph_info_t
+   * This is useful for mapping back from glyphs to characters.
+   */
+  cluster: number;
+}
+
+/**
+ * HarfBuzz compatible glyph extents
+ */
+export interface GlyphExtents {
+  /**
+   * The X offset from the origin to the leftmost part of the glyph.
+   * This is negative for right-to-left scripts.
+   */
+  xBearing: number;
+
+  /**
+   * The Y offset from the origin to the topmost part of the glyph.
+   * This is negative for bottom-to-top scripts.
+   */
+  yBearing: number;
+
+  /**
+   * Distance from the top extremum of the glyph to the bottom extremum.
+   * This is always positive.
+   */
+  width: number;
+
+  /**
+   * Distance from the left extremum of the glyph to the right extremum.
+   * This is always positive.
+   */
+  height: number;
+}
+
+export interface UnmappedCharacterInfo {
+  mapped: false;
+
+  /**
+   * The Unicode code point of the character.
+   */
+  codepoint: number;
+
+  /**
+   * The index of the character in the original text that corresponds to this hb_glyph_info_t
+   * This is useful for mapping back from glyphs to characters.
+   */
+  cluster: number;
+}
+
+export type MappedGlyphInfo = { mapped: true } & GlyphInfo &
+  GlyphPosition &
+  GlyphExtents;
+
+/**
+ * For performance reasons, all properties are required to reduce need for checking for undefined values.
+ */
+export interface FontShaperProps {
+  /**
+   * Letter spacing
+   *
+   * @default 0
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/letter-spacing
+   **/
+  letterSpacing: number;
+}
+
+export abstract class FontShaper {
+  /**
+   * Returns the glyph IDs of the next
+   *
+   * @remarks
+   * If this returns undefined, a glyph for the next codepoint(s) could not be found.
+   *
+   * @param codepoints
+   */
+  abstract shapeText(
+    props: FontShaperProps,
+    codepoints: PeekableIterator<number>,
+  ): Generator<MappedGlyphInfo | UnmappedCharacterInfo, void>;
+}

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

@@ -0,0 +1,159 @@
+/*
+ * 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 { describe, expect, it } from 'vitest';
+
+import { PeekableIterator } from '../../../renderers/SdfTextRenderer/internal/PeekableGenerator.js';
+import { SdfFontShaper, type SdfFontData } from './SdfFontShaper.js';
+import { getUnicodeCodepoints } from '../../../renderers/SdfTextRenderer/internal/getUnicodeCodepoints.js';
+import sdfData from 'test/mockdata/Ubuntu-Bold.msdf.json';
+
+// TODO: Need tests for
+// - mapped = false
+
+describe('SdfFontShaper', () => {
+  it('should be able to shape text.', () => {
+    const shaper = new SdfFontShaper(sdfData as unknown as SdfFontData);
+    const peekableCodepoints = new PeekableIterator(
+      getUnicodeCodepoints('Hi!'),
+    );
+    const glyphs = shaper.shapeText({ letterSpacing: 0 }, peekableCodepoints);
+    // H
+    expect(glyphs.next().value).toEqual({
+      mapped: true,
+      codepoint: 72,
+      glyphId: 72,
+      cluster: 0,
+      width: 28,
+      height: 33,
+      xAdvance: 30.828,
+      yAdvance: 0,
+      xOffset: 1,
+      yOffset: 5.592,
+      xBearing: 0,
+      yBearing: 0,
+    });
+    // i
+    expect(glyphs.next().value).toEqual({
+      mapped: true,
+      codepoint: 105,
+      glyphId: 105,
+      cluster: 1,
+      width: 11,
+      height: 36,
+      xAdvance: 12.138,
+      yAdvance: 0,
+      xOffset: 0,
+      yOffset: 2.592,
+      xBearing: 0,
+      yBearing: 0,
+    });
+    // !
+    expect(glyphs.next().value).toEqual({
+      mapped: true,
+      codepoint: 33,
+      glyphId: 33,
+      cluster: 2,
+      width: 12,
+      height: 34,
+      xAdvance: 12.012,
+      yAdvance: 0,
+      xOffset: 0,
+      yOffset: 5.592,
+      xBearing: 0,
+      yBearing: 0,
+    });
+    expect(glyphs.next().done).toBe(true);
+  });
+
+  it('should be able to shape text that we know have kerning pairs.', () => {
+    const shaper = new SdfFontShaper(sdfData as unknown as SdfFontData);
+    const peekableCodepoints = new PeekableIterator(
+      getUnicodeCodepoints('WeVo'),
+    );
+    const glyphs = shaper.shapeText({ letterSpacing: 0 }, peekableCodepoints);
+    // W
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 87,
+        xAdvance: 39.816,
+        xOffset: -1,
+      }),
+    );
+    // e
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 101,
+        xAdvance: 24.528,
+        xOffset: 0,
+      }),
+    );
+    // V
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 86,
+        xAdvance: 30.324,
+        xOffset: -2,
+      }),
+    );
+    // o
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 111,
+        xAdvance: 23.184,
+        xOffset: -2.31,
+      }),
+    );
+
+    expect(glyphs.next().done).toBe(true);
+  });
+
+  it('should be able to shape text with letterSpacing.', () => {
+    const shaper = new SdfFontShaper(sdfData as unknown as SdfFontData);
+    const peekableCodepoints = new PeekableIterator(
+      getUnicodeCodepoints('We!'),
+    );
+    const glyphs = shaper.shapeText({ letterSpacing: 5 }, peekableCodepoints);
+    // W
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 87,
+        xAdvance: 39.816,
+        xOffset: -1,
+      }),
+    );
+    // e
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 101,
+        xAdvance: 29.528,
+        xOffset: 5,
+      }),
+    );
+    // !
+    expect(glyphs.next().value).toEqual(
+      expect.objectContaining({
+        codepoint: 33,
+        xAdvance: 17.012,
+        xOffset: 5,
+      }),
+    );
+    expect(glyphs.next().done).toBe(true);
+  });
+});

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

@@ -0,0 +1,164 @@
+/*
+ * 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 { PeekableIterator } from '../../../renderers/SdfTextRenderer/internal/PeekableGenerator.js';
+import { SpecialCodepoints } from '../../../renderers/SdfTextRenderer/internal/SpecialCodepoints.js';
+import {
+  FontShaper,
+  type FontShaperProps,
+  type MappedGlyphInfo,
+  type UnmappedCharacterInfo,
+} from './FontShaper.js';
+
+/**
+ * Fast look up table for kernings
+ */
+type KerningTable = Record<
+  number,
+  Record<number, number | undefined> | undefined
+>;
+
+export class SdfFontShaper extends FontShaper {
+  private readonly data: SdfFontData;
+  private readonly kernings: KerningTable;
+
+  constructor(data: SdfFontData) {
+    super();
+    this.data = data;
+
+    const kernings: KerningTable = (this.kernings = {});
+    data.kernings.forEach((kerning) => {
+      const second = kerning.second;
+      const firsts = (kernings[second] = kernings[second] || {});
+      firsts[kerning.first] = kerning.amount;
+    });
+    this.kernings = kernings;
+  }
+
+  *shapeText(
+    props: FontShaperProps,
+    codepoints: PeekableIterator<number>,
+  ): Generator<MappedGlyphInfo | UnmappedCharacterInfo, void> {
+    let codepointResult: IteratorResult<number>;
+    let lastGlyphId: number | undefined = undefined;
+    while ((codepointResult = codepoints.peek()) && !codepointResult.done) {
+      const codepoint = codepointResult.value;
+      const glyph = this.data.chars.find((char) => char.id === codepoint);
+      codepoints.next();
+      if (glyph !== undefined) {
+        // We found a glyph for this codepoint
+        // Yield the mapped glyph info
+
+        /**
+         * Kerning includes any possible additional letter spacing
+         */
+        const kerning =
+          lastGlyphId !== undefined
+            ? (this.kernings[glyph.id]?.[lastGlyphId] || 0) +
+              props.letterSpacing
+            : 0;
+
+        lastGlyphId = glyph.id;
+        yield {
+          mapped: true,
+          glyphId: glyph.id,
+          codepoint,
+          cluster: codepoints.lastIndex,
+          xAdvance: glyph.xadvance + kerning,
+          yAdvance: 0,
+          xOffset: glyph.xoffset + kerning,
+          yOffset: glyph.yoffset,
+          xBearing: 0,
+          yBearing: 0,
+          width: glyph.width,
+          height: glyph.height,
+        };
+      } else {
+        // We didn't find a glyph for this codepoint
+        // Yield the unmapped codepoint info
+
+        // If this codepoint is a linebreak, we should reset the last glyph id
+        // so that the next glyph will not be kerned with the last glyph of the
+        // previous line.
+        if (codepoint === SpecialCodepoints.LINE_FEED) {
+          lastGlyphId = undefined;
+        }
+        yield {
+          mapped: false,
+          codepoint,
+          cluster: codepoints.lastIndex,
+        };
+      }
+    }
+  }
+}
+
+export interface SdfFontData {
+  pages: string[];
+  chars: Array<{
+    id: number;
+    char: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    xoffset: number;
+    yoffset: number;
+    xadvance: number;
+    page: number;
+    chnl: number;
+  }>;
+
+  kernings: Array<{
+    first: number;
+    second: number;
+    amount: number;
+  }>;
+  info: {
+    face: string;
+    size: number;
+    bold: number;
+    italic: number;
+    charset: string[];
+    unicode: number;
+    stretchH: number;
+    smooth: number;
+    aa: number;
+    padding: [number, number, number, number]; // [up, right, down, left]
+    spacing: [number, number]; // [horizontal, vertical]
+    outline: number;
+  };
+  common: {
+    lineHeight: number;
+    base: number;
+    scaleW: number;
+    scaleH: number;
+    pages: number;
+    packed: number;
+    alphaChnl: number;
+    redChnl: number;
+    greenChnl: number;
+    blueChnl: number;
+  };
+  distanceField: {
+    // msdf-bmfont-xml uses the string 'sdf' for single-channel SDF.
+    fieldType: 'sdf' | 'msdf';
+    distanceRange: number;
+  };
+}