TrueType and OpenType fonts can be loaded into RmlUi by the application. RmlUi has no default font, so at least one font must be loaded before text can be rendered. Fonts can be loaded from C++ as described below, or declaratively from a style sheet using the RCSS @font-face at-rule.

To load a font, call one of the Rml::LoadFontFace() functions described in the following.

Load font face from file

The simplest overload takes a file name, and optionally fallback, weight, and face index parameters:

// Adds a new font face to the font engine. The face's family, style, and weight will be determined from the face itself.
// @param[in] file_path The path to the file to load the face from.
// @param[in] fallback_face True to use this font face for unknown characters in other font faces.
// @param[in] weight The weight to load when the font face contains multiple weights.
// @param[in] face_index The index of the font face within a font collection.
// @return True if the face was loaded successfully, false otherwise.
bool LoadFontFace(const String& file_path,
                  bool fallback_face = false,
                  Style::FontWeight weight = Style::FontWeight::Auto,
                  int face_index = 0);

This function will load the font file specified from file_path, opening it through the file interface. The path should normally be relative to the application’s working directory, or an absolute path.

The font’s family (the string you specify the font with using the font-family RCSS property), the style (normal or italic) and by default the weight are all fetched from the font file itself. RmlUi will generate the font data for specific sizes of the font as required by the application. Note that if you are loading a .ttc, only the first font will be registered.

If enabled, the fallback_face option will make the given font face be used for any unknown characters in other fonts. This is useful for example to provide a single font face for emojis, and another one providing characters for Cyrillic, Greek, and similar. These fonts will then be used whenever characters encountered are not located in the fonts specified by the document. Multiple fallback faces can be used, and they will be prioritized in the order they were loaded.

When the weight parameter is Auto the weight is automatically retrieved from the font. Further, if the font contains multiple weight variations then all of them are loaded. Any other value of weight is either used to override the registered weight, or when there are multiple weights in the face, choose which weight variation to load.

Overriding the default weight parameter can be done by one of Rml::Style::FontWeight::Normal, Bold, or any numeric value [1,1000] by casting, for example (Rml::Style::FontWeight)850.

The face_index parameter allows selection of font faces within font collections. This is useful for loading a single font file with multiple faces.

Override the font family

If you need to override the family name or style of a font loaded from file, use the following overload instead:

// Adds a new font face from file to the font engine. The face's family, style, and weight are given by the parameters.
// @param[in] file_path The path to the file to load the face from.
// @param[in] family The family to register the font as.
// @param[in] style The style to register the font as.
// @param[in] weight The weight to load when the font face contains multiple weights.
// @param[in] fallback_face True to use this font face for unknown characters in other font faces.
// @param[in] face_index The index of the font face within a font collection.
// @return True if the face was loaded successfully, false otherwise.
bool LoadFontFace(const String& file_path,
                  const String& family,
                  Style::FontStyle style,
                  Style::FontWeight weight = Style::FontWeight::Auto,
                  bool fallback_face = false,
                  int face_index = 0);

Load font face from memory

If you need to load a font face from memory rather than from file, use the following overload:

// Adds a new font face from memory to the font engine. The face's family, style, and weight are given by the parameters.
// @param[in] data The font data.
// @param[in] family The family to register the font as.
// @param[in] style The style to register the font as.
// @param[in] weight The weight to load when the font face contains multiple weights.
// @param[in] fallback_face True to use this font face for unknown characters in other font faces.
// @param[in] face_index The index of the font face within a font collection.
// @return True if the face was loaded successfully, false otherwise.
// @lifetime The pointed to 'data' must remain available until after the call to Rml::Shutdown.
bool LoadFontFace(Span<const byte> data,
                  const String& family,
                  Style::FontStyle style,
                  Style::FontWeight weight = Style::FontWeight::Auto,
                  bool fallback_face = false,
                  int face_index = 0);

• When the provided family is empty, the font family and style is automatically retrieved from the font.
• style is one of Rml::Style::FontStyle::Normal or Italic.
• The weight, fallback_face, and face_index parameters work exactly like in the first function.

The italic and bold versions of a font are selected with the font-weight and font-style RCSS properties.

Example

In the following example, the font file at data/trilobyte.ttf is loaded and registered with RmlUi with the family name, style and weight settings specified in the file itself.

Rml::LoadFontFace("data/trilobyte.ttf");

In this example, the font file is loaded from memory with overrides for the name, style and weight.

std::vector<unsigned char> trilobyte_b = MyAssetLoader("data/trilobyte_b.ttf");
Rml::LoadFontFace(trilobyte_b, "Trilobyte", Rml::Style::FontStyle::Normal, Rml::Style::FontWeight::Bold);

/* ... */

// Note that the data must stay alive until after the call to Rml::Shutdown.
Rml::Shutdown();
trilobyte_b.clear();

These fonts would be specified in RCSS with the following rules (assuming ‘trilobyte.ttf’ registers a font of the family ‘Trilobyte’):

body
{
    font-family: Trilobyte;
}

strong
{
    font-weight: bold;
}

If you are unsure about the font-family name of a loaded font file, take a look at the log output as that will list the names of all loaded fonts.