From ac439d3b74d10689d037ddbb055f0696e69033f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 11 Jun 2026 22:27:18 +0200 Subject: [PATCH] Text,Trade: doc++ --- src/Magnum/Text/AbstractFont.h | 45 +++++++++++++++++++---------- src/Magnum/Trade/AbstractImporter.h | 21 ++++++++++++-- src/Magnum/Trade/Data.h | 5 +++- 3 files changed, 53 insertions(+), 18 deletions(-) diff --git a/src/Magnum/Text/AbstractFont.h b/src/Magnum/Text/AbstractFont.h index a0a18f907..3bbd71347 100644 --- a/src/Magnum/Text/AbstractFont.h +++ b/src/Magnum/Text/AbstractFont.h @@ -189,9 +189,10 @@ all glyphs in the font: @section Text-AbstractFont-usage-callbacks Loading data from memory, using file callbacks Besides loading data directly from the filesystem using @ref openFile() like -shown above, it's possible to use @ref openData() to import data from memory. -Note that the particular importer implementation must support -@ref FontFeature::OpenData for this method to work. +shown above, it's possible to use @ref openData() to load fonts from memory +(for example from @relativeref{Corrade,Utility::Resource}). Note that the +particular font implementation has to support @ref FontFeature::OpenData for +this method to work: @snippet Text.cpp AbstractFont-usage-data @@ -209,10 +210,10 @@ plugin supporting the callback feature handles that correctly. @snippet Text.cpp AbstractFont-usage-callbacks -For importers that don't support @ref FontFeature::FileCallback directly, the -base @ref openFile() implementation will use the file callback to pass the -loaded data through to @ref openData(), in case the importer supports at least -@ref FontFeature::OpenData. If the importer supports neither +For font plugins that don't support @ref FontFeature::FileCallback directly, +the base @ref openFile() implementation will use the file callback to pass the +loaded data through to @ref openData(), in case the font supports at least +@ref FontFeature::OpenData. If the font supports neither @ref FontFeature::FileCallback nor @ref FontFeature::OpenData, @ref setFileCallback() doesn't allow the callbacks to be set. @@ -229,10 +230,12 @@ instance is destroyed. @section Text-AbstractFont-subclassing Subclassing -The plugin needs to implement the @ref doFeatures(), @ref doClose(), -@ref doCreateShaper() functions, either @ref doCreateGlyphCache() or -@ref doFillGlyphCache() and one or more of `doOpen*()` functions. See also -@ref AbstractShaper for more information. +The plugin needs to implement the @ref doFeatures(), @ref doIsOpened(), +@ref doClose(), @ref doProperties(), @ref doGlyphIdsInto(), @ref doGlyphSize(), +@ref doGlyphAdvance(), @ref doCreateShaper() functions, either +@ref doCreateGlyphCache() or @ref doFillGlyphCache() and at least one of the +@ref doOpenData() or @ref doOpenFile() functions. See also @ref AbstractShaper +for more information. In order to support @ref FontFeature::FileCallback, the font needs to properly use the callbacks to both load the top-level file in @ref doOpenFile() and also @@ -359,8 +362,9 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { * 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 - * @ref InputFileCallbackPolicy. Documentation of particular importers - * provides more information about the expected callback behavior. + * @ref InputFileCallbackPolicy. Documentation of particular font + * plugins 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 @ref Corrade::Utility::Resource. @@ -840,7 +844,13 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { */ virtual void doSetFileCallback(Containers::Optional>(*callback)(const std::string&, InputFileCallbackPolicy, void*), void* userData); - /** @brief Implementation for @ref isOpened() */ + /** + * @brief Implementation for @ref isOpened() + * + * The function should return @cpp true @ce if a @ref doOpenFile() + * or @ref doOpenData() was successful and @ref doClose() wasn't called + * since, @cpp false @ce otherwise. + */ virtual bool doIsOpened() const = 0; /** @@ -884,7 +894,12 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { virtual Properties doOpenData(Containers::ArrayView data, Float size); #endif - /** @brief Implementation for @ref close() */ + /** + * @brief Implementation for @ref close() + * + * The @ref doIsOpened() implementation should return @cpp false @ce + * after calling this function. + */ virtual void doClose() = 0; /** diff --git a/src/Magnum/Trade/AbstractImporter.h b/src/Magnum/Trade/AbstractImporter.h index f89a9f072..b308b7c78 100644 --- a/src/Magnum/Trade/AbstractImporter.h +++ b/src/Magnum/Trade/AbstractImporter.h @@ -1794,6 +1794,9 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi /** * @brief Implementation for @ref openFile() * + * If the operation was successful, @ref doIsOpened() should return + * @cpp true @ce after calling this function, @cpp false @ce otherwise. + * * If @ref ImporterFeature::OpenData is supported, default * implementation opens the file and calls @ref doOpenData() with its * contents. It is allowed to call this function from your @@ -1838,13 +1841,22 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi */ virtual void doSetFileCallback(Containers::Optional>(*callback)(const std::string&, InputFileCallbackPolicy, void*), void* userData); - /** @brief Implementation for @ref isOpened() */ + /** + * @brief Implementation for @ref isOpened() + * + * The function should return @cpp true @ce if a @ref doOpenFile(), + * @ref doOpenData() or @ref doOpenState() was successful and + * @ref doClose() wasn't called since, @cpp false @ce otherwise. + */ virtual bool doIsOpened() const = 0; /** * @brief Implementation for @ref openData() and @ref openMemory() * @m_since_latest * + * If the operation was successful, @ref doIsOpened() should return + * @cpp true @ce after calling this function, @cpp false @ce otherwise. + * * The @p data is mutable or owned depending on the value of * @p dataFlags. This can be used for example to avoid allocating a * local copy in order to preserve its lifetime. The following cases @@ -1898,7 +1910,12 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi /** @brief Implementation for @ref openState() */ virtual void doOpenState(const void* state, Containers::StringView filePath); - /** @brief Implementation for @ref close() */ + /** + * @brief Implementation for @ref close() + * + * The @ref doIsOpened() implementation should return @cpp false @ce + * after calling this function. + */ virtual void doClose() = 0; /** diff --git a/src/Magnum/Trade/Data.h b/src/Magnum/Trade/Data.h index bb1f1ad23..741c38bc7 100644 --- a/src/Magnum/Trade/Data.h +++ b/src/Magnum/Trade/Data.h @@ -103,7 +103,10 @@ MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, DataFlag value); @m_since{2020,06} @see @ref AnimationData::dataFlags(), @ref ImageData::dataFlags(), - @ref MeshData::indexDataFlags(), @ref MeshData::vertexDataFlags() + @ref MaterialData::attributeDataFlags(), + @ref MaterialData::layerDataFlags(), @ref MeshData::indexDataFlags(), + @ref MeshData::vertexDataFlags(), @ref SceneData::dataFlags(), + @ref AbstractImporter::doOpenData() */ typedef Containers::EnumSet DataFlags;