@codexo/exojs 0.8.4 → 0.9.0

package/dist/esm/rendering/text/BitmapText.js

@@ -0,0 +1,220 @@
+import { AbstractText } from './AbstractText.js';
+import { layoutText, buildTextPageQuads } from './TextLayout.js';
+import { TextStyle } from './TextStyle.js';
+
+// ── BmFontAdapter ─────────────────────────────────────────────────────────────
+/**
+ * Adapts {@link BmFontData} to the {@link GlyphProvider} interface consumed
+ * by {@link layoutText}.
+ *
+ * - `getGlyph()` maps BMFont metrics to {@link GlyphInfo} using bearings that
+ *   place each glyph correctly relative to its line's Y origin.
+ * - `getKerning()` looks up the BMFont kerning table.
+ *
+ * @internal
+ */
+class BmFontAdapter {
+    _fontData;
+    _textures;
+    _scale;
+    /** Fallback advance for characters not present in the font (≈ ½ line height). */
+    _fallbackAdvance;
+    constructor(fontData, textures, scale) {
+        this._fontData = fontData;
+        this._textures = textures;
+        this._scale = scale;
+        this._fallbackAdvance = fontData.lineHeight * scale * 0.5;
+    }
+    getGlyph(char, _fontSize) {
+        const cp = char.codePointAt(0) ?? 0;
+        const g = this._fontData.chars.get(cp);
+        const s = this._scale;
+        const lh = this._fontData.lineHeight;
+        const base = this._fontData.base;
+        if (g === undefined) {
+            // Unknown glyph — return an invisible placeholder with a cursor advance.
+            return {
+                x: 0,
+                y: 0,
+                width: 0,
+                height: 0,
+                advance: this._fallbackAdvance,
+                ascent: 0,
+                page: 0,
+                uvLeft: 0,
+                uvTop: 0,
+                uvRight: 0,
+                uvBottom: 0,
+            };
+        }
+        const texW = this._textures[g.page]?.width ?? 1;
+        const texH = this._textures[g.page]?.height ?? 1;
+        return {
+            x: g.x,
+            y: g.y,
+            width: g.width * s,
+            height: g.height * s,
+            advance: g.xAdvance * s,
+            ascent: 0,
+            page: g.page,
+            uvLeft: g.x / texW,
+            uvTop: g.y / texH,
+            uvRight: (g.x + g.width) / texW,
+            uvBottom: (g.y + g.height) / texH,
+            // xBearing shifts the quad right by the glyph's left bearing so the
+            // visual left edge aligns with the cursor.
+            xBearing: g.xOffset * s,
+            // yBearing places the glyph so its top is at lineY + lineHeight + yOffset - base.
+            // This matches the BMFont convention: yOffset is relative to the line top,
+            // and adding lineHeight gives one full line of descent before the glyph top.
+            yBearing: (g.yOffset - base) * s + lh * s,
+        };
+    }
+    getKerning(prev, next, _fontSize) {
+        const a = prev.codePointAt(0);
+        const b = next.codePointAt(0);
+        if (a === undefined || b === undefined)
+            return 0;
+        return (this._fontData.kernings.get(`${a},${b}`) ?? 0) * this._scale;
+    }
+}
+// ── BitmapText ────────────────────────────────────────────────────────────────
+/**
+ * Text node that renders from an offline-generated atlas — either a BMFont
+ * (AngelCode .fnt + .png) or an MSDF atlas (msdf-atlas-gen + .json).
+ *
+ * The atlas is pre-built so there is no runtime Canvas 2D rasterisation.
+ * All layout features (alignment, word-wrap, justify, leading, breakWords,
+ * whiteSpace, letterSpacing) and kerning pairs from the descriptor are fully
+ * supported. Outline effects are handled as shader uniforms — no extra draw
+ * calls, no atlas rebuilds.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const font  = await loader.load('fonts/ui.fnt');   // BmFont, no setup needed
+ * const label = new BitmapText('Score: 0', font, { msdf: true });
+ * scene.addChild(label);
+ *
+ * label.text         = 'Score: 42';  // instant geometry rebuild
+ * label.style.align  = 'center';     // immediate rebuild
+ * ```
+ * @stable
+ */
+class BitmapText extends AbstractText {
+    _font;
+    _fontScale;
+    _msdf;
+    _style;
+    _layout;
+    /** Per-page quad geometry consumed by the text renderer. */
+    _pageQuads = [];
+    _textBounds = { width: 0, height: 0 };
+    _adapter;
+    constructor(text, font, options = {}) {
+        super(text);
+        this._font = font;
+        this._fontScale = options.scale ?? 1;
+        this._msdf = options.msdf ?? false;
+        this._style = new TextStyle(options);
+        this._layout = options.layout ?? {};
+        this._adapter = new BmFontAdapter(font.fontData, font.textures, this._fontScale);
+        this._rebuild();
+    }
+    // ── Text ──────────────────────────────────────────────────────────────────
+    get text() {
+        return this._text;
+    }
+    set text(v) {
+        if (this._text === v)
+            return;
+        this._text = v;
+        this._rebuild();
+    }
+    // ── Style & layout ────────────────────────────────────────────────────────
+    /** Visual style — `align`, `leading`, `fillColor`, `outlineColor` etc. */
+    get style() {
+        return this._style;
+    }
+    set style(v) {
+        this._style = v instanceof TextStyle ? v : new TextStyle(v);
+        this._rebuild();
+    }
+    /** Flow-control options — `maxWidth`, `letterSpacing`, `whiteSpace` etc. */
+    get layout() {
+        return this._layout;
+    }
+    set layout(v) {
+        this._layout = v;
+        this._rebuild();
+    }
+    /** Scale factor applied to all glyph metrics from the font descriptor. */
+    get fontScale() {
+        return this._fontScale;
+    }
+    set fontScale(v) {
+        if (this._fontScale === v)
+            return;
+        this._fontScale = v;
+        this._adapter = new BmFontAdapter(this._font.fontData, this._font.textures, v);
+        this._rebuild();
+    }
+    // ── Read-only state ───────────────────────────────────────────────────────
+    /** `true` when the atlas was produced by `msdf-atlas-gen`. */
+    get msdf() {
+        return this._msdf;
+    }
+    /** Per-page quad data consumed by the text renderer. */
+    get pageQuads() {
+        return this._pageQuads;
+    }
+    get textBounds() {
+        return this._textBounds;
+    }
+    /** The page textures this node draws from. */
+    get textures() {
+        return this._font.textures;
+    }
+    // ── Font replacement ──────────────────────────────────────────────────────
+    /** Replace the font and rebuild the geometry. */
+    setFont(font) {
+        this._font = font;
+        this._adapter = new BmFontAdapter(font.fontData, font.textures, this._fontScale);
+        this._rebuild();
+    }
+    destroy() {
+        this._pageQuads = [];
+        super.destroy();
+    }
+    // ── Private ──────────────────────────────────────────────────────────────
+    _rebuild() {
+        this._pageQuads = [];
+        this._textBounds = { width: 0, height: 0 };
+        if (this._text.length === 0)
+            return;
+        // Derive a TextLayoutStyle from the BMFont descriptor + scale.
+        // Setting fontSize = fontData.lineHeight * scale makes computedLineHeight
+        // equal to the BMFont's native line height multiplied by style.lineHeight.
+        const layoutStyle = {
+            fontSize: this._font.fontData.lineHeight * this._fontScale,
+            lineHeight: this._style.lineHeight,
+            leading: this._style.leading,
+            align: this._style.align,
+        };
+        const placements = layoutText(this._text, layoutStyle, this._layout, this._adapter);
+        let maxX = 0, maxY = 0;
+        for (const p of placements) {
+            const px = p.x + p.width;
+            const py = p.y + p.height;
+            if (px > maxX)
+                maxX = px;
+            if (py > maxY)
+                maxY = py;
+        }
+        this._textBounds = { width: maxX, height: maxY };
+        this._pageQuads = buildTextPageQuads(placements);
+    }
+}
+
+export { BitmapText, BmFontAdapter };
+//# sourceMappingURL=BitmapText.js.map

