Magnum::Text::AbstractFont class
#include <Magnum/Text/AbstractFont.h>

Base for font plugins.

Usage
Subclassing
Reference

Provides interface for opening fonts, filling glyph cache and layouting the glyphs. See Loading and using plugins for more information and *Font classes in Text namespace for available font plugins.

Usage

First step is to open the font using openData(), openSingleData() or openFile(). Next step is to prerender all the glyphs which will be used in text rendering later, see GlyphCache for more information. See Renderer for information about text rendering.

Subclassing

Plugin implements doFeatures(), doClose(), doLayout(), either doCreateGlyphCache() or doFillGlyphCache() and one or more of doOpen*() functions. See also AbstractLayouter for more information.

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

Functions doOpenData(), doOpenSingleData() and doOpenFile() are called after the previous file was closed, function doClose() is called only if there is any file opened.
Functions doOpenData() and doOpenSingleData() are called only if Feature::OpenData is supported.
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

enum class Feature: UnsignedByte { OpenData = 1 << 0, MultiFile = 1 << 1, PreparedGlyphCache = 1 << 2 }: Features supported by this importer.
using Features = Containers::EnumSet<Feature>: Set of features supported by this importer.

Public static functions

static auto pluginInterface() -> std::string: Plugin interface.
static auto pluginSearchPaths() -> std::vector<std::string>: Plugin search paths.

Constructors, destructors, conversion operators

AbstractFont() explicit: Default constructor.
AbstractFont(PluginManager::AbstractManager& manager, const std::string& plugin) explicit: Plugin manager constructor.

Public functions

auto features() const -> Features: Features supported by this font.
auto isOpened() const -> bool: Whether any file is opened.
auto openData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data, Float size) -> bool: Open font from raw data.
auto openSingleData(Containers::ArrayView<const char> data, Float size) -> bool: Open font from single data.
auto openFile(const std::string& filename, Float size) -> bool: Open font from file.
void close(): Close font.
auto size() const -> Float: Font size.
auto ascent() const -> Float: Font ascent.
auto descent() const -> Float: Font descent.
auto lineHeight() const -> Float: Line height.
auto glyphId(char32_t character) -> UnsignedInt: Glyph ID for given character.
auto glyphAdvance(UnsignedInt glyph) -> Vector2: Glyph advance.
void fillGlyphCache(GlyphCache& cache, const std::string& characters): Fill glyph cache with given character set.
auto createGlyphCache() -> Containers::Pointer<GlyphCache>: Create glyph cache.
auto layout(const GlyphCache& cache, Float size, const std::string& text) -> Containers::Pointer<AbstractLayouter>: Layout the text using font's own layouter.

Protected types

struct Metrics: Font metrics.

Private functions

auto doFeatures() const -> Features pure virtual: Implementation for features()
auto doIsOpened() const -> bool pure virtual: Implementation for isOpened()
auto doOpenData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data, Float size) -> Metrics virtual: Implementation for openData()
auto doOpenSingleData(Containers::ArrayView<const char> data, Float size) -> Metrics virtual: Implementation for openSingleData()
auto doOpenFile(const std::string& filename, Float size) -> Metrics virtual: Implementation for openFile()
void doClose() pure virtual: Implementation for close()
auto doGlyphId(char32_t character) -> UnsignedInt pure virtual: Implementation for glyphId()
auto doGlyphAdvance(UnsignedInt glyph) -> Vector2 pure virtual: Implementation for glyphAdvance()
void doFillGlyphCache(GlyphCache& cache, const std::u32string& characters) virtual: Implementation for fillGlyphCache()
auto doCreateGlyphCache() -> Containers::Pointer<GlyphCache> virtual: Implementation for createGlyphCache()
auto doLayout(const GlyphCache& cache, Float size, const std::string& text) -> Containers::Pointer<AbstractLayouter> pure virtual: Implementation for layout()

Enum documentation

enum class Magnum::Text::AbstractFont::Feature: UnsignedByte

Features supported by this importer.

Enumerators
OpenData	Opening fonts from raw data using openData()
MultiFile	The format is multi-file, thus openSingleData() convenience function cannot be used.
PreparedGlyphCache	The font contains prepared glyph cache. See also fillGlyphCache(), createGlyphCache()

Function documentation

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

Plugin interface.

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

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

Plugin search paths.

First looks in magnum/fonts/ or magnum-d/fonts/ 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.

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

Open font from raw data.

Parameters
data	Pairs of filename and file data
size	Font size

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

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

Open font from single data.

Parameters
data	File data
size	Font size

Closes previous file, if it was opened, and tries to open given file. Available only if Feature::OpenData is supported and the plugin doesn't have Feature::MultiFile. Returns true on success, false otherwise.

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

Open font from file.

Parameters
filename	Font file
size	Font size

Closes previous file, if it was opened, and tries to open given file. If the plugin has Feature::MultiFile, the function will use additional files in given path, all sharing common basename derived from filename. 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.

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

Font ascent.

Distance from baseline to top, scaled to font size. Positive value.

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

Font descent.

Distance from baseline to bottom, scalled to font size. Negative value.

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

Line height.

Returns line height scaled to font size.

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

Glyph ID for given character.

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

Glyph advance.

Parameters
glyph	Glyph ID

Returns glyph advance scaled to font size.

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

Fill glyph cache with given character set.

Parameters
cache	Glyph cache instance
characters	UTF-8 characters to render

Fills the cache with given characters. Fonts having Feature::PreparedGlyphCache do not support partial glyph cache filling, use createGlyphCache() instead.

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

Create glyph cache.

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

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

Layout the text using font's own layouter.

Parameters
cache	Glyph cache
size	Font size
text	Text to layout

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

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

Implementation for openData()

Return metrics of opened font on successful opening, zeros otherwise. If the plugin doesn't have Feature::MultiFile, default implementation calls doOpenSingleData().

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

Implementation for openSingleData()

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

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

Implementation for openFile()

Return metrics of opened font on successful opening, zeros otherwise. If Feature::OpenData is supported and the plugin doesn't have Feature::MultiFile, default implementation opens the file and calls doOpenSingleData() with its contents.

void Magnum::Text::AbstractFont::doFillGlyphCache(GlyphCache& 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.