Table of Contents

Class BmFontBuilder

Namespace
KernSmith
Assembly
KernSmith.dll

Fluent builder for configuring and generating bitmap fonts.

public sealed class BmFontBuilder
Inheritance
BmFontBuilder
Inherited Members

Methods

Build()

Generates the bitmap font, returning the descriptor model and atlas texture pages.

public BmFontResult Build()

Returns

BmFontResult

The generated bitmap font result.

FromConfig(BmfcConfig)

Loads settings from a parsed configuration (from a .bmfc or .hiero file) as a starting point.

public BmFontBuilder 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

BmFontBuilder

This builder.

FromConfig(string)

Loads settings from a config file (.bmfc or .hiero) as a starting point.

public BmFontBuilder 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

BmFontBuilder

This builder.

WithAntiAlias(AntiAliasMode)

Sets the anti-aliasing mode.

public BmFontBuilder WithAntiAlias(AntiAliasMode mode)

Parameters

mode AntiAliasMode

Anti-aliasing mode.

Returns

BmFontBuilder

This builder.

WithAutofitTexture(bool)

If true, shrinks the texture to fit the glyphs tightly.

public BmFontBuilder WithAutofitTexture(bool autofit = true)

Parameters

autofit bool

Enable auto-fit.

Returns

BmFontBuilder

This builder.

WithBackend(RasterizerBackend)

Sets the rasterizer backend to use for glyph rendering.

public BmFontBuilder WithBackend(RasterizerBackend backend)

Parameters

backend RasterizerBackend

The backend to use.

Returns

BmFontBuilder

This builder.

WithBold(bool)

Requests bold. Uses a native bold face when available, falling back to synthetic.

public BmFontBuilder WithBold(bool bold = true)

Parameters

bold bool

Enable bold.

Returns

BmFontBuilder

This builder.

WithChannelPacking(bool)

If true, packs multiple glyphs into separate RGBA channels to save space.

public BmFontBuilder WithChannelPacking(bool channelPacking = true)

Parameters

channelPacking bool

Enable channel packing.

Returns

BmFontBuilder

This builder.

WithChannels(ChannelConfig)

Sets how each RGBA channel is used in the output texture.

public BmFontBuilder WithChannels(ChannelConfig config)

Parameters

config ChannelConfig

Channel configuration.

Returns

BmFontBuilder

This builder.

WithChannels(ChannelContent, ChannelContent, ChannelContent, ChannelContent, bool, bool, bool, bool)

Sets what each RGBA channel contains and whether to invert it.

public BmFontBuilder WithChannels(ChannelContent alpha = ChannelContent.Glyph, ChannelContent red = ChannelContent.Glyph, ChannelContent green = ChannelContent.Glyph, ChannelContent blue = ChannelContent.Glyph, bool invertAlpha = false, bool invertRed = false, bool invertGreen = false, bool invertBlue = false)

Parameters

alpha ChannelContent

What the alpha channel holds.

red ChannelContent

What the red channel holds.

green ChannelContent

What the green channel holds.

blue ChannelContent

What the blue channel holds.

invertAlpha bool

Invert alpha channel.

invertRed bool

Invert red channel.

invertGreen bool

Invert green channel.

invertBlue bool

Invert blue channel.

Returns

BmFontBuilder

This builder.

WithCharacters(CharacterSet)

Sets which characters to include in the output.

public BmFontBuilder WithCharacters(CharacterSet characters)

Parameters

characters CharacterSet

The character set to render.

Returns

BmFontBuilder

This builder.

WithCollectMetrics(bool)

Enables collection of pipeline performance metrics on the result.

public BmFontBuilder WithCollectMetrics(bool collect = true)

Parameters

collect bool

Whether to collect metrics (default true).

Returns

BmFontBuilder

This builder.

WithColorFont(bool)

If true, renders color font layers (emoji, etc.).

public BmFontBuilder WithColorFont(bool colorFont = true)

Parameters

colorFont bool

Enable color font rendering.

Returns

BmFontBuilder

This builder.

WithColorPaletteIndex(int)

Selects which CPAL color palette to use for color fonts.

public BmFontBuilder WithColorPaletteIndex(int index)

