@lightningjs/renderer 2.20.0 → 2.20.1

package/dist/src/core/text-rendering/TextRenderer.d.ts

@@ -0,0 +1,383 @@
+import type { CoreTextNodeProps } from '../CoreTextNode.js';
+import type { CoreRenderer } from '../renderers/CoreRenderer.js';
+import type { Stage } from '../Stage.js';
+export type TextBaseline = 'alphabetic' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
+export type TextVerticalAlign = 'top' | 'middle' | 'bottom';
+export type TextRenderers = 'canvas' | 'sdf';
+/**
+ * Structure mapping font family names to a set of font faces.
+ */
+export interface FontFamilyMap {
+    [familyName: string]: FontFace;
+}
+/**
+ * Font metrics used for layout and default line height calculations.
+ */
+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;
+}
+/**
+ * Normalized font metrics where values are expressed as a fraction of 1 EM.
+ */
+export interface NormalizedFontMetrics {
+    /**
+     * The distance, as a fraction of 1 EM, from the baseline to the highest point of the font.
+     */
+    ascender: number;
+    /**
+     * The distance, as a fraction of 1 EM, from the baseline to the lowest point of the font.
+     */
+    descender: number;
+    /**
+     * The additional space used in the calculation of the default line height as a fraction of 1 EM
+     */
+    lineGap: number;
+}
+/**
+ * Text renderer properties that are used in resolving appropriate font faces
+ *
+ * @remarks
+ * Extended by {@link TrProps}
+ */
+export interface TrFontProps {
+    /**
+     * Font Family
+     *
+     * @internalRemarks
+     * `fontFamily` is defined currently as single string, but in the future we may want to
+     * support multiple font family fallbacks, as this is supported by CSS / Canvas2d. We can
+     * do this in a backwards compatible way by unioning an array of strings to the
+     * `fontFamily` property.
+     */
+    fontFamily: string;
+    /**
+     * Font Style
+     *
+     * @remarks
+     * The font style to use when looking up the font face. This can be one of the
+     * following strings:
+     * - `'normal'`
+     * - `'italic'`
+     * - `'oblique'`
+     */
+    fontStyle: 'normal' | 'italic' | 'oblique';
+    /**
+     * Font Size
+     *
+     * @remarks
+     * The font size to use when looking up the font face.
+     *
+     * The font size is specified in pixels and is the height of the font's
+     * em-square. The em-square is essentially the height of the capital letters
+     * for the font. The actual height of the text can be larger than the
+     * specified font size, as the font may have ascenders and descenders that
+     * extend beyond the em-square.
+     *
+     * @default 16
+     */
+    fontSize: number;
+}
+export interface TrProps extends TrFontProps {
+    /**
+     * Text to display
+     *
+     * @default ''
+     */
+    text: string;
+    /**
+     * Text alignment
+     *
+     * @remarks
+     * Alignment of the text relative to it's contained bounds. For best results,
+     * use {@link contain} mode `'width'` or `'both'` and a set an explicit
+     * {@link width} for the text to be aligned within.
+     *
+     * @default 'left'
+     */
+    textAlign: 'left' | 'center' | 'right';
+    /**
+     * Color of text
+     *
+     * @remarks
+     * The color value is a number in the format 0xRRGGBBAA, where RR is the red
+     * component, GG is the green component, BB is the blue component, and AA is
+     * the alpha component.
+     *
+     * @default 0xffffffff (opaque white)
+     */
+    color: number;
+    x: number;
+    y: number;
+    maxWidth: number;
+    maxHeight: number;
+    /**
+     * Vertical offset for text
+     *
+     * @remarks
+     * The vertical offset of the text.
+     *
+     * @default 0
+     */
+    offsetY: number;
+    /**
+     * Letter spacing for text (in pixels)
+     *
+     * @remarks
+     * This property sets additional (or reduced, if value is negative) spacing
+     * between characters in the text.
+     *
+     * @default 0
+     */
+    letterSpacing: number;
+    /**
+     * Line height for text (in pixels)
+     *
+     * @remarks
+     * This property sets the height of each line. If set to `undefined`, the
+     * line height will be calculated based on the font and font size to be the
+     * minimal height required to completely contain a line of text.
+     *
+     * See: https://github.com/lightning-js/renderer/issues/170
+     *
+     * @default `undefined`
+     */
+    lineHeight: number;
+    /**
+     * Max lines for text
+     *
+     * @remarks
+     * This property sets max number of lines of a text paragraph.
+     * Not yet implemented in the SDF renderer.
+     *
+     * @default 0
+     */
+    maxLines: number;
+    /**
+     * Vertical Align for text when lineHeight > fontSize
+     *
+     * @remarks
+     * This property sets the vertical align of the text.
+     * Not yet implemented in the SDF renderer.
+     *
+     * @default middle
+     */
+    verticalAlign: TextVerticalAlign;
+    /**
+     * Overflow Suffix for text
+     *
+     * @remarks
+     * The suffix to be added when text is cropped due to overflow.
+     * Not yet implemented in the SDF renderer.
+     *
+     * @default "..."
+     */
+    overflowSuffix: string;
+    /**
+     * Word Break for text
+     *
+     * @remarks
+     * This property sets how words should break when reaching the end of a line.
+     *
+     * - `'overflow'`: Uses the Css/HTML normal word-break behavior, generally not used in app development.
+     * - `'break-all'`: To prevent overflow, word breaks should happen between any two characters.
+     * - `'break-word'`: To prevent overflow, word breaks should happen between words. If words are too long word breaks happen between any two characters.
+     *
+     * @default "break-word"
+     */
+    wordBreak: 'overflow' | 'break-all' | 'break-word';
+    /**
+     * contain mode for text
+     *
+     * @remarks
+     *
+     * This property sets how the text should be contained within its bounding box.
+     *
+     * - 'width': The text is contained within the specified maxWidth, horizontal position of text will adjust according to {@link textAlign}.
+     * - 'height': The text is contained within the specified maxHeight, vertical position of text will adjust according to {@link verticalAlign}.
+     * - 'both': The text is contained within both the specified maxWidth and maxHeight.
+     * - 'none': The text is not contained within any bounding box.
+     *
+     * @default 'none'
+     */
+    contain: 'width' | 'height' | 'both' | 'none';
+}
+/**
+ * Glyph layout information for WebGL rendering
+ */
+export interface GlyphLayout {
+    /**
+     * Unicode codepoint
+     */
+    codepoint: number;
+    /**
+     * Glyph ID in the font atlas
+     */
+    glyphId: number;
+    /**
+     * X position relative to text origin
+     */
+    x: number;
+    /**
+     * Y position relative to text origin
+     */
+    y: number;
+    /**
+     * Width of glyph in font units
+     */
+    width: number;
+    /**
+     * Height of glyph in font units
+     */
+    height: number;
+    /**
+     * X offset for glyph positioning
+     */
+    xOffset: number;
+    /**
+     * Y offset for glyph positioning
+     */
+    yOffset: number;
+    /**
+     * Atlas texture coordinates (normalized 0-1)
+     */
+    atlasX: number;
+    atlasY: number;
+    atlasWidth: number;
+    atlasHeight: number;
+}
+/**
+ * Complete text layout information for caching
+ */
+export interface TextLayout {
+    /**
+     * Individual glyph layouts
+     */
+    glyphs: GlyphLayout[];
+    /**
+     * Total text width
+     */
+    width: number;
+    /**
+     * Total text height
+     */
+    height: number;
+    /**
+     * Font scale factor
+     */
+    fontScale: number;
+    /**
+     * Line height
+     */
+    lineHeight: number;
+    /**
+     * Font family used
+     */
+    fontFamily: string;
+    /**
+     * distanceRange used
+     */
+    distanceRange: number;
+}
+export interface FontLoadOptions {
+    fontFamily: string;
+    metrics?: FontMetrics;
+    fontUrl?: string;
+    atlasUrl?: string;
+    atlasDataUrl?: string;
+}
+/**
+ * Measure Width of Text function to be defined in font handlers, used in TextLayoutEngine
+ */
+export type MeasureTextFn = (text: string, fontFamily: string, letterSpacing: number) => number;
+export interface FontHandler {
+    init: (c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void;
+    type: 'canvas' | 'sdf';
+    isFontLoaded: (fontFamily: string) => boolean;
+    loadFont: (stage: Stage, options: FontLoadOptions) => Promise<void>;
+    waitingForFont: (fontFamily: string, CoreTextNode: any) => void;
+    stopWaitingForFont: (fontFamily: string, CoreTextNode: any) => void;
+    getFontFamilies: () => FontFamilyMap;
+    canRenderFont: (trProps: TrProps) => boolean;
+    getFontMetrics: (fontFamily: string, fontSize: number) => NormalizedFontMetrics;
+    measureText: MeasureTextFn;
+}
+export interface TextRenderProps {
+    fontFamily: string;
+    fontSize: number;
+    color: number;
+    offsetY: number;
+    worldAlpha: number;
+    globalTransform: Float32Array;
+    clippingRect: unknown;
+    width: number;
+    height: number;
+    parentHasRenderTexture: boolean;
+    framebufferDimensions: unknown;
+    stage: Stage;
+}
+export interface TextRenderInfo {
+    width: number;
+    height: number;
+    hasRemainingText?: boolean;
+    remainingLines?: number;
+    imageData?: ImageData | null;
+    layout?: TextLayout;
+}
+export interface TextRenderer {
+    type: 'canvas' | 'sdf';
+    font: FontHandler;
+    renderText: (props: CoreTextNodeProps) => TextRenderInfo;
+    addQuads: (layout?: TextLayout) => Float32Array | null;
+    renderQuads: (renderer: CoreRenderer, layout: TextLayout, vertexBuffer: Float32Array, renderProps: TextRenderProps) => void;
+    init: (stage: Stage) => void;
+}
+/**
+ * Text line struct for text mapping
+ * 0 - text
+ * 1 - width
+ * 2 - truncated
+ * 3 - line offset x
+ * 4 - line offset y
+ */
+export type TextLineStruct = [string, number, boolean, number, number];
+/**
+ * Wrapped lines struct for text mapping
+ * 0 - line structs
+ * 1 - remaining lines
+ * 2 - remaining text
+ */
+export type WrappedLinesStruct = [TextLineStruct[], number, boolean];
+/**
+ * Wrapped lines struct for text mapping
+ * 0 - line structs
+ * 1 - remaining lines
+ * 2 - remaining text
+ * 3 - bare line height
+ * 4 - line height pixels
+ * 5 - effective width
+ * 6 - effective height
+ */
+export type TextLayoutStruct = [
+    TextLineStruct[],
+    number,
+    boolean,
+    number,
+    number,
+    number,
+    number
+];

package/dist/src/core/text-rendering/TextRenderer.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=TextRenderer.js.map

package/dist/src/core/text-rendering/TextRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextRenderer.js","sourceRoot":"","sources":["../../../../src/core/text-rendering/TextRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/src/core/text-rendering/Utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Returns CSS font setting string for use in canvas context.
+ *
+ * @param fontFace
+ * @param fontStyle
+ * @param fontSize
+ * @param precision
+ * @param defaultFontFace
+ * @returns
+ */
+export declare function getFontSetting(fontFace: string | string[], fontStyle: string, fontSize: number, precision: number, defaultFontFace: string): string;
+/**
+ * Returns true if the given character is a zero-width space.
+ *
+ * @param space
+ */
+export declare function hasZeroWidthSpace(space: string): boolean;
+/**
+ * Returns true if the given character is a zero-width space or a regular space.
+ *
+ * @param space
+ */
+export declare function isSpace(space: string): boolean;
+/**
+ * Converts a string into an array of tokens and the words between them.
+ *
+ * @param tokenRegex
+ * @param text
+ */
+export declare function tokenizeString(tokenRegex: RegExp, text: string): string[];

package/dist/src/core/text-rendering/Utils.js

@@ -0,0 +1,84 @@
+/*
+ * 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.
+ */
+const invisibleChars = /[\u200B\u200C\u200D\uFEFF\u00AD\u2060]/g;
+/**
+ * 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, fontStyle, fontSize, precision, defaultFontFace) {
+    let ff = fontFace;
+    if (!Array.isArray(ff)) {
+        ff = [ff];
+    }
+    const ffs = [];
+    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 hasZeroWidthSpace(space) {
+    return invisibleChars.test(space) === true;
+}
+/**
+ * Returns true if the given character is a zero-width space or a regular space.
+ *
+ * @param space
+ */
+export function isSpace(space) {
+    return hasZeroWidthSpace(space) || space === ' ';
+}
+/**
+ * Converts a string into an array of tokens and the words between them.
+ *
+ * @param tokenRegex
+ * @param text
+ */
+export function tokenizeString(tokenRegex, text) {
+    const delimeters = text.match(tokenRegex) || [];
+    const words = text.split(tokenRegex) || [];
+    const final = [];
+    for (let i = 0; i < words.length; i++) {
+        final.push(words[i], delimeters[i]);
+    }
+    final.pop();
+    return final.filter((word) => word != '');
+}
+//# sourceMappingURL=Utils.js.map

package/dist/src/core/text-rendering/Utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Utils.js","sourceRoot":"","sources":["../../../../src/core/text-rendering/Utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,cAAc,GAAG,yCAAyC,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,QAA2B,EAC3B,SAAiB,EACjB,QAAgB,EAChB,SAAiB,EACjB,eAAuB;IAEvB,IAAI,EAAE,GAAG,QAAQ,CAAC;IAElB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACZ,CAAC;IAED,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAClB,6EAA6E;QAC7E,gBAAgB;QAChB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,KAAK,GAAG,eAAe,CAAC;QAC1B,CAAC;QACD,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,SAAS,IAAI,QAAQ,GAAG,SAAS,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,GAAG,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,IAAY;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAE3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC;IACxC,CAAC;IACD,KAAK,CAAC,GAAG,EAAE,CAAC;IACZ,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AAC5C,CAAC"}