Class BmFont

Namespace

KernSmith

Assembly

KernSmith.dll

The main API for generating and loading BMFont bitmap fonts.

public static class BmFont

Inheritance

object

BmFont

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

BeginIncremental(byte[], FontGeneratorOptions?, AdditionOverflowPolicy)

Starts an empty BmFontIncrementalSession for adding glyphs at runtime. The font is parsed once without a character-set filter, so any character the font contains can be added later. The first AddGlyphs(string) call computes the initial atlas page size exactly as Generate(byte[], FontGeneratorOptions?) would for that batch.

public static BmFontIncrementalSession BeginIncremental(byte[] fontData, FontGeneratorOptions? options = null, AdditionOverflowPolicy overflowPolicy = AdditionOverflowPolicy.Grow)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF file bytes.

options FontGeneratorOptions

Generation options, or null for defaults.

overflowPolicy AdditionOverflowPolicy

What to do when a new glyph does not fit (default: grow the page).

Returns

BmFontIncrementalSession

Remarks

Not supported in a session (throws NotSupportedException): Variants, ChannelPacking, TargetRegion, CustomGlyphs. A Skyline configuration — or a custom Packer — silently uses MaxRects for additions (arbitrary packer state cannot be reconstructed incrementally).

Builder()

Creates a fluent builder for BMFont generation.

public static BmFontBuilder Builder()

Returns

BmFontBuilder

A new fluent builder instance.

ClearRegisteredFonts()

Removes all registered fonts.

public static void ClearRegisteredFonts()

FromConfig(BmfcConfig)

Generates a bitmap font from a parsed configuration (from a .bmfc or .hiero file).

public static BmFontResult FromConfig(BmfcConfig config)

Parameters

config BmfcConfig

The parsed configuration. BmfcConfig is the shared model for both the BMFont .bmfc and libGDX Hiero .hiero formats.

Returns

BmFontResult

The generated bitmap font result.

FromConfig(string)

Generates a bitmap font from a config file, auto-detecting .bmfc or .hiero format.

public static BmFontResult FromConfig(string bmfcPath)

Parameters

bmfcPath string

Path to a configuration file. Despite the name, this accepts both .bmfc and .hiero files (auto-detected by inspecting the file content; the extension is used only as a fallback when the content is inconclusive).

Returns

BmFontResult

The generated bitmap font result.

Generate(byte[], FontGeneratorOptions?)

Generates a BMFont from raw font bytes.

public static BmFontResult Generate(byte[] fontData, FontGeneratorOptions? options = null)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF file bytes.

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

Generate(byte[], int)

Generates a BMFont from raw font bytes at the given size.

public static BmFontResult Generate(byte[] fontData, int size)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF file bytes.

size int

Font size in pixels.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

Generate(string, FontGeneratorOptions?)

Generates a BMFont from a font file on disk.

public static BmFontResult Generate(string fontPath, FontGeneratorOptions? options = null)

Parameters

fontPath string

Path to a TTF/OTF/WOFF file.

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

Generate(string, int)

Generates a BMFont from a font file on disk at the given size.

public static BmFontResult Generate(string fontPath, int size)

Parameters

fontPath string

Path to a TTF/OTF/WOFF file.

size int

Font size in pixels.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

GenerateBatch(IReadOnlyList<BatchJob>, BatchOptions?)

Generates multiple BMFonts in batch, with optional parallelism and font caching.

public static BatchResult GenerateBatch(IReadOnlyList<BatchJob> jobs, BatchOptions? options = null)

Parameters

jobs IReadOnlyList<BatchJob>

The batch jobs to run.

options BatchOptions

Batch options, or null for sequential execution.

Returns

BatchResult

Batch results with per-job outcomes and timing.

GenerateFromSystem(string, FontGeneratorOptions?)

Generates a BMFont from a system-installed font, looked up by family name (e.g., "Arial").

public static BmFontResult GenerateFromSystem(string fontFamily, FontGeneratorOptions? options = null)

Parameters

fontFamily string

Font family name, like "Arial" or "Times New Roman".

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

Exceptions

FontParsingException

Thrown if the font family is not installed.

GenerateFromSystem(string, int)

Generates a BMFont from a system-installed font at the given size.

public static BmFontResult GenerateFromSystem(string fontFamily, int size)

Parameters

fontFamily string

Font family name, like "Arial".

size int

Font size in pixels.

Returns

BmFontResult

The generated bitmap font result containing the .fnt descriptor and atlas pages.

HintFontLocation(string, string, int)

Pre-populates the system font resolver's cache with a consumer-supplied file path for a family name, so GenerateFromSystem(string, FontGeneratorOptions?) can skip OS-specific resolution (Windows registry, heuristic filename match, full directory scan) for it entirely. This is the lightweight alternative to RegisterFont(string, byte[], string?, int) for a consumer who already knows where one of its fonts lives on disk but doesn't want to load its bytes up front.

public static void HintFontLocation(string familyName, string path, int faceIndex = 0)

Parameters

familyName string

Font family name the hint applies to (e.g., "Arial").

path string

Path to the font file believed to contain that family.

faceIndex int

TTC face index (0 for single-face font files).

Remarks

