text-shaper 0.0.1 → 0.1.0

package/dist/raster/atlas.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Texture atlas generator for GPU font rendering
+ *
+ * Packs multiple glyph bitmaps into a single texture atlas
+ * using shelf/skyline bin packing algorithm.
+ */
+import type { Font } from "../font/font.ts";
+import { type AtlasOptions, type GlyphAtlas } from "./types.ts";
+/**
+ * Build a texture atlas from a set of glyphs
+ */
+export declare function buildAtlas(font: Font, glyphIds: number[], options: AtlasOptions): GlyphAtlas;
+/**
+ * Build atlas for ASCII printable characters (32-126)
+ */
+export declare function buildAsciiAtlas(font: Font, options: AtlasOptions): GlyphAtlas;
+/**
+ * Build atlas for a specific string (including all unique glyphs)
+ */
+export declare function buildStringAtlas(font: Font, text: string, options: AtlasOptions): GlyphAtlas;
+/**
+ * Export atlas to formats suitable for GPU upload
+ */
+export declare function atlasToRGBA(atlas: GlyphAtlas): Uint8Array;
+/**
+ * Export atlas as single-channel alpha texture
+ */
+export declare function atlasToAlpha(atlas: GlyphAtlas): Uint8Array;
+/**
+ * Get UV coordinates for a glyph in the atlas
+ */
+export declare function getGlyphUV(atlas: GlyphAtlas, glyphId: number): {
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+} | null;

