@lightningjs/renderer 2.9.2 → 2.11.0

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

@@ -1,187 +1,187 @@
-/*
- * 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,
-    };
-  }
-}
+/*
+ * 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,
+    };
+  }
+}

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

@@ -1,94 +1,94 @@
-/*
- * 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 {
-  TrFontFace,
-  type TrFontFaceDescriptors,
-  type TrFontFaceOptions,
-} from './TrFontFace.js';
-
-declare module './TrFontFace.js' {
-  interface TrFontFaceMap {
-    web: WebTrFontFace;
-  }
-}
-
-export interface WebTrFontFaceOptions extends TrFontFaceOptions {
-  fontUrl: string;
-}
-
-export class WebTrFontFace extends TrFontFace {
-  public readonly fontFace: FontFace;
-  public readonly fontUrl: string;
-
-  constructor(options: WebTrFontFaceOptions) {
-    super(options);
-
-    const { fontFamily, fontUrl } = options;
-
-    // Filter out parentheses from fontUrl
-    const fontUrlWithoutParentheses = fontUrl.replace(/\(|\)/g, '');
-
-    // Defaults for descriptors resolved in the super constructor
-    const determinedDescriptors = this.descriptors;
-
-    // Convert TrFontFaceDescriptors to CSS FontFaceDescriptors
-    let cssDescriptors: FontFaceDescriptors = {
-      style: determinedDescriptors.style,
-      weight:
-        typeof determinedDescriptors.weight === 'number'
-          ? `${determinedDescriptors.weight}`
-          : determinedDescriptors.weight,
-      stretch: determinedDescriptors.stretch,
-      unicodeRange: determinedDescriptors.unicodeRange,
-      featureSettings: determinedDescriptors.featureSettings,
-      display: determinedDescriptors.display,
-    };
-
-    for (const k in cssDescriptors) {
-      const key = k as keyof FontFaceDescriptors;
-      if (cssDescriptors[key] === undefined) {
-        delete cssDescriptors[key];
-      }
-    }
-
-    const fontFace = new FontFace(
-      fontFamily,
-      `url(${fontUrlWithoutParentheses})`,
-      cssDescriptors,
-    );
-
-    if (fontUrlWithoutParentheses.length > 0) {
-      fontFace
-        .load()
-        .then(() => {
-          (this.loaded as boolean) = true;
-          this.emit('loaded');
-        })
-        .catch(console.error);
-    } else {
-      // Default font
-      (this.loaded as boolean) = true;
-      this.emit('loaded');
-    }
-
-    this.fontFace = fontFace;
-    this.fontUrl = fontUrl;
-  }
-}
+/*
+ * 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 {
+  TrFontFace,
+  type TrFontFaceDescriptors,
+  type TrFontFaceOptions,
+} from './TrFontFace.js';
+
+declare module './TrFontFace.js' {
+  interface TrFontFaceMap {
+    web: WebTrFontFace;
+  }
+}
+
+export interface WebTrFontFaceOptions extends TrFontFaceOptions {
+  fontUrl: string;
+}
+
+export class WebTrFontFace extends TrFontFace {
+  public readonly fontFace: FontFace;
+  public readonly fontUrl: string;
+
+  constructor(options: WebTrFontFaceOptions) {
+    super(options);
+
+    const { fontFamily, fontUrl } = options;
+
+    // Filter out parentheses from fontUrl
+    const fontUrlWithoutParentheses = fontUrl.replace(/\(|\)/g, '');
+
+    // Defaults for descriptors resolved in the super constructor
+    const determinedDescriptors = this.descriptors;
+
+    // Convert TrFontFaceDescriptors to CSS FontFaceDescriptors
+    let cssDescriptors: FontFaceDescriptors = {
+      style: determinedDescriptors.style,
+      weight:
+        typeof determinedDescriptors.weight === 'number'
+          ? `${determinedDescriptors.weight}`
+          : determinedDescriptors.weight,
+      stretch: determinedDescriptors.stretch,
+      unicodeRange: determinedDescriptors.unicodeRange,
+      featureSettings: determinedDescriptors.featureSettings,
+      display: determinedDescriptors.display,
+    };
+
+    for (const k in cssDescriptors) {
+      const key = k as keyof FontFaceDescriptors;
+      if (cssDescriptors[key] === undefined) {
+        delete cssDescriptors[key];
+      }
+    }
+
+    const fontFace = new FontFace(
+      fontFamily,
+      `url(${fontUrlWithoutParentheses})`,
+      cssDescriptors,
+    );
+
+    if (fontUrlWithoutParentheses.length > 0) {
+      fontFace
+        .load()
+        .then(() => {
+          (this.loaded as boolean) = true;
+          this.emit('loaded');
+        })
+        .catch(console.error);
+    } else {
+      // Default font
+      (this.loaded as boolean) = true;
+      this.emit('loaded');
+    }
+
+    this.fontFace = fontFace;
+    this.fontUrl = fontUrl;
+  }
+}