@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta20

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

@@ -1,139 +0,0 @@
-/*
- * 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

@@ -1,173 +0,0 @@
-/*
- * 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';
-
-const glyphMap = new Map<number, SdfFontData['chars'][0]>();
-sdfData.chars.forEach((glyph) => {
-  glyphMap.set(glyph.id, glyph);
-});
-
-// TODO: Need tests for
-// - mapped = false
-
-describe('SdfFontShaper', () => {
-  it('should be able to shape text.', () => {
-    const shaper = new SdfFontShaper(
-      sdfData as unknown as SdfFontData,
-      glyphMap,
-    );
-    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,
-      glyphMap,
-    );
-    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,
-      glyphMap,
-    );
-    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

@@ -1,171 +0,0 @@
-/*
- * 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 type { FontMetrics } from '../../TrFontFace.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 glyphMap: Map<number, SdfFontData['chars'][0]>;
-  private readonly kernings: KerningTable;
-
-  constructor(
-    data: SdfFontData,
-    glyphMap: Map<number, SdfFontData['chars'][0]>,
-  ) {
-    super();
-    this.data = data;
-    this.glyphMap = glyphMap;
-
-    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.glyphMap.get(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;
-  };
-  lightningMetrics?: FontMetrics;
-}

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

@@ -1,187 +0,0 @@
-/*
- * 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 { EventEmitter } from '../../../common/EventEmitter.js';
-
-/**
- * Augmentable map of font type IDs to font types
- *
- * @example
- * ```ts
- * declare module './TrFontFace' {
- *   interface TrFontFaceMap {
- *     canvas: CanvasTrFontFace;
- *   }
- * }
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface TrFontFaceMap {}
-
-/**
- * Descriptors defining a font face.
- *
- * Used when selecting a font face from a font family.
- *
- * @remarks
- * Based on the `@font-face` CSS rule. Not all descriptors are supported by all
- * text renderers.
- *
- * @see https://www.w3.org/TR/css-fonts-3/#font-face-rule
- */
-export interface TrFontFaceDescriptors {
-  style: 'normal' | 'italic' | 'oblique';
-  weight: 'normal' | 'bold' | number;
-  stretch:
-    | 'normal'
-    | 'ultra-condensed'
-    | 'extra-condensed'
-    | 'condensed'
-    | 'semi-condensed'
-    | 'semi-expanded'
-    | 'expanded'
-    | 'extra-expanded'
-    | 'ultra-expanded';
-  unicodeRange?: string;
-  display?: FontDisplay;
-  featureSettings?: 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(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',
-      weight: 'normal',
-      stretch: 'normal',
-      ...descriptors,
-    };
-  }
-
-  /**
-   * Convert a TrFontFaceDescriptors to a FontFaceDescriptors which differ slightly
-   *
-   * @param descriptors
-   * @returns
-   */
-  public static convertToCssFontFaceDescriptors(
-    descriptors: TrFontFaceDescriptors,
-  ): FontFaceDescriptors {
-    return {
-      style: descriptors.style,
-      weight:
-        typeof descriptors.weight === 'number'
-          ? `${descriptors.weight}`
-          : descriptors.weight,
-      stretch: descriptors.stretch,
-      unicodeRange: descriptors.unicodeRange,
-      featureSettings: descriptors.featureSettings,
-      display: descriptors.display,
-    };
-  }
-}