Parameters

index int

Zero-based palette index.

Returns

BmFontBuilder

This builder.

WithCustomGlyph(int, CustomGlyph)

Adds a custom bitmap for a specific character code.

public BmFontBuilder WithCustomGlyph(int codepoint, CustomGlyph glyph)

Parameters

codepoint int

Unicode character code to replace.

glyph CustomGlyph

The custom glyph data.

Returns

BmFontBuilder

This builder.

WithCustomGlyph(int, int, int, byte[], PixelFormat, int?)

Adds a custom bitmap for a specific character code from raw pixels.

public BmFontBuilder WithCustomGlyph(int codepoint, int width, int height, byte[] pixelData, PixelFormat format = PixelFormat.Rgba32, int? xAdvance = null)

Parameters

codepoint int

Unicode character code to replace.

width int

Glyph width in pixels.

height int

Glyph height in pixels.

pixelData byte[]

Raw pixel data.

format PixelFormat

Pixel format of the data.

xAdvance int?

Custom horizontal advance, or null to auto-calculate.

Returns

BmFontBuilder

This builder.

WithDpi(int)

Sets the DPI used for font size calculation.

public BmFontBuilder WithDpi(int dpi)

Parameters

dpi int

Dots per inch.

Returns

BmFontBuilder

This builder.

WithEncoder(IAtlasEncoder)

Uses a custom atlas encoder instead of the default.

public BmFontBuilder WithEncoder(IAtlasEncoder encoder)

Parameters

encoder IAtlasEncoder

Encoder to use.

Returns

BmFontBuilder

This builder.

WithEqualizeCellHeights(bool)

If true, makes all glyph cells the same height.

public BmFontBuilder WithEqualizeCellHeights(bool equalize = true)

Parameters

equalize bool

Enable equal cell heights.

Returns

BmFontBuilder

This builder.

WithFaceIndex(int)

Selects which face to use in a font collection (.ttc) file.

public BmFontBuilder WithFaceIndex(int faceIndex)

Parameters

faceIndex int

Zero-based face index.

Returns

BmFontBuilder

This builder.

WithFallbackCharacter(char)

Sets the character shown when a glyph is missing from the font.

public BmFontBuilder WithFallbackCharacter(char fallbackChar)

Parameters

fallbackChar char

Fallback character.

Returns

BmFontBuilder

This builder.

WithFallbackCodepoint(int)

Sets the fallback codepoint used when a requested character is not available in the font. Supports supplementary plane characters (above U+FFFF) unlike WithFallbackCharacter(char).

public BmFontBuilder WithFallbackCodepoint(int codepoint)

Parameters

codepoint int

Unicode codepoint to use as fallback (e.g., 0x25A1 for '□').

Returns

BmFontBuilder

This builder.

WithFont(byte[])

Loads a font from raw byte data.

public BmFontBuilder WithFont(byte[] fontData)

Parameters

fontData byte[]

The font file bytes.

Returns

BmFontBuilder

This builder.

WithFont(string)

Loads a font from a file path.

public BmFontBuilder WithFont(string fontPath)

Parameters

fontPath string

Path to a .ttf, .otf, or .woff file.

Returns

BmFontBuilder

This builder.

WithFontReader(IFontReader)

Uses a custom font reader instead of the default.

public BmFontBuilder WithFontReader(IFontReader reader)

Parameters

reader IFontReader

Font reader to use.

Returns

BmFontBuilder

This builder.

WithForceOffsetsToZero(bool)

If true, forces all glyph x/y offsets to zero.

public BmFontBuilder WithForceOffsetsToZero(bool force = true)

Parameters

force bool

Enable zeroed offsets.

Returns

BmFontBuilder

This builder.

WithForceSyntheticBold(bool)

Forces synthetic bold even when a native bold face exists.

public BmFontBuilder WithForceSyntheticBold(bool force = true)

Parameters

force bool

Enable forced synthetic bold.

Returns

BmFontBuilder

This builder.

WithForceSyntheticItalic(bool)

Forces synthetic italic even when a native italic face exists.

public BmFontBuilder WithForceSyntheticItalic(bool force = true)

Parameters

force bool

Enable forced synthetic italic.

