text-shaper 0.0.1 → 0.1.1

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/bbox.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Exact bounding box calculation for paths with bezier curves
+ *
+ * Bezier curves can extend beyond their control points, so we need to find
+ * the actual extrema by solving for where the derivative equals zero.
+ */
+import type { GlyphPath } from "../render/path.ts";
+/**
+ * Bounding box in 2D space
+ */
+export interface BBox {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+/**
+ * Calculate exact bounding box for a path
+ *
+ * For line segments: min/max of endpoints
+ * For quadratic bezier: find t where derivative = 0, evaluate curve at those t values
+ * For cubic bezier: solve quadratic for extrema, evaluate curve at those t values
+ *
+ * @param path - Path to calculate bounds for
+ * @returns Bounding box or null for empty path
+ */
+export declare function getExactBounds(path: GlyphPath): BBox | null;
+/**
+ * Find t values where a quadratic bezier has extrema
+ *
+ * For quadratic bezier B(t) = (1-t)²p0 + 2(1-t)t*p1 + t²p2
+ * Derivative: B'(t) = 2(1-t)(p1-p0) + 2t(p2-p1)
+ *                   = 2(p1-p0) + 2t(p0-2p1+p2)
+ *                   = 2[(p1-p0) + t(p0-2p1+p2)]
+ *
+ * Set B'(t) = 0:
+ * (p1-p0) + t(p0-2p1+p2) = 0
+ * t = -(p1-p0)/(p0-2p1+p2)
+ *   = (p0-p1)/(p0-2p1+p2)
+ *
+ * @param p0 - Start point
+ * @param p1 - Control point
+ * @param p2 - End point
+ * @returns Array of t values in [0,1] where extrema occur
+ */
+export declare function getQuadraticExtrema(p0: number, p1: number, p2: number): number[];
+/**
+ * Find t values where a cubic bezier has extrema
+ *
+ * For cubic bezier B(t) = (1-t)³p0 + 3(1-t)²t*p1 + 3(1-t)t²p2 + t³p3
+ * Derivative: B'(t) = 3(1-t)²(p1-p0) + 6(1-t)t(p2-p1) + 3t²(p3-p2)
+ *
+ * Simplified: B'(t) = at² + bt + c where:
+ * a = 3(p3 - 3p2 + 3p1 - p0)
+ * b = 6(p2 - 2p1 + p0)
+ * c = 3(p1 - p0)
+ *
+ * Solve using quadratic formula: t = (-b ± √(b²-4ac)) / 2a
+ *
+ * @param p0 - Start point
+ * @param p1 - First control point
+ * @param p2 - Second control point
+ * @param p3 - End point
+ * @returns Array of t values in [0,1] where extrema occur
+ */
+export declare function getCubicExtrema(p0: number, p1: number, p2: number, p3: number): number[];
+/**
+ * Evaluate quadratic bezier at parameter t
+ *
+ * B(t) = (1-t)²p0 + 2(1-t)t*p1 + t²p2
+ *
+ * @param p0 - Start point
+ * @param p1 - Control point
+ * @param p2 - End point
+ * @param t - Parameter in [0,1]
+ * @returns Value at t
+ */
+export declare function evaluateQuadratic(p0: number, p1: number, p2: number, t: number): number;
+/**
+ * Evaluate cubic bezier at parameter t
+ *
+ * B(t) = (1-t)³p0 + 3(1-t)²t*p1 + 3(1-t)t²p2 + t³p3
+ *
+ * @param p0 - Start point
+ * @param p1 - First control point
+ * @param p2 - Second control point
+ * @param p3 - End point
+ * @param t - Parameter in [0,1]
+ * @returns Value at t
+ */
+export declare function evaluateCubic(p0: number, p1: number, p2: number, p3: number, t: number): number;

package/dist/raster/bitmap-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bitmap manipulation utilities
+ */
+import { type Bitmap, PixelMode } from "./types.ts";
+/**
+ * Embolden a bitmap by dilating pixel values
+ * Makes text bolder by spreading coverage in x and y directions
+ */
+export declare function emboldenBitmap(bitmap: Bitmap, xStrength: number, yStrength: number): Bitmap;
+/**
+ * Convert bitmap between pixel modes
+ */
+export declare function convertBitmap(bitmap: Bitmap, targetMode: PixelMode): Bitmap;
+/**
+ * Alpha blend src bitmap onto dst bitmap at position (x, y)
+ */
+export declare function blendBitmap(dst: Bitmap, src: Bitmap, x: number, y: number, opacity: number): void;
+/**
+ * Create a deep copy of a bitmap
+ */
+export declare function copyBitmap(bitmap: Bitmap): Bitmap;
+/**
+ * Resize bitmap using nearest-neighbor interpolation
+ */
+export declare function resizeBitmap(bitmap: Bitmap, newWidth: number, newHeight: number): Bitmap;

package/dist/raster/blur.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bitmap blur filters - Gaussian and Box blur
+ */
+import { type Bitmap } from "./types.ts";
+/**
+ * Generate 1D Gaussian kernel
+ * Uses Gaussian function: exp(-x²/(2σ²))
+ */
+export declare function createGaussianKernel(radius: number): Float32Array;
+/**
+ * Gaussian blur implementation using separable 2-pass algorithm
+ * Modifies bitmap in-place and returns it
+ */
+export declare function gaussianBlur(bitmap: Bitmap, radius: number): Bitmap;
+/**
+ * Box blur using running sum for O(1) per pixel
+ * Modifies bitmap in-place and returns it
+ */
+export declare function boxBlur(bitmap: Bitmap, radius: number): Bitmap;
+/**
+ * Apply blur filter to a bitmap in-place
+ * @param bitmap - Bitmap to blur (modified in-place)
+ * @param radius - Blur radius in pixels (can be fractional)
+ * @param type - Blur type: 'gaussian' (default) or 'box'
+ * @returns The modified bitmap
+ */
+export declare function blurBitmap(bitmap: Bitmap, radius: number, type?: "gaussian" | "box"): Bitmap;

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/gradient.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Gradient fill rendering for paths
+ */
+import type { GlyphPath } from "../render/path.ts";
+import { type Bitmap, type RasterizeOptions } from "./types.ts";
+/**
+ * Color stop in a gradient (RGBA, 0-255 each)
+ */
+export interface ColorStop {
+    /** Position along gradient, 0.0 to 1.0 */
+    offset: number;
+    /** RGBA color values, 0-255 each */
+    color: [number, number, number, number];
+}
+/**
+ * Linear gradient from point (x0,y0) to (x1,y1)
+ */
+export interface LinearGradient {
+    type: "linear";
+    /** Start X coordinate */
+    x0: number;
+    /** Start Y coordinate */
+    y0: number;
+    /** End X coordinate */
+    x1: number;
+    /** End Y coordinate */
+    y1: number;
+    /** Color stops */
+    stops: ColorStop[];
+}
+/**
+ * Radial gradient from center point with radius
+ */
+export interface RadialGradient {
+    type: "radial";
+    /** Center X coordinate */
+    cx: number;
+    /** Center Y coordinate */
+    cy: number;
+    /** Gradient radius */
+    radius: number;
+    /** Color stops */
+    stops: ColorStop[];
+}
+/**
+ * Gradient type union
+ */
+export type Gradient = LinearGradient | RadialGradient;
+/**
+ * Get color at position in gradient
+ */
+export declare function interpolateGradient(gradient: Gradient, x: number, y: number): [number, number, number, number];
+/**
+ * Create a bitmap filled with gradient (no path)
+ */
+export declare function createGradientBitmap(width: number, height: number, gradient: Gradient): Bitmap;
+/**
+ * Rasterize path with gradient fill
+ * First rasterizes path to get coverage mask, then fills with gradient
+ */
+export declare function rasterizePathWithGradient(path: GlyphPath, gradient: Gradient, options: RasterizeOptions): Bitmap;

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;