CosmoFonts.Core 1.3.0

CosmoFonts

Pure-C# OpenType font loader and shaping engine. TrueType / CFF / WOFF / WOFF2 in, positioned glyphs out.

License: BSD-3-Clause.

What's here

src/
  CosmoFonts.Core/           — pure C#, no native deps
  CosmoFonts.Core.HarfBuzz/  — optional HarfBuzz wrapper for complex scripts
tools/
  CosmoFonts.SmokeTest/      — diagnostic + HarfBuzz parity comparator
  CosmoFonts.CffSmokeTest/   — CFF-specific diagnostic

Core is the pure-managed engine that almost every consumer should pull. Core.HarfBuzz is a thin P/Invoke wrapper around the native HarfBuzzSharp package, useful when you need HarfBuzz-grade shaping for Indic / Khmer / Myanmar / Tibetan and don't mind the native binaries.

Quick start

using CosmoFonts.Loader;
using CosmoFonts.Shaping;

// Load a font (TTF, OTF, TTC, WOFF, WOFF2 — auto-detected from magic).
var face = Face.Load(File.ReadAllBytes("/Library/Fonts/Arial.ttf"));

// Render text into a glyph outline via IGlyphRenderer.
var options = new TextOptions(face, sizePt: 12f) { Origin = new Vector2(50, 100) };
TextRenderer.RenderTextTo(myRenderer, "Hello, world!", options);

// Or measure without rendering.
var size = TextMeasurer.MeasureSize("Hello, world!", options);

The TextRenderer.RenderTextTo pipeline runs:

1. NFC normalization (composes "a + combining acute" → "á" when the font has the precomposed glyph)
2. BiDi segmentation per UAX #9 (X-rules, weak/neutral resolution, paired brackets, level reordering)
3. Per BiDi run:
   • Script auto-detection (Latin/Cyrillic/Greek/Arabic/Hebrew/Devanagari/Thai/Han/Hangul/Hiragana/Katakana)
   • Arabic positional shaping (base codepoints → Presentation Forms-B based on joining context, with Lam-Alef ligation)
   • Per-face fallback segmentation (rune missing in primary face → look it up in fallbacks)
   • GSUB substitution (liga/smcp/calt/init/medi/fina/...)
   • GPOS positioning (kerning, mark attachment, cursive)
   • RTL reversal with mark-offset fix-up
4. Concatenate runs in visual order
5. Drive the IGlyphRenderer with positioned outline path commands

TTF / TTC / WOFF / WOFF2

// Single-font file
var face = Face.Load(ttfBytes);

// TTC (TrueType Collection — Helvetica.ttc, Avenir.ttc, Apple Color Emoji.ttc, …)
var helvetica = Face.Load(ttcBytes, fontIndex: 0);
int n = Face.CollectionFontCount(ttcBytes);

// WOFF1 (zlib-compressed) — auto-unwrapped
var face1 = Face.Load(woff1Bytes);

// WOFF2 (Brotli-compressed, with transformed glyf reconstruction) — auto-unwrapped
var face2 = Face.Load(woff2Bytes);

Font fallback

var primary  = Face.Load(File.ReadAllBytes("JetBrainsMono-Regular.ttf"));
var fallback = Face.Load(File.ReadAllBytes("Arial.ttf")); // covers Arabic, Cyrillic, …

var options = new TextOptions(primary, 12f)
{
    FallbackFaces = new[] { fallback },
};
TextRenderer.RenderTextTo(myRenderer, "Hi مرحبا", options);
// → "Hi " from JetBrains, "مرحبا" from Arial

Fallback faces should ideally have the same UnitsPerEm as the primary; mismatched units make fallback glyphs render at the wrong size.

System fonts

var sys = SystemFontCollection.LoadDefault();   // scans platform default paths

if (sys.TryFind("Helvetica", FontStyle.BoldItalic, out var entry))
    using var face = entry.Load();

// Or by exact subfamily name from the font's name table:
sys.TryFind("Avenir", "Heavy Oblique", out _);

// Iterate every variant:
foreach (var e in sys.Entries)
    Console.WriteLine($"{e.FamilyName} / {e.SubfamilyName}  ← {Path.GetFileName(e.FilePath)} #{e.FontIndex}");

The SystemFontCollection walks each platform's default font directories (macOS / Linux / Windows), indexes every TTF / OTF / TTC, prefers English subfamily names from the font's name table, and key by (family, subfamily) plus a Regular-preferred shortcut by family alone.

Variable fonts

if (face.IsVariable)
{
    foreach (var axis in face.Fvar!.Axes)
        Console.WriteLine($"{axis.Tag}: {axis.MinValue}..{axis.MaxValue} default={axis.DefaultValue}");

    foreach (var inst in face.Fvar.Instances)
        Console.WriteLine($"named instance — {string.Join(", ", inst.Coordinates)}");
}

