FreeType2 Fonts

Ultraviolet 2018.04 extends the Framework's text rendering functionality by adding support for the FreeType2 font library. This allows your application to make use of traditional vector-based font formats, such as TrueType (.ttf) and OpenType (.otf), rather than relying on manually-created bitmap font textures.

Enabling FreeType2 Fonts

Due to its reliance on several additional native dependencies, Ultraviolet's FreeType2 functionality is implemented as an optional plugin via the new Ultraviolet.FreeType2 library, which is available through NuGet.

Once you have added a reference to this library, configuration is simple: during context configuration, add an instance of the Ultraviolet.FreeType2.FreeTypePlugin class to the Plugins collection exposed by the UltravioletConfiguration object.

protected override UltravioletContext OnCreatingUltravioletContext()
{
    var configuration = new OpenGLUltravioletConfiguration();
    configuration.Plugins.Add(new Ultraviolet.FreeType2.FreeTypeFontPlugin());

    return new OpenGLUltravioletContext(this, configuration);
}

When this plugin is initialized, it will register the content importers and processors necessary to load the new font formats.

Using FreeType2 Fonts

The new UltravioletFont abstract class represents any renderable font, including both the old SpriteFont class and the new FreeTypeFont class. If you use ContentManager to load an asset as an instance of UltravioletFont, it will create either an instance of SpriteFont or an instance of FreeTypeFont depending on the type of file being loaded.

Generally speaking, your code should avoid direct references to either of the implementing classes, and reference UltravioletFont exclusively; this will make the choice of font format largely irrelevant to your code. The one place where you need to be explicit about what kind of font you're loading is in content manifests, where instances of SpriteFont and instances of FreeTypeFont must be declared as separate content groups:

<ContentGroup Name="Fonts" Directory="Fonts" Type="Ultraviolet.Graphics.Graphics2D.SpriteFont">
  <Asset Name="SegoeUI">SegoeUI</Asset>
</ContentGroup>
<ContentGroup Name="FreeTypeFonts" Directory="Fonts" Type="Ultraviolet.FreeType2.FreeTypeFont, Ultraviolet.FreeType2">
  <Asset Name="Inconsolata">Inconsolata</Asset>
</ContentGroup>

All of the text rendering systems have been updated to accept UltravioletFont where they previously accepted SpriteFont, so once the font is loaded everything else should work exactly as it did before.

Asset Metadata

The FreeTypeFont class supports the same set of faces as SpriteFont (regular, bold, italic, bold-italic), but in order to specify the complete set, you must create a content metadata file for the asset. The primary asset is considered the "regular" face; paths to the additional faces are part of the importer data.

A number of processor metadata properties can also be specified, probably the most important of which is the font size. For scalable fonts, use the SizeInPoints property. For fonts which contain bitmap strikes, use the SizeInPixels property to select the strikes for a particular pixel height.

This is an example of a simple metadata file which makes use of these properties:

<?xml version="1.0" encoding="utf-8" ?>
<AssetMetadata>
  <Asset>Inconsolata-Regular.ttf</Asset>
  <ImporterMetadata>
    <BoldFace>Inconsolata-Bold.ttf</BoldFace>
    <ItalicFace>Inconsolata-Italic.ttf</ItalicFace>
    <BoldItalicFace>Inconsolata-BoldItalic.ttf</BoldItalicFace>
  </ImporterMetadata>
  <ProcessorMetadata>
    <SizeInPoints>12</SizeInPoints>
  </ProcessorMetadata>
</AssetMetadata>

The following processor metadata properties may also be specified:

• Scale is a scaling factor which is applied to the font's strikes. This is primarily useful for fonts which only provide very large strikes, such as Google's Noto Color Emoji font. Bilinear filtering is performed on scaled strikes.
• StrokeRadius, StrokeMiterLimit, StrokeLineCap, and StrokeLineJoin specify that the font should be drawn with an outline and provide control over the parameters with which that outline is drawn.
  • StrokeLineCap can be set to any of Butt, Round, or Square.
  • StrokeLineJoin can be set to any of Bevel, Miter, MiterFixed, MiterVariable, or Round.
  • See the FreeType2 documentation for details on what these values do.
• PrepopulatedGlyphs allows you to specify a range of Unicode code points which should be populated on the font's texture atlases at the time that it is loaded. The default value is "ASCII", which indicates the range from 0 to 127. Otherwise, this value should be a comma-delimited string of number pairs separated by a hyphen indicating the ranges to prepopulate, i.e. 0-127,200-255.
• Substitution allows you to specify which character is used as a substitute for code points that do not exist in the font. If this value is not specified, the font will choose from a number of standard Unicode substitution characters, depending on what is defined in the font.
• AtlasWidth, AtlasHeight, and AtlasSpacing allow you to control the parameters of the texture atlases which the font creates in order to hold its glyph data.
• AdjustOffsetX, AdjustOffsetY, AdjustAscender, AdjustDescender, AdjustLineSpacing, AdjustHorizontalAdvance, and AdjustVerticalAdvance each apply a global adjustment, given in pixels, to the corresponding font metric.
• UseClosestPixelSize, when paired with SizeInPixels, will allow the font loader to choose the closest matching pixel size if the font does not define any strikes which match the specified size exactly.