Magnum::Text::AbstractFont class

Base for font plugins.

Contents

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:

Derived classes

class FreeTypeFont
FreeType font plugin.
class MagnumFont
Simple bitmap font plugin.
class StbTrueTypeFont
TrueType font plugin using stb_freetype.

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() -> std::unique_ptr<GlyphCache>
Create glyph cache.
auto layout(const GlyphCache& cache, Float size, const std::string& text) -> std::unique_ptr<AbstractLayouter>
Layout the text using font's own layouter.

Protected types

struct Metrics
Font metrics.

Protected 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() -> std::unique_ptr<GlyphCache> virtual
Implementation for createGlyphCache()
auto doLayout(const GlyphCache& cache, Float size, const std::string& text) -> std::unique_ptr<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.

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.

std::unique_ptr<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().

std::unique_ptr<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 protected

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 protected

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 protected

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 protected

Implementation for fillGlyphCache()

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