Importing fonts

Fonts control how text characters look and are used primarily throughout the GUI system. They are represented with the Font class. A font is a resource, meaning it can be imported, saved and loaded as we described in the Resource manuals.

Fonts can be imported from .TTF or .OTF formats using the importer.

// Import a font named "lato.ttf" from disk
HFont font = gImporter().import<Font>("lato.ttf");

Customizing import

Font import can be customized by providing a FontImportOptions object to the importer.

auto importOptions = FontImportOptions::create();
// Set required options here (as described below)
HFont font = gImporter().import<Font>("lato.ttf", importOptions);

A variety of properties can be customized on import, the most important of which being font size, font style, DPI and a range of characters to import.

Font size

Call FontImportOptions::setFontSizes() to provide a list of font sizes (in point units) to import. Usually whenever you are using a font, you will be also asked for a font size. If a font is imported without the requested size, the nearest size will be used instead.

// Import font of size 11, 12 and 16
importOptions->setFontSizes({ 11, 12, 16 });

Font style

When it comes to font style, you can control three options: bold, italic and rendering mode.

Bold

When bold font is enabled, the font characters will be rendered thicker than normal. Call FontImportOptions::setBold() to enable/disable this option.

importOptions->setBold(true);

Italic

When italic font is enabled, the font characters will be rendered slightly skewed. Call FontImportOptions::setItalic() to enable/disable this option.

importOptions->setItalic(true);

Render mode

Allows you to control should smoothing be applied to rendered fonts, and what kind. See the FontRenderMode enumeration for more information. To set render mode call FontImportOptions::setRenderMode().

importOptions->setRenderMode(FontRenderMode::HintedSmooth);

DPI

DPI stands for dots per inch. It depends on the resultion of the user's display device versus the physical size of the display surface. Devices that have more pixels per inch will have higher DPI.

Setting a higher DPI will make your fonts be bigger (in terms of pixels). This ensures the physical size of the displayed characters remains the same over devices with different resolution vs. size ratios.

// Set to extremely high DPI used by a full HD phone screen
importOptions->setDPI(450);
// Or DPI used by most full HD monitors
importOptions->setDPI(96);

Character range

When importing a font you must specify a set of characters to import. By default all english letters and other common characters are imported, but if you also require other character sets (e.g. Cyrillic, Japanese, Korean) you must specify them by calling FontImportOptions::addCharIndexRange().

The provided range uses Unicode character codes. You can find indices for various sets at the official Unicode page.

// Add Cyrillic characters
importOptions->addCharIndexRange(0x400, 0x4FF);