@mlightcad/mtext-renderer 0.11.6 → 0.11.8

package/lib/common/lruCache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Callback invoked when an entry is removed from the cache, either because it
+ * was evicted to make room for a new entry, replaced by a different value, or
+ * cleared explicitly.
+ *
+ * @typeParam K - The cache key type.
+ * @typeParam V - The cache value type.
+ */
+export type LRUCacheEvictHandler<K, V> = (key: K, value: V) => void;
+/**
+ * Simple least-recently-used cache with a fixed maximum size.
+ *
+ * Entries are ordered by access time: {@link get} and {@link set} move a key to
+ * the most-recently-used position. When the cache is full, the oldest entry is
+ * evicted before inserting a new one.
+ *
+ * @typeParam K - The cache key type.
+ * @typeParam V - The cache value type.
+ */
+export declare class LRUCache<K, V> {
+    private readonly maxSize;
+    private readonly onEvict?;
+    private readonly map;
+    /**
+     * Creates an LRU cache with the given capacity and optional eviction handler.
+     *
+     * @param maxSize - Maximum number of entries to retain. Defaults to 4096.
+     * @param onEvict - Optional callback invoked for each evicted or replaced value.
+     */
+    constructor(maxSize?: number, onEvict?: LRUCacheEvictHandler<K, V>);
+    /**
+     * Returns the value for `key` and marks it as most recently used.
+     *
+     * @param key - The cache key to look up.
+     * @returns The cached value, or `undefined` if the key is not present.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Stores `value` under `key` and marks it as most recently used.
+     *
+     * If the key already exists, its previous value is passed to {@link onEvict}
+     * when the new value differs. If the cache is at capacity, the least recently
+     * used entry is evicted before the new entry is inserted.
+     *
+     * @param key - The cache key to set.
+     * @param value - The value to store.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Returns whether `key` exists in the cache without updating its recency.
+     *
+     * @param key - The cache key to test.
+     * @returns True if the key is present; otherwise, false.
+     */
+    has(key: K): boolean;
+    /**
+     * Removes all entries from the cache.
+     *
+     * If an {@link onEvict} handler was provided, it is invoked once per entry
+     * before the internal map is cleared.
+     */
+    clear(): void;
+}

package/lib/font/baseTextShape.d.ts

@@ -14,4 +14,8 @@ export declare abstract class BaseTextShape extends THREE.Shape {
      * @returns A THREE.js BufferGeometry representing the text shape
      */
     abstract toGeometry(): THREE.BufferGeometry;
+    /**
+     * Whether the shape has drawable stroke or mesh geometry (not advance-only).
+     */
+    hasStrokeGeometry(): boolean;
 }

package/lib/font/charGeometryCache.d.ts

