Magnum::Text::AbstractFont class

#include <Magnum/Text/AbstractFont.h>

typedef FontFeature Magnum::Text::AbstractFont::Feature

Features supported by a font implementation.

typedef FontFeatures Magnum::Text::AbstractFont::Features

Set of features supported by a font implementation.

static std::string Magnum::Text::AbstractFont::pluginInterface()

Plugin interface.

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

static std::vector<std::string> Magnum::Text::AbstractFont::pluginSearchPaths()

Plugin search paths.

First looks in magnum/fonts/ or magnum-d/fonts/ next to the dynamic Text library (unless it's a static build), then in the same location next to the executable and as a fallback in magnum/fonts/ or magnum-d/fonts/ in the runtime install location (lib[64]/ on Unix-like systems, bin/ on Windows). The system-wide plugin search directory is configurable using the MAGNUM_PLUGINS_DIR CMake variables, see Downloading and building for more information.

Not defined on platforms without dynamic plugin support.

auto Magnum::Text::AbstractFont::fileCallback() new in 2019.10

File opening callback function.

void* Magnum::Text::AbstractFont::fileCallbackUserData() const new in 2019.10

File opening callback user data.

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

Set file opening callback.

In case the font plugin supports FontFeature::FileCallback, files opened through openFile() will be loaded through the provided callback. Besides that, all external files referenced by the top-level file will be loaded through the callback function as well, usually on demand. The callback function gets a filename, InputFileCallbackPolicy and the userData pointer as input and returns a non-owning view on the loaded data as output or a Corrade::Containers::NullOpt if loading failed — because empty files might also be valid in some circumstances, nullptr can't be used to indicate a failure.

In case the font plugin doesn't support FontFeature::FileCallback but supports at least FontFeature::OpenData, a file opened through openFile() will be internally loaded through the provided callback and then passed to openData(). First the file is loaded with InputFileCallbackPolicy::LoadTemporary passed to the callback, then the returned memory view is passed to openData() (sidestepping the potential openFile() implementation of that particular font plugin) and after that the callback is called again with InputFileCallbackPolicy::Close because the semantics of openData() don't require the data to be alive after. In case you need a different behavior, use openData() directly.

In case callback is nullptr, the current callback (if any) is reset. This function expects that the font plugin supports either FontFeature::FileCallback or FontFeature::OpenData. If a font plugin supports neither, callbacks can't be used.

It's expected that this function is called before a file is opened. It's also expected that the loaded data are kept in scope for as long as the font plugin needs them, based on the value of InputFileCallbackPolicy. Documentation of particular importers provides more information about the expected callback behavior.

Following is an example of setting up a file loading callback for fetching compiled-in resources from Corrade::Utility::Resource. See the overload below for a more convenient type-safe way to pass the user data pointer.

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

template<class T>

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

Set file opening callback.

Equivalent to calling the above with a lambda wrapper that casts void* back to T* and dereferences it in order to pass it to callback. Example usage:

struct Data {
    std::unordered_map<std::string, Containers::Array<char>> files;
} data;

font->setFileCallback([](const std::string& filename,
    InputFileCallbackPolicy, Data& data)
        -> Containers::Optional<Containers::ArrayView<const char>>
    {
        auto found = data.files.find(filename);
        if(found == data.files.end()) {
            if(!Utility::Directory::exists(filename))
                return Containers::NullOpt;
            found = data.files.emplace(filename, Utility::Directory::read(filename)).first;
        }
        return Containers::ArrayView<const char>{found->second};
    }, data);

bool Magnum::Text::AbstractFont::openData(Containers::ArrayView<const char> data, Float size)

Open font from raw data.

Closes previous file, if it was opened, and tries to open given file. Available only if FontFeature::OpenData is supported. Returns true on success, false otherwise.

bool Magnum::Text::AbstractFont::openData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data, Float size)

Open font from raw data.

bool Magnum::Text::AbstractFont::openSingleData(Containers::ArrayView<const char> data, Float size)

Open font from raw data.

bool Magnum::Text::AbstractFont::openFile(const std::string& filename, Float size)

Open font from file.

Closes previous file, if it was opened, and tries to open given file. Returns true on success, false otherwise.

Float Magnum::Text::AbstractFont::size() const

Font size.

Returns scale in which lineHeight(), ascent(), descent() and glyphAdvance() is returned. Expects that a font is opened.

Float Magnum::Text::AbstractFont::ascent() const

Font ascent.

Distance from baseline to top, scaled to font size. Positive value. Expects that a font is opened.

Float Magnum::Text::AbstractFont::descent() const

Font descent.

Distance from baseline to bottom, scalled to font size. Negative value. Expects that a font is opened.

Float Magnum::Text::AbstractFont::lineHeight() const

Line height.

Returns line height scaled to font size. Expects that a font is opened.

UnsignedInt Magnum::Text::AbstractFont::glyphId(char32_t character)

Glyph ID for given character.

Expects that a font is opened.

Vector2 Magnum::Text::AbstractFont::glyphAdvance(UnsignedInt glyph)

Glyph advance.

Returns glyph advance scaled to font size. Expects that a font is opened.

void Magnum::Text::AbstractFont::fillGlyphCache(AbstractGlyphCache& cache, const std::string& characters)

Fill glyph cache with given character set.

Fills the cache with given characters. Fonts having FontFeature::PreparedGlyphCache do not support partial glyph cache filling, use createGlyphCache() instead. Expects that a font is opened.

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFont::createGlyphCache()

Create glyph cache.

Configures and fills glyph cache with the contents of whole font. Available only if FontFeature::PreparedGlyphCache is supported. Other fonts support only partial glyph cache filling, see fillGlyphCache(). Expects that a font is opened.

Containers::Pointer<AbstractLayouter> Magnum::Text::AbstractFont::layout(const AbstractGlyphCache& cache, Float size, const std::string& text)

Layout the text using font's own layouter.

Note that the layouters support rendering of single-line text only. See Renderer class for more advanced text layouting. Expects that a font is opened.

Metrics Magnum::Text::AbstractFont::doOpenFile(const std::string& filename, Float size) virtual protected

Implementation for openFile()

Return metrics of opened font on successful opening, zeros otherwise. If FontFeature::OpenData is supported, default implementation opens the file and calls doOpenData() with its contents. It is allowed to call this function from your doOpenFile() implementation — in particular, this implementation will also correctly handle callbacks set through setFileCallback().

This function is not called when file callbacks are set through setFileCallback() and FontFeature::FileCallback is not supported — instead, file is loaded though the callback and data passed through to doOpenData().

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

Implementation for setFileCallback()

Useful when the font plugin needs to modify some internal state on callback setup. Default implementation does nothing and this function doesn't need to be implemented — the callback function and user data pointer are available through fileCallback() and fileCallbackUserData().

Metrics Magnum::Text::AbstractFont::doOpenData(Containers::ArrayView<const char> data, Float size) virtual private

Implementation for openData()

Return metrics of opened font on successful opening, zeros otherwise.

void Magnum::Text::AbstractFont::doFillGlyphCache(AbstractGlyphCache& cache, const std::u32string& characters) virtual private

Implementation for fillGlyphCache()

The string is converted from UTF-8 to UTF-32, unique characters are not removed.