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

Base for font converter plugins.

Provides functionality for converting an arbitrary font to different format. See Loading and using plugins for more information and the list of derived classes for available font converter plugins.

Data dependency

The AbstractGlyphCache instances returned from various functions by design have no dependency on the converter instance and neither on the dynamic plugin module. In other words, you don't need to keep the converter instance (or the plugin manager instance) around in order to have the AbstractGlyphCache instances valid. Moreover, all returned Containers::Array instances are only allowed to have default deleters — this is to avoid potential dangling function pointer calls when destructing such instances after the plugin module has been unloaded.

Subclassing

The plugin needs to implement doFeatures() function and one or more of doExportFontToData() / doExportFontToSingleData() / doExportFontToFile(), doExportGlyphCacheToData() / doExportGlyphCacheToSingleData() / doExportGlyphCacheToFile() or doImportGlyphCacheFromData() / doImportGlyphCacheFromSingleData() / doImportGlyphCacheFromFile() functions based on what features are supported. Characters passed to font exporting functions are converted to list of unique UTF-32 characters.

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

The doExportFontTo*() functions are called only if FontConverterFeature::ExportFont is supported, the doExportGlyphCacheTo*() functions are called only if FontConverterFeature::ExportGlyphCache is supported.
The doImportGlyphCacheFrom*() functions are called only if FontConverterFeature::ImportGlyphCache is supported.
The doExport*To*Data() and doImport*From*Data() functions are called only if FontConverterFeature::ConvertData is supported.
The doImport*FromData() function is called only if there is at least one data array passed.

Derived classes

class MagnumFontConverter: MagnumFont converter plugin.

Public types

using Feature = FontConverterFeature deprecated in 2020.06: Features supported by a font converter.
using Features = FontConverterFeatures deprecated in 2020.06: Features supported by a font converter.

Public static functions

static auto pluginInterface() -> Containers::StringView: Plugin interface.
static auto pluginSearchPaths() -> Containers::Array<Containers::String>: Plugin search paths.

Constructors, destructors, conversion operators

AbstractFontConverter() explicit: Default constructor.
AbstractFontConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit: Plugin manager constructor.

Public functions

auto features() const -> FontConverterFeatures: Features supported by this converter.
auto exportFontToData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::string& characters) const -> std::vector<std::pair<std::string, Containers::Array<char>>>: Export font to raw data.
auto exportFontToSingleData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& characters) const -> Containers::Array<char>: Export font to single raw data.
auto exportFontToFile(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::string& characters) const -> bool: Export font to file.
auto exportGlyphCacheToData(AbstractGlyphCache& cache, const std::string& filename) const -> std::vector<std::pair<std::string, Containers::Array<char>>>: Export glyph cache to raw data.
auto exportGlyphCacheToSingleData(AbstractGlyphCache& cache) const -> Containers::Array<char>: Export glyph cache to single raw data.
auto exportGlyphCacheToFile(AbstractGlyphCache& cache, const std::string& filename) const -> bool: Export glyph cache to file.
auto importGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data) const -> Containers::Pointer<AbstractGlyphCache>: Import glyph cache from raw data.
auto importGlyphCacheFromSingleData(Containers::ArrayView<const char> data) const -> Containers::Pointer<AbstractGlyphCache>: Import glyph cache from single raw data.
auto importGlyphCacheFromFile(const std::string& filename) const -> Containers::Pointer<AbstractGlyphCache>: Import glyph cache from file.

Private functions

