Magnum::Text::AbstractFont class

#include <Magnum/Text/AbstractFont.h>

Usage

Fonts are most commonly implemented as plugins, which means the concrete font implementation is loaded and instantiated through a PluginManager::Manager. A font is opened using either openFile() or openData() together with specifying the size at which glyphs will be rasterized. Then it stays open until the font is destroyed, close() or another font is opened.

In the following example a font is loaded from the filesystem using the StbTrueTypeFont plugin, prerendering desired glyphs into a GlyphCacheGL, completely with all error handling — depending on the font file, font plugin implementation, font size and cache size, it may happen that the characters won't all fit, which should be checked by the application:

PluginManager::Manager<Text::AbstractFont> manager;
Containers::Pointer<Text::AbstractFont> font =
    manager.loadAndInstantiate("StbTrueTypeFont");
if(!font->openFile("font.ttf", 12.0f))
    Fatal{} << "Can't open font.ttf with StbTrueTypeFont";

Text::GlyphCacheGL cache{PixelFormat::R8Unorm, {256, 256}};
if(!font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
                                "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                                "0123456789?!:;,. "))
    Fatal{} << "Glyph cache too small to fit all characters";

See Loading and using plugins for more information about general plugin usage and the list of derived classes for available font plugins. See AbstractGlyphCache for more information about glyph caches, Renderer for high-level text rendering, and AbstractShaper for low-level access to the font text shaping functionality.

Font size

Font libraries specify font size in points, where 1 pt = ~1.333 px at 96 DPI, so in the above snippet a 12 pt font corresponds to 16 px on a 96 DPI display. The font size corresponds to the height of the EM quad which is defined as the distance between ascent and descent.

Upon opening the font, the size in points is exposed in size(). Derived properties are specified in pixels in lineHeight(), ascent() and descent().

The font size used when opening the font affects how large the glyphs will be when rasterized into the glyph cache. Actual text rendering with Renderer then uses its own font size, and the actual size that's visible on the screen is then additionally depending on the actual projection used when drawing the rendered mesh.

This decoupling of font sizes is useful for example in case of DistanceFieldGlyphCacheGL, where a single prerendered glyph size can be used to render arbitrarily large font sizes without becoming blurry or jaggy. When not using a distance field glyph cache, it's usually desirable to have the font size and the actual rendered size match. See the Renderer documentation for further information about picking font sizes.

Glyph cache filling options

Besides filling the cache with glyphs corresponding to individual characters in a UTF-8 string, it's possible to directly specify glyph IDs with fillGlyphCache(AbstractGlyphCache&, const Containers::StridedArrayView1D<const UnsignedInt>&). That's useful for example with ligatures like fl or ff that can get used by a particular font implementation instead of individual letters, and which thus don't have a clear mapping to a Unicode codepoint. You can use some font introspection utility to retrieve either directly the glyph IDs, or get just glyph names and match them with IDs using glyphForName() at runtime. The following snippet prerenders a few of the named ligatures present in the Source Sans font that this website uses. Again explicitly checking that the operation succeeds, this time with a CORRADE_INTERNAL_ASSERT_OUTPUT() macro:

CORRADE_INTERNAL_ASSERT_OUTPUT(font->fillGlyphCache(cache, {
    font->glyphForName("fi"),
    font->glyphForName("f_f"),
    font->glyphForName("fl"),
    …
}));

Subsequent calls to fillGlyphCache() add to already existing glyphs, allowing for incremental filling based on which glyphs are needed by actual text. Such as by passing the output of AbstractShaper::glyphIdsInto() through AbstractGlyphCache::glyphIdsInto() and adding all glyphs which it didn't find. Note that, however, the glyph cache packing is the most efficient when all glyphs are added at once.

Finally, it's possible to use this overload to populate the glyph cache with all glyphs in the font:

Containers::Array<UnsignedInt> glyphs{NoInit, font->glyphCount()};
for(UnsignedInt i = 0; i != font->glyphCount(); ++i)
    glyphs[i] = i;

CORRADE_INTERNAL_ASSERT_OUTPUT(font->fillGlyphCache(cache, glyphs));

Loading data from memory, using file callbacks

Besides loading data directly from the filesystem using openFile() like shown above, it's possible to use openData() to import data from memory. Note that the particular importer implementation must support FontFeature::OpenData for this method to work.

Utility::Resource rs{"data"};
Containers::ArrayView<const char> data = rs.getRaw("font.ttf");
if(!font->openData(data, 12.0f))
    Fatal{} << "Can't open font data with StbTrueTypeFont";

Some font formats consist of more than one file and in that case you may want to intercept those references and load them in a custom way as well. For font plugins that advertise support for this with FontFeature::FileCallback this is done by specifying a file loading callback using setFileCallback(). The callback gets a filename, InputFileCallbackPolicy and an user pointer as parameters; returns a non-owning view on the loaded data or a Containers::NullOpt to indicate the file loading failed. For example, loading a memory-mapped font could look like below. Note that the file loading callback affects openFile() as well — you don't have to load the top-level file manually and pass it to openData(), any font plugin supporting the callback feature handles that correctly.

struct Data {
    std::unordered_map<std::string, Containers::Optional<
        Containers::Array<const char, Utility::Path::MapDeleter>>> files;
} data;

font->setFileCallback([](const std::string& filename,
    InputFileCallbackPolicy policy, Data& data)
        -> Containers::Optional<Containers::ArrayView<const char>>
    {
        auto found = data.files.find(filename);

        /* Discard the memory mapping, if not needed anymore */
        if(policy == InputFileCallbackPolicy::Close) {
            if(found != data.files.end()) data.files.erase(found);
            return {};
        }

        /* Load if not there yet. If the mapping fails, remember that to not
           attempt to load the same file again next time. */
        if(found == data.files.end()) found = data.files.emplace(
            filename, Utility::Path::mapRead(filename)).first;

        if(!found->second) return {};
        return Containers::arrayView(*found->second);
    }, data);

font->openFile("magnum-font.conf", 13.0f);

For importers that don't support FontFeature::FileCallback directly, the base openFile() implementation will use the file callback to pass the loaded data through to openData(), in case the importer supports at least FontFeature::OpenData. If the importer supports neither FontFeature::FileCallback nor FontFeature::OpenData, setFileCallback() doesn't allow the callbacks to be set.

The input file callback signature is the same for Text::AbstractFont, ShaderTools::AbstractConverter and Trade::AbstractImporter to allow code reuse.

Data dependency

The AbstractShaper instances returned from createShaper() have a code and data dependency on the dynamic plugin module — since their implementation is in the plugin module itself, the plugin can't be unloaded until the returned instance is destroyed.

Subclassing

The plugin needs to implement the doFeatures(), doClose(), doCreateShaper() functions, either doCreateGlyphCache() or doFillGlyphCache() and one or more of doOpen*() functions. See also AbstractShaper for more information.

In order to support FontFeature::FileCallback, the font needs to properly use the callbacks to both load the top-level file in doOpenFile() and also load any external files when needed. The doOpenFile() can delegate back into the base implementation, but it should remember at least the base file path to pass correct paths to subsequent file callbacks. The doSetFileCallback() can be overridden in case it's desired to respond to file loading callback setup, but doesn't have to be.

You don't need to do most of the redundant sanity checks, these things are checked by the implementation:

• The doOpenData() and doOpenFile() functions are called after the previous file was closed, doClose() is called only if there is any file opened.
• The doOpenData() is called only if FontFeature::OpenData is supported.
• The doSetFileCallback() function is called only if FontFeature::FileCallback is supported and there is no file opened.
• All do*() implementations working on opened file are called only if there is any file opened.

Derived classes

class FreeTypeFont

FreeType font plugin.

class MagnumFont

Simple bitmap font plugin.

class StbTrueTypeFont

TrueType font plugin using stb_truetype.

Public types

using Feature = FontFeature deprecated in 2020.06

Features supported by a font implementation.

using Features = FontFeatures deprecated in 2020.06

Set of features supported by a font implementation.

Public static functions

static auto pluginInterface() -> Containers::StringView

Plugin interface.

static auto pluginSearchPaths() -> Containers::Array<Containers::String>

Plugin search paths.

Constructors, destructors, conversion operators

AbstractFont() explicit

Default constructor.

AbstractFont(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit

Plugin manager constructor.

Public functions

auto features() const -> FontFeatures

Features supported by this font.

auto fileCallback() -> auto new in 2019.10

File opening callback function.

auto fileCallbackUserData() const -> void* new in 2019.10

File opening callback user data.

void setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData = nullptr) new in 2019.10

Set file opening callback.

template<class T>

void setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, T&) callback, T& userData) new in 2019.10

