@mlightcad/mtext-renderer 0.11.6 → 0.11.8

package/lib/renderer/mtextProcessor.d.ts

@@ -49,22 +49,39 @@ export interface MTextFormatOptions {
     collectCharBoxes?: boolean;
 }
 /**
- * This class represents lines of texts.
+ * Converts parsed MText tokens into positioned THREE.js geometry.
+ *
+ * Owns line breaking, inline/paragraph formatting, stack fractions, alignment,
+ * and per-character bounding boxes used for picking.
  */
 export declare class MTextProcessor {
+    /** Active text style (font, height, oblique, big font, etc.). */
     private _style;
+    /** Layer/block color resolution settings for ByLayer and ByBlock colors. */
     private _colorSettings;
+    /** Factory for mesh and line materials used when flushing geometry batches. */
     private _styleManager;
+    /** Resolves font files, glyph shapes, and font-format-specific metrics. */
     private _fontManager;
+    /** Layout and formatting options supplied at construction time. */
     private _options;
+    /** Accumulated vertical extent of completed lines, excluding the active line. */
     private _totalHeight;
+    /** Horizontal pen position within the current visual line. */
     private _hOffset;
+    /** Maximum logical pen advance seen across all processed visual lines. */
     private _maxLineAdvance;
+    /** Vertical baseline position of the current visual line. */
     private _vOffset;
+    /** Number of visual lines processed so far (1-based while rendering). */
     private _lineCount;
+    /** THREE.js objects created for the current visual line before alignment. */
     private _currentLineObjects;
+    /** Saved {@link RenderContext} snapshots for nested `{}` formatting groups. */
     private _contextStack;
+    /** Active inline formatting and font metric state. */
     private _currentContext;
+    /** Largest font size encountered on the current visual line. */
     private _maxFontSize;
     /**
      * The current horizontal alignment for the paragraph.
@@ -76,25 +93,45 @@ export declare class MTextProcessor {
      * so it persists until explicitly changed by another paragraph alignment command.
      */
     private _currentHorizontalAlignment;
+    /** Whether the most recently appended char box targeted mesh or line geometry. */
     private _lastCharBoxTarget;
+    /** True once a visible glyph has been placed on the current visual line. */
     private _lineHasRenderableChar;
+    /**
+     * Font size recorded when advancing from an empty line; used to correct
+     * vertical position when the first glyph on the next line uses a different height.
+     */
     private _pendingEmptyLineFontSizeAdjust?;
+    /** Vertical layout metadata for each completed visual line. */
     private _lineLayouts;
+    /** Character indices where automatic visual line breaks occurred. */
     private _lineBreakIndices;
+    /** Running count of logical characters emitted into flushed geometry groups. */
     private _processedCharCount;
+    /** Line glyph entries collected for batch geometry merge within a style segment. */
+    private _lineBatchEntries;
+    /** Current paragraph first-line indent in drawing units. */
     private _currentIndent;
+    /** Current paragraph left margin in drawing units. */
     private _currentLeftMargin;
+    /** Current paragraph right margin in drawing units. */
     private _currentRightMargin;
     /**
      * Construct one instance of this class and initialize some properties with default values.
      * @param style Input text style
+     * @param colorSettings Layer/block color resolution settings
      * @param styleManager Input text style manager instance
      * @param fontManager Input font manager instance
      * @param options Input formating options
      */
     constructor(style: TextStyle, colorSettings: ColorSettings, styleManager: StyleManager, fontManager: FontManager, options: MTextFormatOptions);
+    /**
+     * Font manager used to resolve glyphs, shapes, and font metrics.
+     */
     get fontManager(): FontManager;
+    /** Style manager used to create mesh and line materials. */
     get styleManager(): StyleManager;
+    /** Active CAD text style for the entity being rendered. */
     get textStyle(): TextStyle;
     /**
      * Total height of all lines of text
@@ -180,24 +217,31 @@ export declare class MTextProcessor {
      * All of THREE.js objects in current line. It contains objects in all of sections of this line.
      */
     get currentLineObjects(): THREE.Object3D<THREE.Object3DEventMap>[];
+    /** Per-line vertical layout records accumulated during rendering. */
     get lineLayouts(): LineLayout[];
     /**
      * The horizental offset of current character in this line
      */
     get hOffset(): number;
+    /** @param value New horizontal pen position within the current line. */
     set hOffset(value: number);
     /**
      * The vertical offset of current character in this line
      */
     get vOffset(): number;
+    /** @param value New vertical baseline position for the current line. */
     set vOffset(value: number);
+    /** Current paragraph first-line indent in drawing units. */
     get currentIndent(): number;
+    /** Current paragraph left margin in drawing units. */
     get currentLeftMargin(): number;
+    /** Current paragraph right margin in drawing units. */
     get currentRightMargin(): number;
+    /** Usable line width after subtracting left and right paragraph margins. */
     get maxLineWidth(): number;
     /**
      * Process text format information
-     * @param item Input mtext inline codes
+     * @param item Inline formatting command or restore snapshot from the parser.
      */
     processFormat(item: ChangedProperties): void;
     /**
@@ -214,6 +258,8 @@ export declare class MTextProcessor {
      * - width/height/tracking factors
      * - paragraph alignment and margins
      * - underline/overline/strike-through flags
+     *
+     * @param changes Full property snapshot to apply to the current render context.
      */
     private applyPropertyChanges;
     /**
@@ -272,15 +318,29 @@ export declare class MTextProcessor {
      * and starting a new line with indent applied.
      * @param geometries Current text geometries to process
      * @param lineGeometries Current line geometries to process
+     * @param meshCharBoxes Mesh char boxes to flush with the current line
+     * @param lineCharBoxes Line char boxes to flush with the current line
      * @param group The group to add processed geometries to
      */
     private startNewParagraph;
     /**
      * Renders one SHX shape glyph for AutoCAD SHAPE entities.
      *
-     * The glyph is resolved by {@link shapeName} first, then by {@link shapeNumber}.
+     * @param shapeName Optional SHX shape name from the SHAPE entity.
+     * @param shapeNumber Optional SHX shape number from the SHAPE entity.
+     * @returns A single styled THREE.js object for the resolved shape, or `undefined` when lookup fails.
      */
     processShapeGlyph(shapeName?: string, shapeNumber?: number): THREE.Object3D | undefined;
+    /**
+     * Resolves a SHX shape glyph by name and/or numeric code for SHAPE entities.
+     *
+     * Name lookup is attempted first; numeric lookup is used when the name is absent
+     * or does not match. Unlike MText, failed SHAPE lookups do not fall back to `?`.
+     *
+     * @param shapeName Optional SHX shape name.
+     * @param shapeNumber Optional SHX shape number.
+     * @returns Resolved shape and display label, or `undefined` when not found.
+     */
     private resolveShapeGlyph;
     /**
      * Builds geometry for one glyph and appends it to the output buffers.
@@ -288,47 +348,235 @@ export declare class MTextProcessor {
      * @returns Horizontal advance width after width factor and oblique skew.
      */
     private buildShapeGeometry;
+    /**
+     * Builds the world transform for one glyph (width factor, oblique, bold, translate).
+     *
+     * @param charX Horizontal glyph origin in drawing space.
+     * @param charY Vertical glyph origin in drawing space.
+     * @param charHeight Layout font height used for oblique advance calculation.
+     * @returns Composite transform matrix and extra horizontal advance introduced by oblique skew.
+     */
+    private buildCharTransformMatrix;
+    /**
+     * Appends one glyph's geometry to the active batch buffers and optional char boxes.
+     *
+     * Mesh fonts (`ShapeGeometry`) are transformed immediately; line fonts are queued in
+     * {@link _lineBatchEntries} for later merge via {@link TextGeometryBuilder.mergeLineGeometries}.
+     *
+     * @param shape Source text shape for the glyph.
+     * @param label Character label stored on geometry and char boxes.
+     * @param canonical Untransformed glyph geometry from the font.
+     * @param matrix World transform to apply to the glyph.
+     * @param geometries Accumulator for mesh (`ShapeGeometry`) primitives.
+     * @param meshCharBoxes Accumulator for mesh-glyph picking boxes.
+     * @param lineCharBoxes Accumulator for line-glyph picking boxes.
+     */
+    private appendCharGeometry;
+    /**
+     * Creates a two-point line decoration geometry (underline, overline, strike-through).
+     *
+     * @param lineGeometries Accumulator for line-based decoration geometry.
+     * @param vertices Six floats: start `(x,y,z)` and end `(x,y,z)` in drawing space.
+     */
+    private pushDecorationLine;
     /**
      * Render the specified texts
-     * @param item Input texts to render
+     * @param tokens Parsed MText token stream from the parser.
+     * @returns A {@link THREE.Group} containing merged line/mesh objects and layout metadata.
      */
     processText(tokens: Generator<MTextToken>): THREE.Group<THREE.Object3DEventMap>;
+    /**
+     * Flushes pending geometry and char boxes into a styled THREE.js object on `group`.
+     *
+     * When only char boxes exist (spaces, empty lines), creates a marker object with
+     * layout metadata and no visible geometry.
+     *
+     * @param geometries Pending mesh geometries for the current style segment.
+     * @param lineGeometries Pending line geometries and decorations for the current style segment.
+     * @param meshCharBoxes Mesh-glyph char boxes collected since the last flush.
+     * @param lineCharBoxes Line-glyph char boxes collected since the last flush.
+     * @param group Parent group receiving the created object.
+     * @param charBoxType Char-box classification stored on the flushed object.
+     */
     private processGeometries;
+    /**
+     * Lays out and renders one parser word token, breaking to a new visual line when needed.
+     *
+     * @param word Character sequence for a single word token.
+     * @param geometries Mesh geometry accumulator for the active style segment.
+     * @param lineGeometries Line geometry accumulator for the active style segment.
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     */
     private processWord;
+    /**
+     * Renders an MText stack token (`\S...;`) as fraction, superscript, subscript, or tolerance layout.
+     *
+     * @param stackData Parser stack payload: `[numerator, denominator, divider]`.
+     * @param geometries Mesh geometry accumulator.
+     * @param lineGeometries Line geometry accumulator.
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     */
     private processStack;
+    /**
+     * Records a zero-height char box for a stack fraction divider in logical char order.
+     *
+     * @param startX Horizontal start of the fraction bar in drawing space.
+     * @param currentVOffset Vertical baseline of the stack relative to the main line.
+     * @param width Horizontal extent of the fraction bar.
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     */
     private recordStackDivider;
     /**
      * Convert a legacy top-anchored vOffset (used by stack/sub/sup logic) into
      * the current baseline-anchored coordinate system.
+     *
+     * @param legacyTopAlignedVOffset Vertical position in the legacy top-anchored system.
+     * @param fontSize Font size associated with the legacy offset.
+     * @returns Baseline-anchored vertical offset for the current layout model.
      */
     private convertTopAlignedVOffset;
+    /**
+     * Advances the pen by one space width and optionally records a space char box.
+     *
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     */
     private processBlank;
+    /**
+     * Records the character index where a visual line break occurs.
+     *
+     * @param meshCharBoxes Optional pending mesh char boxes included in the break index.
+     * @param lineCharBoxes Optional pending line char boxes included in the break index.
+     */
     private recordVisualLineBreak;
+    /**
+     * Appends vertical layout metadata for the current visual line to {@link _lineLayouts}.
+     */
     private recordCurrentLineLayout;
+    /**
+     * Renders a percent-control-code symbol (`%%...`) or its literal fallback character.
+     *
+     * @param data Parser payload describing the percent symbol kind and lookup data.
+     * @param geometries Mesh geometry accumulator.
+     * @param lineGeometries Line geometry accumulator.
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     */
     private processPercentSymbol;
+    /**
+     * Renders one character glyph, including decorations and line-break handling.
+     *
+     * Missing glyphs are treated as spaces. When the pen exceeds {@link maxLineWidth},
+     * a visual line break is recorded before placement.
+     *
+     * @param char Character to render.
+     * @param geometries Mesh geometry accumulator.
+     * @param lineGeometries Line geometry accumulator.
+     * @param meshCharBoxes Mesh char-box accumulator.
+     * @param lineCharBoxes Line char-box accumulator.
+     * @param shapeOverride Optional pre-resolved shape (used by percent symbols and stacks).
+     */
     private processChar;
+    /**
+     * Applies horizontal alignment to the final visual line after all tokens are processed.
+     */
     private processLastLine;
+    /**
+     * Initializes line metric state from the current font and default text height.
+     */
     private initLineParams;
+    /**
+     * Switches the active font family and recomputes derived line metrics.
+     *
+     * @param fontName Font family name from an inline `\f` command or text style.
+     */
     private changeFont;
     /**
-     * Calcuate font size, line space, line height and other parameters.
+     * Recalculates font scale factor and drawing-space font size from defaults and scale factors.
+     *
+     * @param newFontHeight Optional absolute font height override in drawing units.
      */
     private calcuateLineParams;
     /**
-     * Get text shape of the specified character
-     * @param char Input one character
-     * @returns Return the text shape of the specified character
+     * Returns whether a shape contributes visible stroke or mesh geometry for rendering.
+     *
+     * @param shape Candidate text shape.
+     * @param char Character being resolved (spaces may still be renderable when width > 0).
+     * @returns `true` when the shape should be drawn instead of replaced with the not-found glyph.
      */
     private shapeHasStrokeGeometry;
+    /**
+     * Resolves the best available shape for a percent-control-code symbol.
+     *
+     * Tries symbol-font lookup codes first, then falls back to the primary font glyph.
+     *
+     * @param data Parser percent-symbol payload.
+     * @returns A renderable text shape for the symbol.
+     */
     private resolvePercentSymbolShape;
+    /**
+     * Resolves the text shape for one character using primary font, big font, defaults, and symbol fonts.
+     *
+     * Updates {@link _maxFontSize} when the active font size exceeds the current line maximum.
+     * Falls back to the not-found glyph when no renderable geometry is available.
+     *
+     * @param char Character to resolve.
+     * @returns Renderable text shape and the font that supplied it.
+     */
+    private resolveCharShape;
+    private canProbeFontOwnership;
+    private fontHasChar;
+    /**
+     * Returns the renderable shape for one character, discarding font provenance metadata.
+     *
+     * @param char Character to resolve.
+     * @returns Renderable text shape, or `undefined` when resolution fails entirely.
+     */
     private getCharShape;
+    /**
+     * Finalizes the current visual line and starts the next one.
+     *
+     * Records layout metadata, resets horizontal pen state, updates vertical offset,
+     * and reapplies paragraph alignment to objects on the completed line.
+     *
+     * @param collectBreakIndex When `true`, records a char index for automatic wrapping.
+     */
     private advanceToNextLine;
+    /**
+     * Updates {@link _maxLineAdvance} from the current line's horizontal pen position.
+     */
     private captureCurrentLineAdvance;
+    /**
+     * Counts logical characters represented by pending char boxes for break-index accounting.
+     *
+     * Stack char boxes collapse numerator, divider, and denominator into one logical token.
+     *
+     * @param meshCharBoxes Pending mesh char boxes.
+     * @param lineCharBoxes Pending line char boxes.
+     * @param charBoxType Classification of the geometry group being flushed.
+     * @returns Number of logical characters contributed by the pending boxes.
+     */
     private countFinalCharBoxes;
+    /**
+     * Corrects vertical offset when the first glyph on a line uses a different font size
+     * than the empty line that preceded it.
+     */
     private applyPendingEmptyLineYAdjust;
+    /**
+     * Chooses whether subsequent char boxes should attach to mesh or line geometry owners.
+     *
+     * @param meshCharBoxes Mesh char boxes already collected on the current line.
+     * @param lineCharBoxes Line char boxes already collected on the current line.
+     * @returns Target geometry family for the next char box.
+     */
     private resolveCharBoxTarget;
     /**
-     * Apply translation on the specified buffer geometries according to text alignment setting
+     * Applies translation on the specified buffer geometries according to text alignment setting.
+     *
+     * Translates both geometry vertices and attached char boxes on the current visual line.
      */
     private processAlignment;
     /**
@@ -337,22 +585,45 @@ export declare class MTextProcessor {
      * AutoCAD uses each font's own space glyph metrics (SHX pen advance or TrueType
      * horizontal advance). A fixed fraction of text height (e.g. 50% for SHX) is only
      * a rough fallback when the font has no space definition.
+     *
+     * @param font Font family name.
+     * @param fontSize Font size in drawing units.
+     * @returns Horizontal advance width for one space character.
      */
     private calculateBlankWidthForFont;
     /**
-     * Merges line-based geometries for LineSegments. SHX glyphs use indexed
-     * BufferGeometry while fraction/divider decorations omit an index; normalize
-     * to non-indexed form so mergeGeometries accepts the batch.
+     * Converts pending mesh and line geometries into a styled THREE.js object.
+     *
+     * @param geometries Mesh (`ShapeGeometry`) primitives for the current style segment.
+     * @param lineGeometries Line primitives and decorations for the current style segment.
+     * @param meshCharBoxes Mesh char boxes to attach to the created object.
+     * @param lineCharBoxes Line char boxes to attach to the created object.
+     * @param charBoxType Char-box classification stored on the created object.
+     * @returns A mesh, line segments object, or small group containing both.
      */
-    private mergeLineGeometries;
+    private toThreeObject;
     /**
-     * Convert the text shape geometries to three.js object
-     * @param geometries Input text shape geometries
-     * @returns Return three.js object created from the specified text shape geometries
+     * Multiplies the active font-size scale factor and recomputes line metrics.
+     *
+     * @param value Relative scale multiplier (for example `0.7` for superscript).
      */
-    private toThreeObject;
     private changeFontSizeScaleFactor;
+    /**
+     * Sets an absolute font height override and recomputes line metrics.
+     *
+     * @param value Font height in drawing units.
+     */
     private changeFontHeight;
+    /**
+     * Resolves the initial text color from entity color settings.
+     *
+     * @returns Base color as `0xRRGGBB`.
+     */
     private resolveBaseColor;
+    /**
+     * Builds color settings for material creation from the current render context.
+     *
+     * @returns Color settings including the active inline color snapshot.
+     */
     private getMaterialColorSettings;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
@@ -44,7 +44,7 @@
   ],
   "dependencies": {
     "@mlightcad/mtext-parser": "^1.5.0",
-    "@mlightcad/shx-parser": "^1.3.5",
+    "@mlightcad/shx-parser": "^1.4.4",
     "iconv-lite": "^0.7.0",
     "idb": "^8.0.3",
     "opentype.js": "^2.0.0"