auto doFeatures() const -> FontConverterFeatures pure virtual: Implementation for features()
auto doExportFontToData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::u32string& characters) const -> std::vector<std::pair<std::string, Containers::Array<char>>> virtual: Implementation for exportFontToData()
auto doExportFontToSingleData(AbstractFont& font, AbstractGlyphCache& cache, const std::u32string& characters) const -> Containers::Array<char> virtual: Implementation for exportFontToSingleData()
auto doExportFontToFile(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::u32string& characters) const -> bool virtual: Implementation for exportFontToFile()
auto doExportGlyphCacheToData(AbstractGlyphCache& cache, const std::string& filename) const -> std::vector<std::pair<std::string, Containers::Array<char>>> virtual: Implementation for exportGlyphCacheToData()
auto doExportGlyphCacheToSingleData(AbstractGlyphCache& cache) const -> Containers::Array<char> virtual: Implementation for exportGlyphCacheToSingleData()
auto doExportGlyphCacheToFile(AbstractGlyphCache& cache, const std::string& filename) const -> bool virtual: Implementation for exportGlyphCacheToFile()
auto doImportGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data) const -> Containers::Pointer<AbstractGlyphCache> virtual: Implementation for importGlyphCacheFromData()
auto doImportGlyphCacheFromSingleData(Containers::ArrayView<const char> data) const -> Containers::Pointer<AbstractGlyphCache> virtual: Implementation for importGlyphCacheFromSingleData()
auto doImportGlyphCacheFromFile(const std::string& filename) const -> Containers::Pointer<AbstractGlyphCache> virtual: Implementation for importGlyphCacheFromFile()

Typedef documentation

typedef FontConverterFeature Magnum::Text::AbstractFontConverter::Feature

Features supported by a font converter.

typedef FontConverterFeatures Magnum::Text::AbstractFontConverter::Features

Features supported by a font converter.

Function documentation

static Containers::StringView Magnum::Text::AbstractFontConverter::pluginInterface()

Plugin interface.

"cz.mosra.magnum.Text.AbstractFontConverter/0.2"

static Containers::Array<Containers::String> Magnum::Text::AbstractFontConverter::pluginSearchPaths()

Plugin search paths.

Looks into magnum/fontconverters/ or magnum-d/fontconverters/ next to the dynamic Trade library, next to the executable and elsewhere according to the rules documented in Corrade::PluginManager::implicitPluginSearchPaths(). The search directory can be also hardcoded using the MAGNUM_PLUGINS_DIR CMake variables, see Downloading and building for more information.

Not defined on platforms without dynamic plugin support.

std::vector<std::pair<std::string, Containers::Array<char>>> Magnum::Text::AbstractFontConverter::exportFontToData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::string& characters) const

Export font to raw data.

Parameters
font	Opened font
cache	Populated glyph cache
filename	Output filename
characters	Characters to export

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ExportFont is supported. Returns pairs of filename and data on success, prints a message to Error and returns an empty vector otherwise. All data will be sharing common basename derived from filename. If the plugin doesn't have FontConverterFeature::MultiFile, only one pair is returned, thus using exportFontToSingleData() might be more convenient in that case.

Containers::Array<char> Magnum::Text::AbstractFontConverter::exportFontToSingleData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& characters) const

Export font to single raw data.

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ExportFont is supported and the plugin doesn't have FontConverterFeature::MultiFile. On failure prints a message to Error and returns nullptr. See exportFontToData() for more information.

bool Magnum::Text::AbstractFontConverter::exportFontToFile(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::string& characters) const

Export font to file.

Available only if FontConverterFeature::ExportFont is supported. If the plugin has FontConverterFeature::MultiFile, the function will create more than one file in given path, all sharing common basename derived from filename. On failure prints a message to Error and returns false. See exportFontToData() for more information.

std::vector<std::pair<std::string, Containers::Array<char>>> Magnum::Text::AbstractFontConverter::exportGlyphCacheToData(AbstractGlyphCache& cache, const std::string& filename) const

Export glyph cache to raw data.

Parameters
cache	Populated glyph cache
filename	Output filename

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ExportGlyphCache is supported. Returns pairs of filename and data on success, prints a message to Error and returns an empty vector otherwise. All data will be sharing common basename derived from filename. If the plugin doesn't have FontConverterFeature::MultiFile, only one pair is returned, thus using exportGlyphCacheToSingleData() might be more convenient in that case.