package/dist/esm/rendering/text/BitmapText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BitmapText.js","sources":["../../../../../src/rendering/text/BitmapText.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/text/BmFont.d.ts

@@ -0,0 +1,50 @@
+import type { Texture } from '@/rendering/texture/Texture';
+/** Per-character metrics from a BMFont descriptor. */
+export interface BmFontChar {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Horizontal draw offset from the cursor to the glyph's left edge. */
+    xOffset: number;
+    /** Vertical draw offset from the line top to the glyph's top edge. */
+    yOffset: number;
+    /** Cursor advance after this character. */
+    xAdvance: number;
+    /** Atlas page this character lives on. */
+    page: number;
+}
+/** Parsed representation of a BMFont (.fnt) descriptor. */
+export interface BmFontData {
+    /** Texture file names for each atlas page (relative paths). */
+    pages: string[];
+    /** Code-point → glyph metrics. */
+    chars: Map<number, BmFontChar>;
+    /**
+     * Kerning pairs — key `"${first},${second}"`, value = pixel adjustment.
+     * Negative values pull glyphs together; positive push them apart.
+     */
+    kernings: Map<string, number>;
+    /** Full line height in font units. */
+    lineHeight: number;
+    /** Baseline position from the top of the line in font units. */
+    base: number;
+}
+/**
+ * A loaded BMFont asset: the parsed descriptor plus all page textures.
+ *
+ * Loaded by the built-in BMFont factory — no extra setup required.
+ * Pass directly to {@link BitmapText}.
+ *
+ * ```ts
+ * const font = await loader.load('fonts/ui.fnt');       // BmFont via extension
+ * const font = await loader.load(BmFont, 'fonts/ui.fnt'); // explicit token
+ * const label = new BitmapText('Score: 0', font);
+ * ```
+ * @stable
+ */
+export declare class BmFont {
+    readonly fontData: BmFontData;
+    readonly textures: readonly Texture[];
+    constructor(fontData: BmFontData, textures: readonly Texture[]);
+}

