Table of Contents

Core Library

The KernSmith NuGet package is the core library that powers bitmap font generation. It provides a fully in-memory pipeline from font file to BMFont output.

Pipeline Flow

  1. Font reading -- parse TTF/OTF/WOFF tables (cmap, head, hhea, OS/2, GPOS) for the requested codepoints
  2. Rasterization -- render glyphs via a pluggable rasterizer backend (FreeType by default, with GDI and DirectWrite alternatives) with optional effects (outline, gradient, shadow)
  3. Atlas packing -- arrange glyphs into texture pages using MaxRects or Skyline algorithms
  4. Output formatting -- produce BMFont .fnt descriptors (text, XML, or binary) and encoded atlas images

Namespaces

Namespace Purpose
KernSmith Entry point (BmFont), configuration types (FontGeneratorOptions, CharacterSet, Padding, Spacing, ChannelConfig, BmfcConfig, AtlasSizeConstraints, AntiAliasMode, OutputFormat, TextureFormat), exceptions, enums
KernSmith.Font Font reading and TTF table parsing
KernSmith.Font.Models Data models: FontInfo, KerningPair, GlyphMetrics
KernSmith.Font.Tables Parsed table structures: HeadTable, HheaTable, Os2Metrics, NameInfo
KernSmith.Rasterizer IRasterizer, glyph effects (<xref:KernSmith.Rasterizer.IGlyphEffect>), <xref:KernSmith.Rasterizer.GlyphCompositor>
KernSmith.Atlas IAtlasPacker, packing algorithms, texture encoders (PNG/TGA/DDS), <xref:KernSmith.Atlas.AtlasBuilder>
KernSmith.Output BMFont formatters, <xref:KernSmith.Output.FileWriter>, BmFontResult, BmFontReader
KernSmith.Output.Model BMFont data model: BmFontModel, InfoBlock, CommonBlock

Key Classes

BmFont

The main entry point. Provides static methods for font generation:

  • BmFont.Generate() -- generate from a font file path or byte array
  • BmFont.GenerateFromSystem() -- generate from a system-installed font
  • BmFont.FromConfig() -- generate from a .bmfc or .hiero configuration file (format auto-detected by inspecting file content, with the extension used only as a fallback when the content is inconclusive)
  • BmFont.Builder() -- start a fluent builder chain
  • BmFont.Load() -- load an existing .fnt file with atlas pages
  • BmFont.GenerateBatch() -- parallel batch generation
  • BmFont.RegisterFont() -- register raw font data for use with GenerateFromSystem() on platforms without system font access
  • BmFont.UnregisterFont() -- remove a previously registered font
  • BmFont.ClearRegisteredFonts() -- remove all registered fonts

BmFontResult

The output of font generation. Provides access to:

  • .FntText, .FntXml, .FntBinary -- formatted .fnt content
  • .Pages -- atlas page pixel data and dimensions
  • .GetPngData(), .GetTgaData(), .GetDdsData() -- encoded atlas images
  • .ToFile() -- write all output files to disk
  • .ToBmfc(), .ToHiero() -- export an equivalent .bmfc or Hiero .hiero (libGDX) config string
  • .Model -- the underlying BmFontModel data

Config Formats

KernSmith reads and writes both BMFont .bmfc and Hiero .hiero (libGDX) configuration files. ConfigFormatFactory.ReadConfig() dispatches to the correct format by inspecting the file content (the extension is used only as a fallback when the content is inconclusive), while ConfigFormatFactory.WriteConfig() selects the format from the file extension; both return/accept a BmfcConfig. The format-specific BmfcConfigReader/BmfcConfigWriter and HieroConfigReader/HieroConfigWriter (all in the KernSmith namespace) are also available. Hiero is a lossy target for some KernSmith features (channel packing, variable axes, super sampling, color fonts have no .hiero equivalent).

AtlasPage

Each entry in BmFontResult.Pages is an AtlasPage exposing the raw PixelData, Width, Height, PageIndex, and Format (<xref:KernSmith.Atlas.PixelFormat>: Rgba32 or Grayscale8).

For encoded image bytes, a page provides .ToPng(), .ToTga(), and .ToDds().

For direct GPU upload, the following helpers convert a page to a specific pixel layout regardless of its native format. Each returns a fresh, caller-owned buffer:

Method Output Use case
GetRgbaPixelData() 4 bytes/pixel R,G,B,A (grayscale -> 255,255,255,v) Straight-alpha GPU upload (e.g. MonoGame Texture2D.SetData)
GetAlpha8PixelData() 1 byte/pixel alpha coverage Single-channel/coverage textures, custom shaders
GetPremultipliedRgbaPixelData() 4 bytes/pixel premultiplied R,G,B,A Premultiplied-alpha blend pipelines (MonoGame default BlendState.AlphaBlend, WPF)

FontGeneratorOptions

Configuration for the generation pipeline: font size, character set, effects (outline, gradient, shadow), atlas settings, SDF, super sampling, variable font axes, and more.

Size is a float (default 32f) and supports fractional values when paired with the FreeType, StbTrueType, or DirectWrite rasterizer. The GDI rasterizer rounds fractional sizes to the nearest integer. Integer literals (e.g. Size = 32) continue to compile via implicit widening. BMFont on-disk formats store integer size; formatters round at the write boundary using Math.Round.

Bold / Italic Properties

Property Description
Bold Request bold -- uses native bold face when available (system fonts), falls back to synthetic
Italic Request italic -- uses native italic face when available (system fonts), falls back to synthetic
ForceSyntheticBold Force synthetic bold, skip native bold face lookup
ForceSyntheticItalic Force synthetic italic, skip native italic face lookup

When loading from a file path, bold/italic is always synthetic -- Bold and ForceSyntheticBold produce identical results. Use GenerateFromSystem() or WithSystemFont() for native face resolution. GDI backend limitation: cannot apply synthetic bold when a native bold face exists -- use FreeType or DirectWrite.

CharacterSet

Defines which Unicode codepoints to include. Provides presets (Ascii, ExtendedAscii, Latin) and factory methods (FromChars, FromRanges, Union).

Platform Notes

Blazor WASM

The core library works in Blazor WebAssembly when paired with the StbTrueType rasterizer backend. Key constraints:

  • Use KernSmith.Rasterizers.StbTrueType — FreeType requires native binaries unavailable in WASM
  • Use in-memory APIs (FntText, GetPngData()) instead of ToFile()
  • System font loading returns empty results — use BmFont.RegisterFont() to provide font data
  • Enable <RunAOTCompilation>true</RunAOTCompilation> for production performance

See the Blazor WASM sample for a complete working example.

Edit this page