Set file opening callback.

auto isOpened() const -> bool

Whether any file is opened.

auto openData(Containers::ArrayView<const void> data, Float size) -> bool

Open raw data.

auto openFile(Containers::StringView filename, Float size) -> bool

Open a file.

void close()

Close currently opened file.

auto size() const -> Float

Font size in points.

auto ascent() const -> Float

Font ascent in pixels.

auto descent() const -> Float

Font descent in pixels.

auto lineHeight() const -> Float

Line height in pixels.

auto glyphCount() const -> UnsignedInt new in Git master

Total count of glyphs in the font.

auto glyphId(char32_t character) -> UnsignedInt

Glyph ID for given character.

void glyphIdsInto(const Containers::StridedArrayView1D<const char32_t>& characters, const Containers::StridedArrayView1D<UnsignedInt>& glyphs) new in Git master

Glyph IDs for given characters.

auto glyphName(UnsignedInt glyph) -> Containers::String new in Git master

Glyph name.

auto glyphForName(Containers::StringView name) -> UnsignedInt new in Git master

Glyph for given name.

auto glyphSize(UnsignedInt glyph) -> Vector2 new in Git master

Glyph size in pixels.

auto glyphAdvance(UnsignedInt glyph) -> Vector2

Glyph advance in pixels.

