Magnum::Text::AbstractFontConverter class

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:

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.