#bikallem/freetype

#Table of Contents

• Features
• What Is Not Ported
• API
• Project Structure
• Build
• Parity Testing
• Performance
• Dependencies
• C-to-MoonBit Design Decisions
• License

#Overview

• Font loading from Bytes (in-memory, no file I/O)
• Character-to-glyph mapping (cmap formats 0, 2, 4, 6, 8, 10, 12, 13)
• Glyph outline loading (TrueType simple/composite, CFF charstrings)
• Glyph rendering (render_glyph, LOAD_RENDER) in normal, light, mono, LCD, LCD_V, color BGRA, and SDF modes
• Pixel size scaling with proper 16.16 fixed-point math
• Kerning pair lookup
• TrueType bytecode hinting (~160 opcodes: point movement, zones, projection vectors, rounding, deltas)
• PostScript hinting (stem fitting, blue zone alignment, point interpolation)
• Auto-hinter (script-aware segment/edge/stem detection, pixel grid fitting)
• PostScript Type 2 charstring interpreter (path operators, hints, subroutines, flex)
• PostScript Type 1 charstring interpreter (hsbw, closepath, callothersubr/Flex, seac)
• Font variations API (set_var_design_coordinates, fvar/avar/gvar/HVAR)
• WOFF1 decompression (zlib via bikallem/compress)
• WOFF2 decompression (Brotli via bikallem/compress) with glyf/loca and hmtx transform reconstruction, including collections
• Standalone CFF font loading (bare CFF without SFNT container)
• Format auto-detection from file header bytes

#Features

#What Is Not Ported

#API

#Load a font

let font_data : Bytes = ... // font file contents
let face = @freetype.from_bytes(font_data)

// Face metadata
println(face.family_name())    // "DejaVu Sans"
println(face.num_glyphs())     // 6253
println(face.units_per_em())   // 2048
println(face.is_scalable())   // true
println(face.has_kerning())   // true

#Character to glyph mapping

let glyph_index = @freetype.get_char_index(face, 65U) // 'A' → glyph index

#Load glyph outlines

// Font units (no scaling)
@freetype.load_glyph(face, glyph_index, load_flags=@base.LOAD_NO_SCALE)
let outline = face.glyph().outline()
println(outline.n_points())    // number of outline points
println(outline.n_contours())  // number of contours
println(outline.points()[0].x())  // first point x coordinate

// Scaled to pixel size
@freetype.set_pixel_sizes(face, 0U, 16U)  // 16 ppem
@freetype.load_glyph(face, glyph_index)
println(face.glyph().metrics().hori_advance())  // advance width in 26.6

#Render glyph bitmaps

@freetype.set_pixel_sizes(face, 0U, 16U)
@freetype.load_glyph(face, glyph_index, load_flags=@base.LOAD_RENDER)
println(face.glyph().bitmap().width())
println(face.glyph().bitmap().rows())

// Or render after a separate load_glyph call.
@freetype.load_glyph(face, glyph_index, load_flags=@base.LOAD_NO_HINTING)
@freetype.render_glyph(face)
println(face.glyph().bitmap_left())
println(face.glyph().bitmap_top())

// Explicit render modes.
@freetype.render_glyph(face, mode=Mono)
@freetype.render_glyph(face, mode=Lcd)
@freetype.render_glyph(face, mode=Sdf)

// LOAD_RENDER also honors FreeType-style load targets.
@freetype.load_glyph(
  face,
  glyph_index,
  load_flags=@base.LOAD_RENDER | @base.LOAD_TARGET_LCD,
)

// Color glyphs opt in through LOAD_COLOR and render to BGRA.
@freetype.load_glyph(face, glyph_index, load_flags=@base.LOAD_COLOR)
println(face.glyph().bitmap().pixel_mode()) // Bgra

#Kerning

let (kern_x, kern_y) = @freetype.get_kerning(face, glyph_a, glyph_v)

#Format detection

let format = @base.detect_format(data)
// Returns: TrueType, CffOpenType, TrueTypeCollection, Woff1, Woff2,
//          Type1Pfb, Type1Pfa, CffStandalone, Bdf, Pcf, WindowsFnt, Pfr, Unknown

#Project Structure

