PixelFontBuilder

Description

sealed class Tinman.Engine.Drawing.PixelFontBuilder

Builds pixel fonts that can be loaded with PixelFontInfo.For and Graphics.LoadFontFrom.

To build a pixel font, the following steps are necessary:

  1. Create a PixelFontBuilder object.

  2. Use Baseline or AutoBaseline to specify the font baseline.

  3. Use Compact and/or AutoCompact to specify the font compact height.

  4. Use KerningPairs and Spacing to control the horizontal spacing between glyph pairs.

  5. Use PowerOfTwo to control the dimensions of the pixel font image.

  6. Use Trim to specify the trimming behaviour for glyph pixels.

  7. Use Whitespace to specify the whitespace width to use for the font.

  8. Use FilterCategories, FilterHeight and FilterIgnore to configure the filter that decides which characters will be included in the pixel font.

  9. Use Glyph and/or GlyphAll to specify the font glyphs.

  10. Use Build to build a pixel font image, which will contain all font glyphs as well as the corresponding metadata (see below for details).

  11. Write the pixel font image to a .pxb file (or any other image format that supports 8-bit grayscale images), for example by using ColorBuffer.WritePXB1

  12. Use Graphics.LoadFontFrom or PixelFont.HandleFile to load a pixel font from its image file.

A pixel font image holds the actual font glyphs as well as additional metadata, which is encoded as 8-bit grayscale values. The following logic may be used to iterate over all font glyphs and to decode the metadata:

  1. Define V(x,y) as…​

    1. the 8-bit pixel value at (x,y), if inside of the font image.

    2. 255, if (x,y) lies outside of the font image.

  2. Let X be 0.
    Let Y be 0.
    Let Dy be 0.

  3. If V(X,Y) is not 255, goto 6.

  4. Let X be 0.
    Let Y be the sum of Dy and Y.
    Let Dy be 0.

  5. If V(X,Y) is 255, goto 9.

  6. The pixel at (X,Y) represents the top-left corner of a font glyph specification rectangle, which encodes glyph metadata in the top-most pixel row:

    Rw := 255 - V(X+0,Y)
Rh := 255 - V(X+1,Y)
W  := 255 - V(X+2,Y)
Ox := 255 - V(X+3,Y)
Oy := 255 - V(X+4,Y)
Ch := 255 - V(X+5,Y)
Cl := 255 - V(X+6,Y)

    These metadata values correlate with PixelFontGlyph attributes as follows:
    X becomes Box2I.X1 of PixelFontGlyph.Bounds.
    Y+1 becomes Box2I.Y1 of PixelFontGlyph.Bounds.
    Rw becomes Box2I.Width of PixelFontGlyph.Bounds.
    Rh becomes Box2I.Height of PixelFontGlyph.Bounds.
    W becomes PixelFontGlyph.Width.
    Ox becomes Vec2I.X of PixelFontGlyph.Offset.
    Oy becomes Vec2I.Y of PixelFontGlyph.Offset.
    Ch*256+Cl becomes PixelFontGlyph.Character.

  7. Let Dx be the maximum of Rw and 7.
    Let Dy be the maximum of Rh+1 and Dy.
    Let X be the sum of Dx and X.

  8. Continue with step 3.

  9. Let B be a empty sequence of unsigned 8-bit integer values.

  10. Start at (X+1,Y) to iterate in row-major order over all remaining pixels of the font image and append 255 - V(x,y) to B for each pixel.

  11. Consume the byte stream B according to this structure:

    Block   | Count
--------+------
VERSION |     1
HEADER  |     1
KERNING |  0..n
FOOTER  |     1

VERSION | Type      | Meaning
--------+-----------+-------------------------------
      0 | uint8     | block ID (always 1)
      1 | uint8     | data stream version (always 1)

HEADER  | Type      | Meaning
--------+-----------+-------------------------------
      0 | uint8     | block ID (always 2)
      1 | uint8     | font height
      2 | uint8     | font ascent
      3 | uint8     | compact height
      4 | uint8     | whitespace width
      5 | int8      | glyph spacing

KERNING | Type      | Meaning
--------+-----------+-------------------------------
      0 | uint8     | block ID (always 3)
      1 | uint16_be | first character
      3 | uint16_be | second character
      5 | int8      | kerning width

FOOTER  | Type      | Meaning
--------+-----------+-------------------------------
      0 | uint8     | block ID (always 255)
See also

PixelFont
IPixelFontGlyphs

Public / Constants

Auto​Compact​Default

public constant AutoCompactDefault → ("0123456789abcdefhiklmnorstuvwxzABCDEFGHIJKLMNOPRSTUVWXYZ":string)

The characters that will be present in AutoCompact by default.

Public / Constructors

Build

public method Build → ()

returns → ColorBuffer

The font image.

Builds a font image from the current builder state.

See also

PixelFontBuilder.Baseline
PixelFontBuilder.Compact
PixelFontBuilder.KerningPairs
PixelFontBuilder.Spacing
PixelFontBuilder.Whitespace

Pixel​Font​Builder

public constructor PixelFontBuilder → ()

Creates a new instance of PixelFontBuilder.

Public / Methods

Glyph

public method Glyph → (2)

character in : char

The glyph character, built of black pixels. White pixels and transparent pixels do not belong to the glyph and are trimmed away. Any shades in between can be used for anti-aliasing.

pixels in : ColorBuffer

[not-null]
The glyph pixels.

returns → bool

true if a glyph has been added, false if not.

Adds a glyph to the font.

This method returns false in these cases:

  • IsIgnored returns true for character in.

  • The glyph pixels in are empty, i.e. all pixels are white.

  • The trimmed height of the glyph pixels in is not contained in FilterHeight.