package/dist/esm/rendering/text/BmFont.js

@@ -0,0 +1,24 @@
+/**
+ * A loaded BMFont asset: the parsed descriptor plus all page textures.
+ *
+ * Loaded by the built-in BMFont factory — no extra setup required.
+ * Pass directly to {@link BitmapText}.
+ *
+ * ```ts
+ * const font = await loader.load('fonts/ui.fnt');       // BmFont via extension
+ * const font = await loader.load(BmFont, 'fonts/ui.fnt'); // explicit token
+ * const label = new BitmapText('Score: 0', font);
+ * ```
+ * @stable
+ */
+class BmFont {
+    fontData;
+    textures;
+    constructor(fontData, textures) {
+        this.fontData = fontData;
+        this.textures = textures;
+    }
+}
+
+export { BmFont };
+//# sourceMappingURL=BmFont.js.map

package/dist/esm/rendering/text/BmFont.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BmFont.js","sources":["../../../../../src/rendering/text/BmFont.ts"],"sourcesContent":[null],"names":[],"mappings":"AAmCA;;;;;;;;;;;;AAYG;MACU,MAAM,CAAA;AACD,IAAA,QAAQ;AACR,IAAA,QAAQ;IAExB,WAAA,CAAmB,QAAoB,EAAE,QAA4B,EAAA;AACnE,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ;AACxB,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ;IAC1B;AACD;;;;"}

package/dist/esm/rendering/text/GlyphAtlas.d.ts