auto fillGlyphCache(AbstractGlyphCache& cache, const Containers::StridedArrayView1D<const UnsignedInt>& glyphs) -> bool new in Git master

Fill glyph cache with given glyph IDs.

auto fillGlyphCache(AbstractGlyphCache& cache, std::initializer_list<UnsignedInt> glyphs) -> bool

auto fillGlyphCache(AbstractGlyphCache& cache, Containers::StringView characters) -> bool

Fill glyph cache with given character set.

auto createGlyphCache() -> Containers::Pointer<AbstractGlyphCache>

Create glyph cache.

auto createShaper() -> Containers::Pointer<AbstractShaper> new in Git master

Create an instance of this font shaper implementation.

auto layout(const AbstractGlyphCache& cache, Float size, Containers::StringView text) -> Containers::Pointer<AbstractLayouter> deprecated in Git master

Layout the text using font's own layouter.

Protected types

struct Properties

Font properties.

Protected functions

auto doOpenFile(Containers::StringView filename, Float size) -> Properties virtual

Implementation for openFile()

Private functions

auto doFeatures() const -> FontFeatures pure virtual

Implementation for features()

void doSetFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData) virtual

Implementation for setFileCallback()

auto doIsOpened() const -> bool pure virtual

Implementation for isOpened()

auto doOpenData(Containers::ArrayView<const char> data, Float size) -> Properties virtual

Implementation for openData()

void doClose() pure virtual

Implementation for close()

void doGlyphIdsInto(const Containers::StridedArrayView1D<const char32_t>& characters, const Containers::StridedArrayView1D<UnsignedInt>& glyphs) pure virtual new in Git master

Implementation for glyphIdsInto()

auto doGlyphName(UnsignedInt glyph) -> Containers::String virtual new in Git master

Implementation for glyphName()

auto doGlyphForName(Containers::StringView name) -> UnsignedInt virtual new in Git master

Implementation for glyphForName()

auto doGlyphSize(UnsignedInt glyph) -> Vector2 pure virtual new in Git master

Implementation for glyphSize()

auto doGlyphAdvance(UnsignedInt glyph) -> Vector2 pure virtual

Implementation for glyphAdvance()

auto doFillGlyphCache(AbstractGlyphCache& cache, const Containers::StridedArrayView1D<const UnsignedInt>& glyphs) -> bool virtual

Implementation for fillGlyphCache()

auto doCreateGlyphCache() -> Containers::Pointer<AbstractGlyphCache> virtual

Implementation for createGlyphCache()

auto doCreateShaper() -> Containers::Pointer<AbstractShaper> pure virtual new in Git master

Implementation for createShaper()

Typedef documentation

Function documentation

"cz.mosra.magnum.Text.AbstractFont/0.3.7"

font->setFileCallback([](const std::string& filename,
    InputFileCallbackPolicy, void*) {
        Utility::Resource rs{"data"};
        return Containers::optional(rs.getRaw(filename));
    });

const Utility::Resource rs{"data"};
font->setFileCallback([](const std::string& filename,
    InputFileCallbackPolicy, const Utility::Resource& rs) {
        return Containers::optional(rs.getRaw(filename));
    }, rs);