@@ -1,10 +1,11 @@
 import * as THREE from 'three';
 /**
  * Manages caching of font character geometries to improve text rendering performance.
+ * Uses an LRU policy so memory stays bounded when many (code, size) pairs are loaded.
  */
 export declare class CharGeometryCache {
-    private cache;
-    constructor();
+    private readonly cache;
+    constructor(maxSize?: number);
     /**
      * Returns true if the geometry of the specified character code exists in the cache.
      * Otherwise, returns false.

package/lib/font/meshTextShape.d.ts

@@ -22,6 +22,8 @@ export declare class MeshTextShape extends BaseTextShape {
      * @returns A THREE.js BufferGeometry representing the text shape
      */
     toGeometry(): THREE.BufferGeometry;
+    /** @inheritdoc */
+    hasStrokeGeometry(): boolean;
     /**
      * Calculates the width of a character in the font.
      * @param char - The character to calculate width for

package/lib/font/shxFont.d.ts

@@ -1,7 +1,9 @@
-import { ShxFontData } from '@mlightcad/shx-parser';
+import { ShxFontData, ShxFontMetrics } from '@mlightcad/shx-parser';
 import { BaseFont } from './baseFont';
 import { FontData } from './font';
 import { ShxTextShape } from './shxTextShape';
+/** Scaled SHX font layout metrics (cap height, cell width, etc.) from `@mlightcad/shx-parser`. */
+export type { ShxFontMetrics } from '@mlightcad/shx-parser';
 /**
  * ShxFont is a class that extends BaseFont and represents a SHX font.
  * It provides methods to generate shapes for text and retrieve character shapes.
@@ -9,68 +11,92 @@ import { ShxTextShape } from './shxTextShape';
 export declare class ShxFont extends BaseFont {
     /** Internal shx font instance */
     private readonly font;
+    /** The type of font; always `'shx'`. */
     readonly type = "shx";
+    /** Parsed SHX font data used for glyph lookup and layout metrics. */
     readonly data: ShxFontData;
+    /** Cached layout-ready {@link ShxTextShape} instances keyed by code and size. */
+    private readonly layoutShapeCache;
+    /** Cached BIGFONT character encodings keyed by input character. */
+    private readonly codeCache;
+    /**
+     * Creates a new SHX font wrapper.
+     * @param fontData - Font metadata and binary SHX data used to initialize the font.
+     */
     constructor(fontData: FontData);
     /**
-     * Return true if this font contains glyph of the specified character. Otherwise, return false.
-     * @param char - The character to check
-     * @returns True if this font contains glyph of the specified character. Otherwise, return false.
+     * Returns whether the font contains a glyph for the given character.
+     * @param char - The character to look up.
+     * @returns True if the font contains the character; otherwise, false.
      */
     hasChar(char: string): boolean;
     /**
-     * Return true if this font contains glyph of the specified character code. Otherwise, return false.
-     * @param code - The character code to check
-     * @returns True if this font contains glyph of the specified character code. Otherwise, return false.
+     * Returns whether the font contains a glyph for the given character code.
+     * @param code - The character code to look up.
+     * @returns True if the font contains the code point; otherwise, false.
      */
     hasCode(code: number): boolean;
     /**
-     * Horizontal advance for the space character (ASCII 32) at the given size.
-     * Uses the SHX glyph pen advance when defined; otherwise falls back to half the
-     * text height (common for AutoCAD SHX fonts).
+     * Computes the horizontal advance for a space at the requested size.
+     * @param size - The requested font size.
+     * @returns The width of the space advance.
      */
     getSpaceAdvance(size: number): number;
+    /**
+     * Converts a text string into a list of SHX text shapes.
+     * @param text - The text to convert.
+     * @param size - The requested font size.
+     * @returns An array of generated SHX text shapes.
+     */
     generateShapes(text: string, size: number): ShxTextShape[];
     /**
-     * SHX font always has fixed scale factor 1.
-     * @returns Always return value 1
+     * Returns the scale factor used by the SHX font implementation.
+     * @returns Always returns 1 for SHX fonts.
      */
     getScaleFactor(): number;
+    /**
+     * Gets the scaled layout metrics for the font at the requested size.
+     * @param size - The requested font size.
+     * @returns The SHX font metrics for the given size.
+     */
+    getFontMetrics(size: number): ShxFontMetrics;
     /**
      * Gets the shape data for a specific character at a given size.
-     * If the font type is BIGFONT, please use getCodeShape to get the shape data
-     * because the character code for BIGFONT isn't unicode.
-     * @param char - The character to get the shape for
-     * @param size - The desired size of the character
-     * @returns The shape data for the character, or undefined if not found
+     * @param char - The character to look up.
+     * @param size - The requested font size.
+     * @returns The shape data for the character, or undefined if not found.
      */
     getCharShape(char: string, size: number): ShxTextShape | undefined;
     /**
      * Gets the shape data for a specific character code at a given size.
-     * The passed code must the code stored in font instead of unicode.
-     * - Unicode shx font uses unicode as character code.
-     * - Bigfont uses a custom encoding for double-byte characters.
-     * @param code - The character code to get the shape for
-     * @param size - The desired size of the character
-     * @returns The shape data for the character code, or undefined if not found
+     * @param code - The character code to look up.
+     * @param size - The requested font size.
+     * @returns The shape data for the code, or undefined if not found.
      */
     getCodeShape(code: number, size: number): ShxTextShape | undefined;
     /**
-     * Gets the shape data for a named SHX shape at a given size.
-     *
-     * Shape names are matched case-insensitively via the underlying SHX parser.
+     * Gets the shape data for a named SHX shape at the requested size.
+     * @param name - The SHX shape name to look up.
+     * @param size - The requested font size.
+     * @returns The matching shape, or undefined if unavailable.
      */
     getShapeByName(name: string, size: number): ShxTextShape | undefined;
-    /** True when the SHX glyph has drawable strokes or a non-zero pen advance. */
+    /**
+     * Checks whether a parsed SHX shape contains renderable strokes.
+     * @param shape - The shape to inspect.
+     * @returns True when the shape has at least one renderable segment.
+     */
     private static hasRenderableStrokes;
     /**
-     * For an unsupported char, use "？" as a replacement.
+     * Gets the fallback text shape used for missing characters.
+     * @param size - The requested font size.
+     * @returns The fallback shape, or undefined if it cannot be built.
      */
     getNotFoundTextShape(size: number): ShxTextShape | undefined;
     /**
-     * Gets encoded code of the specified character according to font character encoding
-     * @param char - The character to get its code
-     * @returns Returns encoded code of the specified character
+     * Resolves the internal SHX character code for a given Unicode character.
+     * @param char - The input character.
+     * @returns The internal SHX code used for lookup.
      */
     private getCode;
 }