src/
  lib.mbt              # Public API: from_bytes, get_char_index, load_glyph,
                       #   set_pixel_sizes, get_kerning
  error/               # FTError enum (~80 error codes)
  fixed/               # Fixed-point math: 16.16, 26.6, 2.14, CORDIC trig, matrix ops
  types/               # Shared types: Vector, BBox, Outline, Bitmap, GlyphMetrics, tags
  stream/              # ByteReader: position-tracked Bytes reader
  base/                # FaceRec, GlyphSlot, GlyphLoader, outline ops, format detection
  smooth/              # Outline rasterizer: gray, mono, LCD, LCD_V bitmap emission
  color/               # Color font table parsing, BGRA surfaces, bitmap decode helpers
  sdf/                 # Signed-distance-field rasterization
  nativeft/            # Legacy native bridge experiments (not used by the public runtime)
  sfnt/                # SFNT parsing: table directory, head, hhea, maxp, hmtx, name,
                       #   OS/2, post, cmap (formats 0/2/4/6/8/10/12/13/14), kern,
                       #   WOFF1, WOFF2
  truetype/            # TrueType: glyph loading, loca, bytecode interpreter
  cff/                 # CFF: INDEX/DICT parsing, charstring loading
  psaux/               # PostScript charstring interpreter (Type 2)
  pshinter/            # PostScript hinting: stem alignment, blue zones
  psnames/             # Glyph name ↔ Unicode mapping
  type1/               # Type 1 PFB: segment parsing, eexec decryption
  autofit/             # Auto-hinter: script detection, segment/edge analysis
  bdf/, pcf/           # Bitmap font drivers
  cache/               # Glyph/charmap LRU cache
  otvalid/, gxvalid/   # OpenType and GX/AAT table validation
  parity/              # Parity tests (read fonts from disk, compare with C FreeType)
  bench/               # C FreeType comparison benchmark + report
  benchmarks/          # MoonBit benchmarks (moon bench)
  blit/                # Fast byte-level blit operations (memcpy/memset FFI)

#Build

make build     # Compile
make test      # Run unit tests
make parity    # Run parity tests against C FreeType golden data
make fmt       # Format code + regenerate .mbti files
make bench     # Run C vs MoonBit benchmark comparison
make clean     # Remove build artifacts
make all       # build + fmt + test + parity

#Parity Testing

1. Golden file generation — A Python wrapper (test/golden/generate/generate.py) stages the font corpus, using the repo's MoonBit WOFF2 decompressor for .woff2 files, then invokes a C program (test/golden/generate/gen_golden.c) linked against vendored FreeType to dump JSON per font: face metadata, charmap entries, glyph outlines at multiple sizes and load flags, and kerning pairs.

2. Test generation — A Python script (test/parity/gen_parity_tests.py) reads the golden JSON and generates MoonBit test files that load the same fonts through our port and compare every value.

3. Font loading — Tests read fonts from disk at runtime via @fs.read_file_to_bytes() (native target).

• Format detection
• Font loading without error
• Face metadata: family name, glyph count, units per em, ascender, descender, height, underline
• Bounding box: xMin, yMin, xMax, yMax
• Face flags: scalable, sfnt, horizontal, kerning
• Charmap count and platform/encoding IDs
• Character-to-glyph mapping (up to 50 charcodes per font)
• Glyph outlines in font units: point count, contour count, point coordinates
• Glyph metrics at 16 ppem: horizontal advance
• Rendered bitmap parity: pixel mode, dimensions, bearings, buffer bytes
• TTC multi-face loading
• Kerning pair values (up to 20 pairs)

$ make parity

  PARITY REPORT: MoonBit FreeType Port vs C FreeType

  Total: 536 tests, 536 passed, 0 failed

  Format coverage:
     FULL  TrueType                  .ttf
     FULL  CFF/OpenType              .otf
     FULL  TrueType Collection       .ttc
     FULL  WOFF1                     .woff
     FULL  WOFF2                     .woff2
     FULL  Standalone CFF            .cff
     FULL  Type 1 PFB                .pfb
     FULL  BDF Bitmap                .bdf
     FULL  PCF Bitmap                .pcf

#Performance

make bench    # Runs C FreeType + MoonBit benchmarks and generates comparison report

#Dependencies

• bikallem/compress — zlib decompression (WOFF1) and Brotli decompression (WOFF2)
• moonbitlang/x — file I/O for parity tests (native target only)

#C-to-MoonBit Design Decisions

#License