Returns

BmFontBuilder

This builder.

WithGradient((byte R, byte G, byte B), (byte R, byte G, byte B), float, float)

Applies a color gradient across all glyphs.

public BmFontBuilder WithGradient((byte R, byte G, byte B) startColor, (byte R, byte G, byte B) endColor, float angleDegrees = 90, float midpoint = 0.5)

Parameters

startColor (byte R, byte G, byte B)

Start color as (R, G, B).

endColor (byte R, byte G, byte B)

End color as (R, G, B).

angleDegrees float

Angle in degrees. 0 = left-to-right, 90 = top-to-bottom.

midpoint float

Where the midpoint falls, 0.0 to 1.0.

Returns

BmFontBuilder

This builder.

WithHardShadow(bool)

Uses a hard (binarized) shadow silhouette instead of the antialiased glyph alpha.

public BmFontBuilder WithHardShadow(bool enabled = true)

Parameters

enabled bool

Enable hard shadow.

Returns

BmFontBuilder

This builder.

WithHeightPercent(int)

Scales glyph height as a percentage. 100 = normal, 200 = double height.

public BmFontBuilder WithHeightPercent(int percent)

Parameters

percent int

Height as a percentage.

Returns

BmFontBuilder

This builder.

WithHinting(bool)

If true, enables font hinting for sharper small text.

public BmFontBuilder WithHinting(bool enable = true)

Parameters

enable bool

Enable hinting.

Returns

BmFontBuilder

This builder.

WithItalic(bool)

Requests italic. Uses a native italic face when available, falling back to synthetic.

public BmFontBuilder WithItalic(bool italic = true)

Parameters

italic bool

Enable italic.

Returns

BmFontBuilder

This builder.

WithKerning(bool)

If true, includes kerning pairs in the output.

public BmFontBuilder WithKerning(bool kerning = true)

Parameters

kerning bool

Enable kerning.

Returns

BmFontBuilder

This builder.

WithMatchCharHeight(bool)

If true, scales custom glyph advances to match the font's character height.

public BmFontBuilder WithMatchCharHeight(bool match = true)

Parameters

match bool

Enable height matching.

Returns

BmFontBuilder

This builder.

WithMaxTextureSize(int)

Sets the max texture size (both width and height) in pixels.

public BmFontBuilder WithMaxTextureSize(int size)

Parameters

size int

Max width and height in pixels.

Returns

BmFontBuilder

This builder.

WithMaxTextureSize(int, int)

Sets the max texture width and height separately.

public BmFontBuilder WithMaxTextureSize(int width, int height)

Parameters

width int

Max texture width in pixels.

height int

Max texture height in pixels.

Returns

BmFontBuilder

This builder.

WithOutline(int)

Adds an outline around each glyph.

public BmFontBuilder WithOutline(int outline)

Parameters

outline int

Outline width in pixels.

Returns

BmFontBuilder

This builder.

WithOutline(int, byte, byte, byte)

Adds a colored outline around each glyph.

public BmFontBuilder WithOutline(int width, byte r, byte g = 0, byte b = 0)

Parameters

width int

Outline width in pixels.

r byte

Red (0-255).

g byte

Green (0-255).

b byte

Blue (0-255).

Returns

BmFontBuilder

This builder.

WithPacker(IAtlasPacker)

Uses a custom atlas packer instead of the default.

public BmFontBuilder WithPacker(IAtlasPacker packer)

Parameters

packer IAtlasPacker

Packer to use.

Returns

BmFontBuilder

This builder.

WithPackingAlgorithm(PackingAlgorithm)

Sets the atlas packing algorithm.

public BmFontBuilder WithPackingAlgorithm(PackingAlgorithm algorithm)

Parameters

algorithm PackingAlgorithm

Packing algorithm.

Returns

BmFontBuilder

This builder.

WithPackingEfficiency(float)

Sets the expected packing efficiency for atlas size estimation. 0.0 = worst, 1.0 = perfect.

public BmFontBuilder WithPackingEfficiency(float efficiency)

Parameters

efficiency float

Packing efficiency between 0.0 and 1.0.

Returns

BmFontBuilder

This builder.

WithPadding(int)

