class
#include <Magnum/Text/AbstractFont.h>
AbstractFont Base for font plugins.
Contents
Provides interface for opening fonts, filling glyph cache and layouting the glyphs.
Usage
Fonts are most commonly implemented as plugins. For example, loading a font from the filesystem using the StbTrueTypeFont plugin and prerendering all needed glyphs can be done like this, completely with all error handling:
PluginManager::Manager<Text::AbstractFont> manager; Containers::Pointer<Text::AbstractFont> font = manager.loadAndInstantiate("StbTrueTypeFont"); if(!font || !font->openFile("font.ttf", 16.0f)) Fatal{} << "Can't open font.ttf with StbTrueTypeFont"; Text::GlyphCache cache{Vector2i{512}}; font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789?!:;,. ");
See Loading and using plugins for more information about general plugin usage and *Font
classes in the Text namespace for available font plugins. See GlyphCache for more information about glyph caches and Renderer for information about actual text rendering.
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::
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::
struct Data { std::unordered_map<std::string, Containers::Array<const char, Utility::Directory::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(found == data.files.end()) found = data.files.emplace( filename, Utility::Directory::mapRead(filename)).first; return Containers::arrayView(found->second); }, data); font->openFile("magnum-font.conf", 13.0f);
For importers that don't support FontFeature::
The input file callback signature is the same for Text::
Subclassing
The 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() and doOpenFile() are called after the previous file was closed, function doClose() is called only if there is any file opened.
- Function 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() -> 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 -> 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 char> data, Float size) -> bool - Open font from raw data.
-
auto openData(const std::
vector<std:: pair<std:: string, Containers:: ArrayView<const char>>>& data, Float size) -> bool deprecated in 2019.10 - Open font from raw data.
-
auto openSingleData(Containers::
ArrayView<const char> data, Float size) -> bool deprecated in 2019.10 - Open font from raw 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(AbstractGlyphCache& cache,
const std::
string& characters) - Fill glyph cache with given character set.
-
auto createGlyphCache() -> Containers::
Pointer<AbstractGlyphCache> - Create glyph cache.
-
auto layout(const AbstractGlyphCache& cache,
Float size,
const std::
string& text) -> Containers:: Pointer<AbstractLayouter> - Layout the text using font's own layouter.
Protected types
- struct Metrics
- Font metrics.
Protected functions
-
auto doOpenFile(const std::
string& filename, Float size) -> Metrics 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) -> Metrics virtual - Implementation for openData()
- 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(AbstractGlyphCache& cache,
const std::
u32string& characters) virtual - Implementation for fillGlyphCache()
-
auto doCreateGlyphCache() -> Containers::
Pointer<AbstractGlyphCache> virtual - Implementation for createGlyphCache()
-
auto doLayout(const AbstractGlyphCache& cache,
Float size,
const std::
string& text) -> Containers:: Pointer<AbstractLayouter> pure virtual - Implementation for layout()
Typedef documentation
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.
Function documentation
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.
Looks into magnum/fonts/
or magnum-d/fonts/
next to the dynamic Trade library, next to the executable and elsewhere according to the rules documented in Corrade::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::userData
pointer as input and returns a non-owning view on the loaded data as output or a Corrade::nullptr
can't be used to indicate a failure.
In case the font plugin doesn't support FontFeature::
In case callback
is nullptr
, the current callback (if any) is reset. This function expects that the font plugin supports either FontFeature::
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::
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 — this reuses an existing Corrade::
const Utility::Resource rs{"data"}; font->setFileCallback([](const std::string& filename, InputFileCallbackPolicy, const Utility::Resource& rs) { return Containers::optional(rs.getRaw(filename)); }, rs);
bool Magnum:: Text:: AbstractFont:: openData(Containers:: ArrayView<const char> data,
Float size)
Open font from raw data.
Parameters | |
---|---|
data | File data |
size | Font size |
Closes previous file, if it was opened, and tries to open given file. Available only if FontFeature::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.
Parameters | |
---|---|
filename | Font file |
size | Font size |
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:: 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.
Parameters | |
---|---|
glyph | Glyph ID |
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.
Parameters | |
---|---|
cache | Glyph cache instance |
characters | UTF-8 characters to render |
Fills the cache with given characters. Fonts having FontFeature::
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::
Containers:: Pointer<AbstractLayouter> Magnum:: Text:: AbstractFont:: layout(const AbstractGlyphCache& 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. 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::
This function is not called when file callbacks are set through setFileCallback() and FontFeature::
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.