Reading axis metadata + named instances works. Actual glyph interpolation at non-default instances (gvar / HVAR / VVAR / MVAR) is not implemented — you get the default-instance outline.

What's implemented

OpenType layout

Other tables

Unicode / shaping

File formats

What's not implemented

The honest list of gaps relative to a full HarfBuzz:

• Indic complex shapers (Devanagari / Bengali / Gujarati / Gurmukhi / Kannada / Malayalam / Tamil / Telugu / Oriya / Sinhala). We pass them through GSUB, but the multi-pass pre-base / post-base reordering and conjunct cluster shaping HarfBuzz does are not implemented. Output is degraded for these scripts.
• South-East Asian shapers — Khmer / Myanmar / Tibetan / Thai / Lao similarly need stateful cluster transformations.
• Variable font interpolation — gvar, HVAR, VVAR, MVAR, CFF2 deltas. We read fvar metadata only.
• Color emoji rendering — COLR v1 paint graph, sbix bitmap, CBDT/CBLC, SVG-in-OT.
• Apple AAT tables — morx, kerx (some macOS system fonts use these instead of OT layout).
• Full UCD bidi data — we use block-range classification; HarfBuzz uses the full Unicode database.
• UAX #14 line breaking — TextOptions.LineBreakOracle is a hook the caller can wire; no built-in implementation.

For workloads that hit those gaps, install CosmoFonts.Core.HarfBuzz and use the HarfBuzzShaper directly — it's a thin P/Invoke wrapper around HarfBuzzSharp's native binaries.

Migrating from SixLabors.Fonts

CosmoFonts grew out of replacing SixLabors.Fonts in CosmoImage and tracks SixLabors's feature surface where CosmoImage actually exercised it. The shaping pipeline mirrors SixLabors's TextRenderer / TextOptions / IGlyphRenderer model so the migration is mostly a namespace swap.

At parity (drop-in equivalents)

Where CosmoFonts goes further than SixLabors.Fonts

Where SixLabors.Fonts goes further than CosmoFonts

Migration checklist

1. Replace using SixLabors.Fonts; with using CosmoFonts.Loader; + using CosmoFonts.Shaping;.
2. Replace Font with Face. Size moves from the Font constructor to the TextOptions(face, sizePt) constructor.
3. Replace RichTextOptions(font) { … } with new TextOptions(face, sizePt) { … }. Property names mostly carry over (Origin, LineSpacing, HorizontalAlignment, WordBreaking, TextJustification, LayoutMode, WrappingLength, FeatureTags).
4. Replace SystemFonts.CreateFont(family, size) with SystemFontCollection.LoadDefault().CreateFont(family) (caches the collection — LoadDefault does file-system I/O, so reuse the result).
5. Update IGlyphRenderer implementations: BeginText / BeginGlyph take RectF instead of FontRectangle, BeginGlyph returns void instead of bool, no in modifier on parameters.
6. Replace Tag.Parse("smcp") — same syntax, lives at CosmoFonts.Font.Opentype.Tag.Parse.
7. If you used decorations: emit them yourself in your renderer or post-process the output path (CosmoImage's VipsText.cs has a worked example).

Verifying against HarfBuzz

CosmoFonts.SmokeTest is the diagnostic tool used to verify pure-managed output against native HarfBuzz. Throughout the engine's build-out, byte-for-byte parity was confirmed on:

• 8 classical Latin kerning pairs on Arial / OpenSans / Times New Roman / JetBrains Mono / Amiri (Δ = 0.000pt)
• JetBrains Mono code ligatures (==, =>, ->, !=)
• Latin combining marks via NFC composition (á, ê, ö, ñ)
• Arabic mark-to-base after BiDi reversal (بَ → fatha at offset (307, −106) matching HB exactly)

dotnet run --project tools/CosmoFonts.SmokeTest -- /System/Library/Fonts/Supplemental/Arial.ttf

Build

dotnet build src/CosmoFonts.Core/CosmoFonts.Core.csproj
dotnet build src/CosmoFonts.Core.HarfBuzz/CosmoFonts.Core.HarfBuzz.csproj  # optional
dotnet run   --project tools/CosmoFonts.SmokeTest -- <path-to-font>

Core targets net10.0. The only external dependency is a sibling Cosmo.Transport project (lightweight transport primitives).

Acknowledgments

Bidi table ranges and Arabic Presentation Forms-B mapping were derived from the Unicode UCD. Font format parsers follow the Microsoft OpenType spec and W3C WOFF2. Algorithm shapes and fixtures cross-checked against HarfBuzz via HarfBuzzSharp.