package/lib/font/shxTextShape.d.ts

@@ -13,27 +13,32 @@ export declare class ShxTextShape extends BaseTextShape {
     private readonly shape;
     private readonly font;
     private readonly fontSize;
+    /** Lazily built geometry for this layout-ready shape instance. */
+    private geometry?;
     /**
-     * Creates a new instance of ShxTextShape
-     * @param code - The character code this shape represents
-     * @param shape - The shape data for this character
+     * Creates a new SHX text shape wrapper.
+     * @param code - The character code represented by this shape.
+     * @param fontSize - The font size used to resolve the shape advance width.
+     * @param shape - The parsed SHX shape data.
+     * @param font - The SHX font instance that owns the shape.
      */
     constructor(code: number, fontSize: number, shape: ShxShape, font: ShxFont);
     /**
-     * Resolves horizontal advance for SHX glyphs.
-     *
-     * - Unicode / shapes fonts: prefer the pen-down end X (lastPoint), which matches
-     *   AutoCAD's advance for single-byte SHX.
-     * - Big fonts (CJK): advance is the scaled font cell width (content.width /
-     *   content.height * fontSize). Glyph bbox or lastPoint can be narrower than the
-     *   cell; using only bbox caused successive Han characters to overlap visually.
+     * Computes the width of the shape from its bounding box.
+     * @returns The width of the shape's bounding box.
      */
-    private resolveAdvanceWidth;
     protected calcWidth(): number;
+    /**
+     * Returns a translated copy of this shape.
+     * @param offset - The offset to apply to the shape.
+     * @returns A new shape shifted by the given offset.
+     */
     offset(offset: Point): ShxTextShape;
     /**
-     * Converts the text shape to a THREE.js geometry
-     * @returns A THREE.js BufferGeometry representing the text shape
+     * Converts the text shape to a THREE.js geometry.
+     * @returns A BufferGeometry representing the text shape.
      */
     toGeometry(): THREE.BufferGeometry<THREE.NormalBufferAttributes>;
+    /** @inheritdoc */
+    hasStrokeGeometry(): boolean;
 }

package/lib/font/textGeometryBuilder.d.ts

@@ -0,0 +1,47 @@
+import * as THREE from 'three';
+/**
+ * One cached glyph geometry plus the world transform to apply at merge time.
+ */
+export interface TransformedLineGeometryEntry {
+    /** The source line-segment geometry for a single glyph. */
+    geometry: THREE.BufferGeometry;
+    /** The 4×4 transform matrix applied to each vertex before merging. */
+    matrix: THREE.Matrix4;
+}
+/**
+ * Builds a single line-segment {@link THREE.BufferGeometry} from many transformed glyph sources.
+ * Avoids per-character geometry allocation before merge.
+ */
+export declare class TextGeometryBuilder {
+    /**
+     * Merges indexed or non-indexed line geometries into one non-indexed {@link THREE.BufferGeometry}
+     * suitable for {@link THREE.LineSegments}.
+     * @param entries Glyph geometries paired with their world transforms.
+     * @returns A single non-indexed line geometry containing all transformed segments.
+     */
+    static mergeLineGeometries(entries: TransformedLineGeometryEntry[]): THREE.BufferGeometry;
+    /**
+     * Counts how many line segments a geometry represents.
+     * Indexed geometries use index pairs; non-indexed geometries use consecutive position pairs.
+     * @param geometry The line geometry to inspect.
+     * @returns The number of line segments (each segment is two vertices).
+     */
+    private static countLineSegments;
+    /**
+     * Applies a transform matrix to a single line geometry and returns a new non-indexed copy.
+     * @param geometry The source line geometry.
+     * @param matrix The transform applied to every vertex.
+     * @returns A new non-indexed line geometry with transformed positions.
+     */
+    private static applyMatrixToLineGeometry;
+    /**
+     * Writes transformed line-segment vertices from a source geometry into a flat position buffer.
+     * Supports both indexed and non-indexed source geometries.
+     * @param geometry The source line geometry.
+     * @param matrix The transform applied to each vertex before writing.
+     * @param output The destination `Float32Array` (xyz per vertex).
+     * @param outputOffset The index in `output` at which writing begins.
+     * @returns The next write offset after all segments have been written.
+     */
+    private static writeTransformedLineSegments;
+}