Sets uniform glyph padding on all sides.

public BmFontBuilder WithPadding(int all)

Parameters

all int

Padding in pixels for every side.

Returns

BmFontBuilder

This builder.

WithPadding(int, int, int, int)

Sets per-side glyph padding in pixels.

public BmFontBuilder WithPadding(int up, int right, int down, int left)

Parameters

up int

Top padding.

right int

Right padding.

down int

Bottom padding.

left int

Left padding.

Returns

BmFontBuilder

This builder.

WithPostProcessor(IGlyphPostProcessor)

Adds a custom post-processing step that runs on each glyph after rasterization.

public BmFontBuilder WithPostProcessor(IGlyphPostProcessor processor)

Parameters

processor IGlyphPostProcessor

The post-processor to add.

Returns

BmFontBuilder

This builder.

WithPowerOfTwo(bool)

If true, rounds texture dimensions up to powers of two.

public BmFontBuilder WithPowerOfTwo(bool powerOfTwo = true)

Parameters

powerOfTwo bool

Enable power-of-two sizing.

Returns

BmFontBuilder

This builder.

WithRasterizer(IRasterizer)

Uses a custom rasterizer instead of the default FreeType one.

public BmFontBuilder WithRasterizer(IRasterizer rasterizer)

Parameters

rasterizer IRasterizer

Rasterizer to use.

Returns

BmFontBuilder

This builder.

WithSdf(bool)

If true, generates signed distance field (SDF) output instead of bitmaps.

public BmFontBuilder WithSdf(bool sdf = true)

Parameters

sdf bool

Enable SDF.

Returns

BmFontBuilder

This builder.

WithShadow(int, int, int, (byte R, byte G, byte B)?, float)

Adds a drop shadow behind each glyph.

public BmFontBuilder WithShadow(int offsetX = 2, int offsetY = 2, int blur = 0, (byte R, byte G, byte B)? color = null, float opacity = 1)

Parameters

offsetX int

Horizontal offset in pixels.

offsetY int

Vertical offset in pixels.

blur int

Blur radius in pixels.

color (byte R, byte G, byte B)?

Shadow color as (R, G, B); defaults to black.

opacity float

Shadow opacity, 0.0 to 1.0.

Returns

BmFontBuilder

This builder.

WithSize(float)

Sets the font size in points. Fractional values are supported on FreeType, StbTrueType, and DirectWrite backends; the GDI backend rounds to the nearest integer.

public BmFontBuilder WithSize(float size)

Parameters

size float

Font size in points.

Returns

BmFontBuilder

This builder.

WithSpacing(int)

Sets uniform glyph spacing in the atlas.

public BmFontBuilder WithSpacing(int both)

Parameters

both int

Gap in pixels for both axes.

Returns

BmFontBuilder

This builder.

WithSpacing(int, int)

Sets the gap between glyphs in the atlas.

public BmFontBuilder WithSpacing(int horizontal, int vertical)

Parameters

horizontal int

Horizontal gap in pixels.

vertical int

Vertical gap in pixels.

Returns

BmFontBuilder

This builder.

WithSuperSampling(int)

Sets the super-sampling level (1 = off, 2 = 2x, 4 = 4x). Higher values give smoother edges.

public BmFontBuilder WithSuperSampling(int level)

Parameters

level int

Super-sampling multiplier.

Returns

BmFontBuilder

This builder.

WithSystemFont(string)

Uses a system-installed font by family name (e.g., "Arial").

public BmFontBuilder WithSystemFont(string familyName)

Parameters

familyName string

Font family name.

Returns

BmFontBuilder

This builder.

WithTextureFormat(TextureFormat)

Sets the output texture format (PNG, TGA, or DDS).

public BmFontBuilder WithTextureFormat(TextureFormat format)

Parameters

format TextureFormat

Texture format.

Returns

BmFontBuilder

This builder.

WithVariationAxis(string, float)

Sets a variable font axis value (e.g., "wght" = 700 for bold weight).

public BmFontBuilder WithVariationAxis(string tag, float value)

Parameters

tag string

Four-character axis tag like "wght" or "wdth".

value float

Axis value.

Returns

BmFontBuilder

This builder.

Edit this page