All glyphs from given cache will be exported. If you want to export smaller subset, fill the cache with less characters.

Containers::Array<char> Magnum::Text::AbstractFontConverter::exportGlyphCacheToSingleData(AbstractGlyphCache& cache) const

Export glyph cache to single raw data.

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ExportGlyphCache is supported and the plugin doesn't have FontConverterFeature::MultiFile. On failure prints a message to Error and returns nullptr. See exportGlyphCacheToData() for more information.

bool Magnum::Text::AbstractFontConverter::exportGlyphCacheToFile(AbstractGlyphCache& cache, const std::string& filename) const

Export glyph cache to file.

Available only if FontConverterFeature::ExportGlyphCache is supported. If the plugin has FontConverterFeature::MultiFile, the function will create more than one file in given path, all sharing common basename derived from filename. On failure prints a message to Error and returns false.

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFontConverter::importGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data) const

Import glyph cache from raw data.

Parameters
data	Pairs of filename and file data

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ImportGlyphCache is supported. On failure prints a message to Error and returns nullptr. If the plugin doesn't have FontConverterFeature::MultiFile, only one file is needed, thus using importGlyphCacheFromSingleData() might be more convenient in that case.

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFontConverter::importGlyphCacheFromSingleData(Containers::ArrayView<const char> data) const

Import glyph cache from single raw data.

Available only if FontConverterFeature::ConvertData and FontConverterFeature::ImportGlyphCache is supported and the plugin doesn't have FontConverterFeature::MultiFile. On failure prints a message to Error and returns nullptr. See importGlyphCacheFromData() for multi-file conversion.

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFontConverter::importGlyphCacheFromFile(const std::string& filename) const

Import glyph cache from file.

Available only if FontConverterFeature::ImportGlyphCache is supported. If the plugin has FontConverterFeature::MultiFile, the function will use additional files in given path, all sharing common basename derived from filename. On failure prints a message to Error and returns nullptr.

std::vector<std::pair<std::string, Containers::Array<char>>> Magnum::Text::AbstractFontConverter::doExportFontToData(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::u32string& characters) const virtual private

Implementation for exportFontToData()

If the plugin doesn't have FontConverterFeature::MultiFile, default implementation calls doExportFontToSingleData().

bool Magnum::Text::AbstractFontConverter::doExportFontToFile(AbstractFont& font, AbstractGlyphCache& cache, const std::string& filename, const std::u32string& characters) const virtual private

Implementation for exportFontToFile()

If FontConverterFeature::ConvertData is supported, default implementation calls doExportFontToData() and saves the result to given file(s).

std::vector<std::pair<std::string, Containers::Array<char>>> Magnum::Text::AbstractFontConverter::doExportGlyphCacheToData(AbstractGlyphCache& cache, const std::string& filename) const virtual private

Implementation for exportGlyphCacheToData()

If the plugin doesn't have FontConverterFeature::MultiFile, default implementation calls doExportGlyphCacheToSingleData().

bool Magnum::Text::AbstractFontConverter::doExportGlyphCacheToFile(AbstractGlyphCache& cache, const std::string& filename) const virtual private

Implementation for exportGlyphCacheToFile()

If FontConverterFeature::ConvertData is supported, default implementation calls doExportGlyphCacheToData() and saves the result to given file(s).

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFontConverter::doImportGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayView<const char>>>& data) const virtual private

Implementation for importGlyphCacheFromData()

If the plugin doesn't have FontConverterFeature::MultiFile, default implementation calls doImportGlyphCacheFromSingleData().

Containers::Pointer<AbstractGlyphCache> Magnum::Text::AbstractFontConverter::doImportGlyphCacheFromFile(const std::string& filename) const virtual private

Implementation for importGlyphCacheFromFile()

If FontConverterFeature::ConvertData is supported and the plugin doesn't have FontConverterFeature::MultiFile, default implementation opens the file and calls doImportGlyphCacheFromSingleData() with its contents.