The hint is validated exactly like any other cache or seed-table entry — the file must exist and its parsed font-table family name must match familyName — before it is ever trusted. A wrong hint costs one bounded failed check, then normal resolution proceeds as if no hint had been given; a correct hint skips OS resolution entirely on the next lookup for that family.

Load(string)

Loads a BMFont from a .fnt file, auto-detecting text/XML/binary format. Also loads atlas images (.png) from the same directory.

public static BmFontResult Load(string fntPath)

Parameters

fntPath string

Path to the .fnt file.

Returns

BmFontResult

The loaded bitmap font result with descriptor model and atlas pages.

LoadModel(byte[])

Loads a BMFont model from raw .fnt bytes. Does not load atlas images.

public static BmFontModel LoadModel(byte[] fntData)

Parameters

fntData byte[]

Raw .fnt file bytes.

Returns

BmFontModel

The parsed BMFont descriptor model.

LoadModel(string)

Loads a BMFont model from a text-format .fnt string. Does not load atlas images.

public static BmFontModel LoadModel(string fntContent)

Parameters

fntContent string

Text-format .fnt content.

Returns

BmFontModel

The parsed BMFont descriptor model.

QueryAtlasSize(byte[], FontGeneratorOptions?)

Queries the estimated atlas size from raw font bytes without rasterizing.

public static AtlasSizeInfo QueryAtlasSize(byte[] fontData, FontGeneratorOptions? options = null)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF file bytes.

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

AtlasSizeInfo

Estimated atlas dimensions and page count.

QueryAtlasSize(string, FontGeneratorOptions?)

Queries the estimated atlas size from a font file on disk without rasterizing.

public static AtlasSizeInfo QueryAtlasSize(string fontPath, FontGeneratorOptions? options = null)

Parameters

fontPath string

Path to a TTF/OTF/WOFF file.

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

AtlasSizeInfo

Estimated atlas dimensions and page count.

QueryAtlasSizeFromSystem(string, FontGeneratorOptions?)

Queries the estimated atlas size from a system-installed font without rasterizing.

public static AtlasSizeInfo QueryAtlasSizeFromSystem(string fontFamily, FontGeneratorOptions? options = null)

Parameters

fontFamily string

Font family name, like "Arial".

options FontGeneratorOptions

Generation options, or null for defaults.

Returns

AtlasSizeInfo

Estimated atlas dimensions and page count.

ReadFontInfo(byte[], int)

Reads font metadata from raw font file bytes without generating a bitmap font.

public static FontInfo ReadFontInfo(byte[] fontData, int faceIndex = 0)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF font file bytes.

faceIndex int

Face index for .ttc font collections (default 0).

Returns

FontInfo

Font metadata including family name, metrics, available codepoints, and kerning pairs.

ReadFontInfo(string, int)

Reads font metadata from a font file on disk without generating a bitmap font.

public static FontInfo ReadFontInfo(string fontPath, int faceIndex = 0)

Parameters

fontPath string

Path to a TTF/OTF/WOFF font file.

faceIndex int

Face index for .ttc font collections (default 0).

Returns

FontInfo

Font metadata including family name, metrics, available codepoints, and kerning pairs.

RegisterFont(string, byte[], string?, int)

Registers raw font data (TTF/OTF/WOFF) under a family name so that GenerateFromSystem(string, FontGeneratorOptions?) can resolve it without accessing system fonts. This is essential on platforms where system fonts are unavailable (e.g., Blazor WASM) and recommended for cross-platform consistency.

public static void RegisterFont(string familyName, byte[] fontData, string? style = null, int faceIndex = 0)

Parameters

familyName string

Font family name (e.g., "Arial").

fontData byte[]

Raw font file bytes.

style string

Optional style name (e.g., "Bold", "Italic", "Bold Italic"). When null, registers as the default/regular variant.

faceIndex int

TTC face index (0 for single-face font files).

ResumeIncremental(byte[], FontGeneratorOptions, BmFontModel, AdditionOverflowPolicy)

Resumes a BmFontIncrementalSession from an existing model (e.g. a parsed .fnt or a previous Generate(byte[], FontGeneratorOptions?) result): occupancy, page geometry, character list and kerning are recovered from existing, and new glyphs are placed without moving anything already there. options must be the same settings the model was generated with — padding, spacing, size and outline mismatches throw ArgumentException. See BeginIncremental(byte[], FontGeneratorOptions?, AdditionOverflowPolicy) for the options unsupported in a session.

public static BmFontIncrementalSession ResumeIncremental(byte[] fontData, FontGeneratorOptions options, BmFontModel existing, AdditionOverflowPolicy overflowPolicy = AdditionOverflowPolicy.Grow)

Parameters

fontData byte[]

Raw TTF/OTF/WOFF file bytes of the same font the model was generated from.

options FontGeneratorOptions

The generation options the existing model was generated with.

existing BmFontModel

The existing font model providing occupancy and metrics.

overflowPolicy AdditionOverflowPolicy

What to do when a new glyph does not fit (default: grow the page).

Returns

BmFontIncrementalSession

Remarks

Bold, Italic and MatchCharHeight cannot be verified from the model and must match the original generation, or added glyphs will not match the atlas.

UnregisterFont(string, string?)

Removes a previously registered font. Returns true if a font was removed.

public static bool UnregisterFont(string familyName, string? style = null)

Parameters

familyName string

Font family name.

style string

Optional style name, or null for the default variant.

Returns

bool