package/dist/raster/cell.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Cell management for scanline rasterization
+ *
+ * Based on FreeType's ftgrays.c cell accumulation approach.
+ * Each cell tracks coverage and area for anti-aliased rendering.
+ *
+ * Uses pool-based allocation with overflow detection for bounded memory.
+ */
+/**
+ * Pool overflow error - thrown when cell pool is exhausted
+ */
+export declare class PoolOverflowError extends Error {
+    constructor();
+}
+/**
+ * A cell accumulates coverage information for one pixel
+ */
+export interface Cell {
+    /** X coordinate in pixels */
+    x: number;
+    /** Accumulated signed area */
+    area: number;
+    /** Accumulated coverage (winding number contribution) */
+    cover: number;
+    /** Next cell in linked list (index into pool, -1 for end) */
+    next: number;
+}
+/**
+ * Cell storage with pool-based allocation and linked lists per scanline.
+ * Matches FreeType's approach for bounded memory usage.
+ */
+export declare class CellBuffer {
+    /** Fixed-size cell pool */
+    private pool;
+    /** Pool size */
+    private poolSize;
+    /** Next free cell index */
+    private freeIndex;
+    /** Per-scanline linked list heads (index into pool, -1 for empty) */
+    private ycells;
+    /** Band bounds (Y range for current render pass) */
+    private bandMinY;
+    private bandMaxY;
+    /** Bounding box of active cells */
+    minY: number;
+    maxY: number;
+    minX: number;
+    maxX: number;
+    /** Current position for incremental cell updates */
+    private currentX;
+    private currentY;
+    private currentCellIndex;
+    /** Clip bounds in pixels */
+    private clipMinX;
+    private clipMinY;
+    private clipMaxX;
+    private clipMaxY;
+    /** Null cell index (sentinel at end of pool) */
+    private nullCellIndex;
+    /** Whether band bounds have been set */
+    private bandSet;
+    constructor(poolSize?: number);
+    /**
+     * Set clipping bounds
+     */
+    setClip(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * Set band bounds for current render pass
+     */
+    setBandBounds(minY: number, maxY: number): void;
+    /**
+     * Clear all cells for new band
+     */
+    reset(): void;
+    /**
+     * Set current position (in subpixel coordinates)
+     * @throws PoolOverflowError if pool is exhausted
+     */
+    setCurrentCell(x: number, y: number): void;
+    /**
+     * Find or create a cell at the given pixel position
+     * @throws PoolOverflowError if pool is exhausted
+     */
+    private findOrCreateCell;
+    /**
+     * Ensure ycells array can accommodate the given Y coordinate
+     * Used for backward compatibility when setBandBounds is not called
+     */
+    private ensureYCellsCapacity;
+    /**
+     * Add area and cover to current cell
+     */
+    addArea(area: number, cover: number): void;
+    /**
+     * Get current cell area (for accumulation)
+     */
+    getArea(): number;
+    /**
+     * Get current cell cover
+     */
+    getCover(): number;
+    /**
+     * Get all cells for a given Y coordinate, sorted by X
+     */
+    getCellsForRow(y: number): Cell[];
+    /**
+     * Iterate over all cells in scanline order within band
+     */
+    iterateCells(): Generator<{
+        y: number;
+        cells: Cell[];
+    }>;
+    /**
+     * Iterate cells for a single row (for band sweep)
+     */
+    iterateRowCells(y: number): Generator<Cell>;
+    /**
+     * Get number of cells currently allocated
+     */
+    getCellCount(): number;
+    /**
+     * Check if pool is near capacity
+     */
+    isNearCapacity(): boolean;
+}
+/**
+ * Convert cell coverage to 8-bit grayscale value
+ *
+ * The area is accumulated in 2*PIXEL_BITS precision.
+ * We need to shift down to get 0-255 coverage.
+ */
+export declare function coverageToGray(area: number): number;
+/**
+ * Apply non-zero winding fill rule
+ */
+export declare function applyNonZeroRule(cover: number): number;
+/**
+ * Apply even-odd fill rule
+ */
+export declare function applyEvenOddRule(cover: number): number;

package/dist/raster/fixed-point.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Fixed-point arithmetic utilities for rasterization
+ *
+ * FreeType uses several fixed-point formats:
+ * - F26Dot6: 26.6 format (64 units per pixel) for coordinates
+ * - F16Dot16: 16.16 format for high-precision calculations
+ * - F2Dot14: 2.14 format for normalized vectors
+ */
+export declare const PIXEL_BITS = 8;
+export declare const ONE_PIXEL: number;
+export declare const PIXEL_MASK: number;
+export declare const F26DOT6_SHIFT = 6;
+export declare const F26DOT6_ONE: number;
+export declare const F16DOT16_SHIFT = 16;
+export declare const F16DOT16_ONE: number;
+/**
+ * Convert float to 26.6 fixed-point
+ */
+export declare function floatToF26Dot6(x: number): number;
+/**
+ * Convert 26.6 fixed-point to float
+ */
+export declare function f26Dot6ToFloat(x: number): number;
+/**
+ * Convert float to internal raster coordinates (PIXEL_BITS precision)
+ * Input is in font units, output has 256 subpixel levels per pixel
+ */
+export declare function floatToPixel(x: number, scale: number): number;
+/**
+ * Truncate to pixel (floor for positive, ceil for negative)
+ */
+export declare function truncPixel(x: number): number;
+/**
+ * Get fractional part (0 to ONE_PIXEL-1)
+ */
+export declare function fracPixel(x: number): number;
+/**
+ * Round to nearest pixel
+ */
+export declare function roundPixel(x: number): number;
+/**
+ * Floor to pixel boundary
+ */
+export declare function floorPixel(x: number): number;
+/**
+ * Ceiling to pixel boundary
+ */
+export declare function ceilPixel(x: number): number;
+/**
+ * Upscale from 26.6 to internal PIXEL_BITS format
+ * PIXEL_BITS=8 means 2 extra bits of precision vs 26.6
+ */
+export declare function upscale(x: number): number;
+/**
+ * Downscale from internal format to 26.6
+ */
+export declare function downscale(x: number): number;
+/**
+ * Multiply two fixed-point numbers and divide, avoiding overflow
+ * Computes (a * b) / c with 64-bit intermediate precision
+ */
+export declare function mulDiv(a: number, b: number, c: number): number;
+/**
+ * Multiply two 16.16 fixed-point numbers
+ */
+export declare function mulFix(a: number, b: number): number;
+/**
+ * Divide two numbers and return 16.16 fixed-point result
+ */
+export declare function divFix(a: number, b: number): number;
+/**
+ * Fast approximation of sqrt(x*x + y*y) using "alpha max plus beta min" algorithm.
+ * Uses alpha = 1, beta = 3/8 for max error < 7% vs exact value.
+ * From FreeType's FT_HYPOT macro.
+ */
+export declare function hypot(x: number, y: number): number;
+/**
+ * Calculate the length of a 2D vector (integer math)
+ * Uses FreeType's "alpha max plus beta min" approximation
+ */
+export declare function vectorLength(dx: number, dy: number): number;
+/**
+ * Normalize a 2D vector to unit length (16.16 fixed-point output)
+ */
+export declare function normalizeVector(dx: number, dy: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Clamp value to range
+ */
+export declare function clamp(x: number, min: number, max: number): number;
+/**
+ * Absolute value
+ */
+export declare function abs(x: number): number;
+/**
+ * Sign of value (-1, 0, or 1)
+ */
+export declare function sign(x: number): number;

package/dist/raster/gray-raster.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Gray-scale anti-aliased rasterizer
+ *
+ * Based on FreeType's ftgrays.c - a coverage-based scanline rasterizer
+ * that produces high-quality anti-aliased output.
+ *
+ * Algorithm overview:
+ * 1. Convert outline to line segments (flatten curves)
+ * 2. For each line segment, compute coverage contribution to cells
+ * 3. Sweep scanlines, accumulating coverage
+ * 4. Convert coverage to grayscale pixels
+ *
+ * Key concepts:
+ * - cover: accumulated vertical change (winding contribution)
+ * - area: accumulated (y-delta * x-position) for edge anti-aliasing
+ *
+ * Band processing:
+ * - Large glyphs are divided into vertical bands
+ * - Each band is rendered with bounded memory pool
+ * - On overflow, band is bisected and retried
+ */
+import type { Bitmap, FillRule, Span } from "./types.ts";
+/**
+ * Rasterizer state
+ */
+export declare class GrayRaster {
+    private cells;
+    private x;
+    private y;
+    private minX;
+    private minY;
+    private maxX;
+    private maxY;
+    constructor();
+    /**
+     * Set clip rectangle (in pixels)
+     */
+    setClip(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * Set band bounds for current render pass
+     */
+    setBandBounds(minY: number, maxY: number): void;
+    /**
+     * Reset rasterizer state
+     */
+    reset(): void;
+    /**
+     * Move to a new position (start new contour)
+     * Coordinates are in subpixel units (ONE_PIXEL per pixel)
+     */
+    moveTo(x: number, y: number): void;
+    /**
+     * Draw line to position
+     */
+    lineTo(toX: number, toY: number): void;
+    /**
+     * Render a line from current position to (toX, toY)
+     * This is the core rasterization algorithm.
+     */
+    private renderLine;
+    /**
+     * Render a line segment within a single scanline
+     */
+    private renderScanline;
+    /**
+     * Multiply and divide with 64-bit precision
+     */
+    private mulDiv;
+    /**
+     * Draw a quadratic Bezier curve using simple parametric sampling
+     */
+    conicTo(cx: number, cy: number, toX: number, toY: number): void;
+    /**
+     * Draw a cubic Bezier curve
+     */
+    cubicTo(cx1: number, cy1: number, cx2: number, cy2: number, x: number, y: number): void;
+    private subdivCubic;
+    /**
+     * Sweep all cells and render to bitmap
+     *
+     * Supports both top-down (positive pitch) and bottom-up (negative pitch) bitmaps.
+     * For positive pitch: y=0 is at top of image (first row in buffer)
+     * For negative pitch: y=0 is at bottom of image (last row in buffer)
+     */
+    sweep(bitmap: Bitmap, fillRule?: FillRule): void;
+    private applyFillRule;
+    private fillSpan;
+    private setPixel;
+    /**
+     * Sweep and call span callback (unbuffered)
+     * @param callback Span callback function
+     * @param fillRule Fill rule to apply
+     * @param userData User data passed to callback (like FreeType's render_span_data)
+     */
+    sweepSpans<T = void>(callback: (y: number, spans: Span[], userData: T) => void, fillRule?: FillRule, userData?: T): void;
+    /**
+     * Sweep with span buffering (like FreeType's gray_sweep_direct)
+     * Buffers up to 16 spans before flushing for better performance
+     * @param callback Span callback function
+     * @param fillRule Fill rule to apply
+     * @param minX Minimum X clip bound
+     * @param maxX Maximum X clip bound
+     * @param userData User data passed to callback (like FreeType's render_span_data)
+     */
+    sweepDirect<T = void>(callback: (y: number, spans: Span[], userData: T) => void, fillRule?: FillRule, minX?: number, maxX?: number, userData?: T): void;
+    /**
+     * Render with band processing for bounded memory.
+     * Divides large glyphs into bands, retries with bisection on overflow.
+     * Supports both Y-dimension (vertical) and X-dimension (horizontal) bisection
+     * like FreeType's ftgrays.c gray_convert_glyph.
+     *
+     * @param bitmap Target bitmap
+     * @param decomposeFn Function that decomposes outline to rasterizer commands
+     * @param bounds Glyph bounds (minY, maxY, optionally minX, maxX)
+     * @param fillRule Fill rule to apply
+     */
+    renderWithBands(bitmap: Bitmap, decomposeFn: () => void, bounds: {
+        minY: number;
+        maxY: number;
+        minX?: number;
+        maxX?: number;
+    }, fillRule?: FillRule): void;
+    /**
+     * Render a single band with X clipping
+     * @returns true on success, false on pool overflow
+     */
+    private renderBandWithXClip;
+    /**
+     * Sweep a band with X clipping and render to bitmap
+     */
+    private sweepBandWithXClip;
+}

package/dist/raster/lcd-filter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * LCD subpixel rendering support
+ *
+ * LCD displays have RGB subpixels that can be individually addressed
+ * to achieve higher effective resolution. This module provides:
+ * 1. Subpixel rendering (3x horizontal resolution)
+ * 2. FIR filtering to reduce color fringing
+ */
+import type { GlyphPath } from "../render/path.ts";
+import type { Bitmap } from "./types.ts";
+/**
+ * LCD filter weights for reducing color fringing
+ * These are based on FreeType's default LCD filter
+ */
+export declare const LCD_FILTER_LIGHT: number[];
+export declare const LCD_FILTER_DEFAULT: number[];
+export declare const LCD_FILTER_LEGACY: number[];
+/**
+ * LCD rendering mode
+ */
+export declare enum LcdMode {
+    /** Horizontal RGB subpixels (most common) */
+    RGB = 0,
+    /** Horizontal BGR subpixels */
+    BGR = 1,
+    /** Vertical RGB subpixels */
+    RGB_V = 2,
+    /** Vertical BGR subpixels */
+    BGR_V = 3
+}
+/**
+ * Rasterize a glyph with LCD subpixel rendering
+ *
+ * The algorithm:
+ * 1. Render at 3x horizontal resolution
+ * 2. Apply FIR filter to reduce color fringing
+ * 3. Output RGB values per pixel
+ */
+export declare function rasterizeLcd(path: GlyphPath, width: number, height: number, scale: number, offsetX: number, offsetY: number, mode?: LcdMode, filterWeights?: number[]): Bitmap;
+/**
+ * Convert LCD bitmap to RGBA for display
+ * Uses gamma-corrected blending against a background color
+ */
+export declare function lcdToRGBA(lcd: Bitmap, bgColor?: [number, number, number], fgColor?: [number, number, number]): Uint8Array;

package/dist/raster/outline-decompose.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Decompose path commands into rasterizer calls
+ */
+import { type GlyphPath } from "../render/path.ts";
+import type { GrayRaster } from "./gray-raster.ts";
+import { FillRule } from "./types.ts";
+/**
+ * Outline validation error types (like FreeType's error codes)
+ */
+export declare enum OutlineError {
+    Ok = 0,
+    InvalidOutline = 1,
+    InvalidArgument = 2,
+    EmptyOutline = 3
+}
+/**
+ * Validation result with error code and message
+ */
+export interface ValidationResult {
+    error: OutlineError;
+    message?: string;
+}
+/**
+ * Validate a GlyphPath before rasterization (like FreeType's outline validation)
+ *
+ * Checks:
+ * - Path is not null/undefined
+ * - Commands array exists
+ * - Path is not empty (unless allowEmpty is true)
+ * - Command structure is valid
+ * - Contours are properly closed (start with M, end with Z)
+ */
+export declare function validateOutline(path: GlyphPath | null | undefined, allowEmpty?: boolean): ValidationResult;
+/**
+ * Convert a GlyphPath to rasterizer commands
+ *
+ * @param raster - The rasterizer instance
+ * @param path - Path commands to decompose
+ * @param scale - Scale factor (font units to pixels)
+ * @param offsetX - X offset in pixels
+ * @param offsetY - Y offset in pixels
+ * @param flipY - Flip Y axis (font coords are Y-up)
+ */
+export declare function decomposePath(raster: GrayRaster, path: GlyphPath, scale: number, offsetX?: number, offsetY?: number, flipY?: boolean): void;
+/**
+ * Calculate bounding box of path in pixel coordinates
+ */
+export declare function getPathBounds(path: GlyphPath, scale: number, flipY?: boolean): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+} | null;
+/**
+ * Get fill rule from outline flags (like FreeType's FT_OUTLINE_EVEN_ODD_FILL check)
+ *
+ * @param path Path with optional flags
+ * @param defaultRule Default fill rule if flags not set
+ * @returns Fill rule to use
+ */
+export declare function getFillRuleFromFlags(path: GlyphPath | null | undefined, defaultRule?: FillRule): FillRule;

package/dist/raster/rasterize.d.ts

@@ -0,0 +1,36 @@
+/**
+ * High-level rasterization API
+ */
+import type { Font } from "../font/font.ts";
+import { type GlyphPath } from "../render/path.ts";
+import type { GlyphId } from "../types.ts";
+import { type Bitmap, PixelMode, type RasterizedGlyph, type RasterizeOptions } from "./types.ts";
+/**
+ * Rasterize a glyph path to a bitmap
+ */
+export declare function rasterizePath(path: GlyphPath, options: RasterizeOptions): Bitmap;
+/**
+ * Rasterize a glyph from a font
+ */
+export declare function rasterizeGlyph(font: Font, glyphId: GlyphId, fontSize: number, options?: {
+    pixelMode?: PixelMode;
+    padding?: number;
+    /** Use TrueType hinting if available */
+    hinting?: boolean;
+}): RasterizedGlyph | null;
+/**
+ * Rasterize text string using shaped glyphs
+ */
+export declare function rasterizeText(font: Font, text: string, fontSize: number, options?: {
+    pixelMode?: PixelMode;
+    padding?: number;
+}): Bitmap | null;
+/**
+ * Export bitmap to raw RGBA pixels (for WebGL textures, etc.)
+ */
+export declare function bitmapToRGBA(bitmap: Bitmap): Uint8Array;
+/**
+ * Export bitmap to grayscale array
+ */
+export declare function bitmapToGray(bitmap: Bitmap): Uint8Array;
+export { type Bitmap, clearBitmap, createBitmap, FillRule, PixelMode, type RasterizedGlyph, type RasterizeOptions, type Span, } from "./types.ts";