See also

PixelFontBuilder.AutoBaseline
PixelFontBuilder.AutoCompact
PixelFontBuilder.Trim

Glyph​All

public method GlyphAll → (1)

glyphs in : IPixelFontGlyphs

[not-null]
The pixel font glyphs provider to use.

Helper method that iterates over all characters in IPixelFontGlyphs.Glyphs, calls IPixelFontGlyphs.Glyph for each one and then delegates to Glyph.

Glyph​Range

public method GlyphRange → (3)

glyphs in : IPixelFontGlyphs

[not-null]
The pixel font glyphs provider to use.

a in : char

The first character of the range (inclusive).

b in : char

The second character of the range (inclusive).

Helper method that iterates over all characters between a in and b in, calls IPixelFontGlyphs.Glyph for each one and then delegates to Glyph.

Glyph​String

public method GlyphString → (2)

glyphs in : IPixelFontGlyphs

[not-null]
The pixel font glyphs provider to use.

value in : string

[not-null]
The characters.

Helper method that iterates over all unique characters in value in, calls IPixelFontGlyphs.Glyph for each one and then delegates to Glyph.

Is​Ignored

[Pure]
public method IsIgnored → (1)

character in : char

The character to check.

returns → bool

true if character in will produce a font glyph,
false if it will not.

Checks if the given character is ignored and will thus never produce a font glyph.

A character is ignored if any of the following holds true:

  • It is contained in the set of ignored characters, see FilterIgnore.

  • The set of character categories of character in is disjoint with the set of allowed categories, see FilterCategories.

Kerning​Pair

public method KerningPair → (3)

first in : char

The first glyph.

second in : char

The second glyph.

value in : int32

[-128..127]
The custom kerning width offset of the glyph pair.

Adds an entry to KerningPairs.

Public / Attributes

Auto​Baseline

public attribute AutoBaseline → (get,set)

value : char

The character to use for setting Baseline.

Specifies a character that will be used to set Baseline automatically when a matching glyph is being added by subsequent calls to Glyph.

Defaults to '\0'.

Auto​Compact

[Constant]
public attribute AutoCompact → (get)

value : ISortedSet<char>

[not-null]
The characters to use for updating Compact.

Specifies a set of characters that will be used to set Compact to a value greater than its current value, automatically when a matching glyph is being added by subsequent calls to Glyph.

Contains all characters of AutoCompactDefault by default.

Baseline

public attribute Baseline → (get,set)

value : int32

[0..255]
The font baseline. If 0, the font baseline with be equal to the font height.

The font baseline, in pixels.

The value of this property will be taken into account when Build is called.

Defaults to 0.

See also

IPixelFontInfo.Ascent

Compact

public attribute Compact → (get,set)

value : int32

[0..255]
The compact font height. If 0, the compact font height will be equal to the font ascent, see IPixelFontInfo.Ascent.

Specifies the compact font height.

The value of this property will be taken into account when Build is called.

Defaults to 0.

See also

IPixelFontInfo.Compact

Filter​Categories

public attribute FilterCategories → (get,set)

value : CharacterCategory

The set of character categories to include.

Specifies the unicode character categories to include.

Defaults to CharacterCategory.All.

Filter​Height

public attribute FilterHeight → (get,set)

value : RangeI

The range of pixel height values for trimmed pixel font glyphs.

Specifies the allowed range of pixel font height values.

This property can be useful to quickly remove unwanted glyphs when building a font, just by having a look at the generated pixel font image, because there the font glyphs are sorted in ascending order of their trimmed pixel font glyph height.

Defaults to RangeI.Max.

Filter​Ignore

[Constant]
public attribute FilterIgnore → (get)

value : ISortedSet<char>

[not-null]
The set of ignored characters.

Returns the set of ignored characters.

Kerning​Pairs

[Constant]
public attribute KerningPairs → (get)

value : ISortedMap<Pair<char, char>, int8>

[not-null]
The mapping from kerning width pair to kerning width value.

Returns the glyph pairs for which custom kerning width are defined.

The value of this property will be taken into account when Build is called.

The values in this map are added to the initial kerning widths that result from applying Spacing.

Power​Of​Two

public attribute PowerOfTwo → (get,set)

value : bool

true to create power-of-two images, false to create compact images.

Generate pixel font images that have power-of-two dimensions?

The value of this property will be taken into account when Build is called.

Defaults to true.

Spacing

public attribute Spacing → (get,set)

value : int32

[-128..127]
The amount of glyph pixel spacing to use. If negative, the initial kerning width will always be -1-N, which means that pixel blocks will never overlap while having a constant spacing of zero or more. Otherwise, the pixel blocks will be arranged horizontally using the greatest amount of overlap which still satisfied the pixel spacing.

Specifies the amount of omnidirectional spacing around the pixels of each font glyph to use for computing the initial kerning width of each glyph pair.

The value of this property will be taken into account when Build is called.

The initial kerning width may be adjusted by adding custom kerning width offsets to KerningPairs, for specific glyph pairs.

Defaults to 1.

Trim

public attribute Trim → (get,set)

value : bool

true to trim the given glyph pixels at the left and right edges,
false to use the unmodified glyph pixels, as specified.

Enables or disables horizontal trimming of glyphs for subsequent calls to Glyph.

Defaults to true.

Whitespace

public attribute Whitespace → (get,set)

value : int32

[0..255]
The whitespace width of the font. If 0, the whitespace width will be computed automatically.

Specifies the whitespace width to use for the pixel font.

The value of this property will be taken into account when Build is called.

Defaults to 0.