@@ -0,0 +1,104 @@
+import { Signal } from '@/core/Signal';
+import { Texture } from '@/rendering/texture/Texture';
+import type { GlyphInfo, GlyphProvider } from './types';
+/**
+ * Atlas rendering mode. Determines texture format and rasterization strategy.
+ * `'sdf'` uses a single-channel R8 DataTexture with EDT-based rasterization.
+ * `'color'` uses an RGBA canvas for emoji / colour-font glyphs.
+ * MSDF is supported for {@link BitmapText} via offline-generated atlases only.
+ */
+export type AtlasMode = 'sdf' | 'color';
+/**
+ * SDF buffer radius in pixels — the maximum distance outside a glyph that the
+ * SDF field encodes. Determines the maximum usable outline/shadow reach.
+ * Exported so applications can import this constant when computing shader uniforms.
+ */
+export declare const SDF_RADIUS = 8;
+/**
+ * A single texture page within a {@link GlyphAtlas}. Glyphs are packed into
+ * the page using a shelf-bin algorithm.
+ *
+ * In `'sdf'` mode the page owns a `DataTexture` (`r8`) populated by tiny-sdf
+ * output. In `'color'` mode a Canvas 2D context preserves full glyph colours
+ * for emoji.
+ * @advanced
+ */
+export declare class AtlasPage {
+    readonly texture: Texture;
+    readonly index: number;
+    readonly mode: AtlasMode;
+    private readonly _packer;
+    private readonly _width;
+    private readonly _height;
+    private readonly _sdfBuffer;
+    private readonly _sdfTexture;
+    private readonly _ctx;
+    private readonly _colorGlyphs;
+    constructor(index: number, width: number, height: number, mode: AtlasMode);
+    insert(w: number, h: number): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Copy R8 SDF data into the page buffer at the given slot origin.
+     * Only valid in `'sdf'` mode.
+     *
+     * `data` is a `Uint8ClampedArray` of single-channel SDF values as produced
+     * by {@link GlyphSdf.draw}. Each value is one byte (0 = far outside the
+     * glyph, 255 = deep inside, ~128 = glyph edge).
+     */
+    writeSdf(data: Uint8ClampedArray, slotX: number, slotY: number, srcW: number, srcH: number): void;
+    measureGlyph(char: string, font: string): TextMetrics;
+    /** Rasterize a white glyph into the canvas at the given padded slot origin (canvas mode only). */
+    rasterize(char: string, slotX: number, slotY: number, ascent: number, bbLeft: number, font: string): void;
+    uploadDirtyRegion(): void;
+    reset(): void;
+}
+/**
+ * A per-font-variant glyph atlas with automatic multi-page growth.
+ *
+ * In `'sdf'` mode (default) each atlas page is a single-channel R8
+ * `DataTexture` populated by {@link GlyphSdf}. One `GlyphSdf` instance is kept per
+ * font size so the atlas can mix sizes efficiently.
+ *
+ * In `'color'` mode pages are RGBA canvas textures that preserve full glyph
+ * colour data for emoji and colour fonts.
+ * @advanced
+ */
+export declare class GlyphAtlas implements GlyphProvider {
+    private _pages;
+    private readonly _cache;
+    private readonly _kerningCache;
+    private readonly _pageSize;
+    private readonly _family;
+    private readonly _fontStyle;
+    private readonly _fontWeight;
+    private readonly _mode;
+    private readonly _sdfRadius;
+    /**
+     * Dispatched whenever a new atlas page is allocated.
+     *
+     * Listen here to detect unexpected atlas growth (e.g. many unique CJK glyphs
+     * or an oversized font size). The payload is the zero-based page index.
+     *
+     * ```ts
+     * const atlas = pool.getAtlas('Roboto', 'normal', '400');
+     * atlas.onPageAdded.on(idx => console.warn(`Atlas page ${idx} added`));
+     * ```
+     */
+    readonly onPageAdded: Signal<[pageIndex: number]>;
+    /** {@link GlyphSdf} instances keyed by font size — only used in SDF mode. */
+    private readonly _sdfInstances;
+    constructor(family: string, fontStyle: 'normal' | 'italic', fontWeight: string, pageSize?: number, mode?: AtlasMode, sdfRadius?: number);
+    get pages(): readonly AtlasPage[];
+    get mode(): AtlasMode;
+    getGlyph(char: string, size: number): GlyphInfo;
+    getKerning(prev: string, next: string, fontSize: number): number;
+    clear(): void;
+    private _addPage;
+    private _cssFont;
+    private _getSdf;
+    private _rasterizeSdf;
+    private _rasterizeCanvas;
+    private _allocateSlot;
+}