diff --git a/src/Magnum/Text/AbstractFont.h b/src/Magnum/Text/AbstractFont.h index 6a318b9d3..20fc8a954 100644 --- a/src/Magnum/Text/AbstractFont.h +++ b/src/Magnum/Text/AbstractFont.h @@ -48,14 +48,14 @@ Provides interface for opening fonts, filling glyph cache and layouting the glyphs. See @ref plugins for more information and `*Font` classes in @ref Text namespace for available font plugins. -## Usage +@section Text-AbstractFont-usage Usage First step is to open the font using @ref openData(), @ref openSingleData() or @ref openFile(). Next step is to prerender all the glyphs which will be used in text rendering later, see @ref GlyphCache for more information. See @ref Renderer for information about text rendering. -## Subclassing +@section Text-AbstractFont-subclassing Subclassing Plugin implements @ref doFeatures(), @ref doClose(), @ref doLayout(), either @ref doCreateGlyphCache() or @ref doFillGlyphCache() and one or more of @@ -72,7 +72,7 @@ checked by the implementation: - All `do*()` implementations working on opened file are called only if there is any file opened. -Plugin interface string is `"cz.mosra.magnum.Text.AbstractFont/0.2.4"`. +Plugin interface string is @cpp "cz.mosra.magnum.Text.AbstractFont/0.2.4" @ce. */ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { CORRADE_PLUGIN_INTERFACE("cz.mosra.magnum.Text.AbstractFont/0.2.4") @@ -123,7 +123,7 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { * * Closes previous file, if it was opened, and tries to open given * file. Available only if @ref Feature::OpenData is supported. Returns - * `true` on success, `false` otherwise. + * @cpp true @ce on success, @cpp false @ce otherwise. */ bool openData(const std::vector>>& data, Float size); @@ -134,8 +134,8 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { * * Closes previous file, if it was opened, and tries to open given * file. Available only if @ref Feature::OpenData is supported and the - * plugin doesn't have @ref Feature::MultiFile. Returns `true` on - * success, `false` otherwise. + * plugin doesn't have @ref Feature::MultiFile. Returns @cpp true @ce + * on success, @cpp false @ce otherwise. */ bool openSingleData(Containers::ArrayView data, Float size); @@ -147,8 +147,8 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { * Closes previous file, if it was opened, and tries to open given * file. If the plugin has @ref Feature::MultiFile, the function will * use additional files in given path, all sharing common basename - * derived from @p filename. Returns `true` on success, `false` - * otherwise. + * derived from @p filename. Returns @cpp true @ce on success, + * @cpp false @ce otherwise. */ bool openFile(const std::string& filename, Float size); @@ -348,7 +348,7 @@ CORRADE_ENUMSET_OPERATORS(AbstractFont::Features) Returned by @ref AbstractFont::layout(). -## Subclassing +@section Text-AbstractLayouter-subclassing Subclassing Plugin creates private subclass (no need to expose it to end users) and implements @ref doRenderGlyph(). Bounds checking on @p i is done automatically diff --git a/src/Magnum/Text/AbstractFontConverter.h b/src/Magnum/Text/AbstractFontConverter.h index 7a74ae818..5646892cc 100644 --- a/src/Magnum/Text/AbstractFontConverter.h +++ b/src/Magnum/Text/AbstractFontConverter.h @@ -48,7 +48,7 @@ namespace for available font converter plugins. You can use the @ref magnum-fontconverter "magnum-fontconverter" utility to do font conversion on command-line. -## Subclassing +@section Text-AbstractFontConverter-subclassing Subclassing Plugin implements @ref doFeatures() and one or more of `exportTo*()` / `importFrom*()` functions based on what features are supported. Characters @@ -68,7 +68,7 @@ checked by the implementation: - Function `doImport*FromData()` is called only if there is at least one data array passed. -Plugin interface string is `"cz.mosra.magnum.Text.AbstractFontConverter/0.1.2"`. +Plugin interface string is @cpp "cz.mosra.magnum.Text.AbstractFontConverter/0.1.2" @ce. @attention @ref Corrade::Containers::Array instances returned from the plugin should *not* use anything else than the default deleter, otherwise this can @@ -174,8 +174,8 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl * Available only if @ref Feature::ExportFont is supported. If the * plugin has @ref Feature::MultiFile, the function will create more * than one file in given path, all sharing common basename derived - * from @p filename. Returns `true` on success, `false` otherwise. See - * @ref exportFontToData() for more information. + * from @p filename. Returns @cpp true @ce on success, @cpp false @ce + * otherwise. See @ref exportFontToData() for more information. * @see @ref features(), @ref exportFontToData(), * @ref exportGlyphCacheToFile() */ @@ -218,8 +218,8 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl * Available only if @ref Feature::ExportGlyphCache is supported. If * the plugin has @ref Feature::MultiFile, the function will create * more than one file in given path, all sharing common basename - * derived from @p filename. Returns `true` on success, `false` - * otherwise. + * derived from @p filename. Returns @cpp true @ce on success, + * @cpp false @ce otherwise. * @see @ref features(), @ref exportGlyphCacheToData(), * @ref exportFontToFile() */ @@ -230,7 +230,7 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl * @param data Pairs of filename and file data * * Available only if @ref Feature::ConvertData and @ref Feature::ImportGlyphCache - * is supported. Returns imported cache on success, `nullptr` + * is supported. Returns imported cache on success, @cpp nullptr @ce * otherwise. If the plugin doesn't have @ref Feature::MultiFile, only * one file is needed, thus using @ref importGlyphCacheFromSingleData() * might be more convenient in that case. @@ -244,7 +244,7 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl * * Available only if @ref Feature::ConvertData and @ref Feature::ImportGlyphCache * is supported and the plugin doesn't have @ref Feature::MultiFile. - * Returns imported cache on success, `nullptr` otherwise. See + * Returns imported cache on success, @cpp nullptr @ce otherwise. See * @ref importGlyphCacheFromData() for multi-file conversion. * @see @ref features(), @ref importGlyphCacheFromFile(), * @ref exportFontToSingleData() @@ -257,7 +257,7 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl * Available only if @ref Feature::ImportGlyphCache is supported. If * the plugin has @ref Feature::MultiFile, the function will use * additional files in given path, all sharing common basename derived - * from @p filename. Returns imported cache on success, `nullptr` + * from @p filename. Returns imported cache on success, @cpp nullptr @ce * otherwise. * @see @ref features(), @ref importGlyphCacheFromData(), * @ref exportGlyphCacheToFile() diff --git a/src/Magnum/Text/DistanceFieldGlyphCache.h b/src/Magnum/Text/DistanceFieldGlyphCache.h index 94701aa1a..179e6e301 100644 --- a/src/Magnum/Text/DistanceFieldGlyphCache.h +++ b/src/Magnum/Text/DistanceFieldGlyphCache.h @@ -40,11 +40,12 @@ Unlike original @ref GlyphCache converts each binary image to distance field. It is not possible to use non-binary colors with this cache, internal texture format is red channel only. -## Usage +@section Text-DistanceFieldGlyphCache-usage Usage Usage is similar to @ref GlyphCache, additionally you need to specify size of resulting distance field texture. -@code + +@code{.cpp} Text::AbstractFont* font; Text::GlyphCache* cache = new Text::DistanceFieldGlyphCache(Vector2i(2048), Vector2i(384)); font->createGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" diff --git a/src/Magnum/Text/GlyphCache.h b/src/Magnum/Text/GlyphCache.h index 919a2f741..52fde7f5f 100644 --- a/src/Magnum/Text/GlyphCache.h +++ b/src/Magnum/Text/GlyphCache.h @@ -43,11 +43,12 @@ namespace Magnum { namespace Text { Contains font glyphs prerendered into texture atlas. -## Usage +@section Text-GlyphCache-usage Usage Create GlyphCache object with sufficient size and then call @ref AbstractFont::createGlyphCache() to fill it with glyphs. -@code + +@code{.cpp} Text::AbstractFont* font; Text::GlyphCache* cache = new GlyphCache(Vector2i(512)); font->createGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" @@ -126,9 +127,9 @@ class MAGNUM_TEXT_EXPORT GlyphCache { * * Returned values include padding. * - * If no glyph is found, glyph `0` is returned, which is by default on - * zero position and has zero region in texture atlas. You can reset it - * to some meaningful value in @ref insert(). + * If no glyph is found, glyph @cpp 0 @ce is returned, which is by + * default on zero position and has zero region in texture atlas. You + * can reset it to some meaningful value in @ref insert(). * @see @ref padding() */ std::pair operator[](UnsignedInt glyph) const { @@ -170,7 +171,7 @@ class MAGNUM_TEXT_EXPORT GlyphCache { * * You can obtain unused non-overlapping regions with @ref reserve(). * You can't overwrite already inserted glyph, however you can reset - * glyph `0` to some meaningful value. + * glyph @cpp 0 @ce to some meaningful value. * * Glyph parameters are expected to be without padding. * diff --git a/src/Magnum/Text/Renderer.h b/src/Magnum/Text/Renderer.h index dd819e506..d4b9be75f 100644 --- a/src/Magnum/Text/Renderer.h +++ b/src/Magnum/Text/Renderer.h @@ -171,13 +171,14 @@ class MAGNUM_TEXT_EXPORT AbstractRenderer { Lays out the text into mesh using given font. Use of ligatures, kerning etc. depends on features supported by particular font and its layouter. -## Usage +@section Text-Renderer-usage Usage Immutable text (e.g. menu items, credits) can be simply rendered using static methods, returning result either as data arrays or as fully configured mesh. The text can be then drawn as usual by configuring the shader and drawing the mesh: -@code + +@code{.cpp} // Font instance, received from plugin manager std::unique_ptr font; @@ -198,6 +199,7 @@ shader.setTransformationProjectionMatrix(projection) .setVectorTexture(glyphCache->texture()); mesh.draw(shader); @endcode + See @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, BufferUsage, Alignment) for more information. @@ -205,7 +207,8 @@ for more information. While this method is sufficient for one-shot rendering of static texts, for mutable texts (e.g. FPS counters, chat messages) there is another approach that doesn't recreate everything on each text change: -@code + +@code{.cpp} std::unique_ptr font; Text::GlyphCache cache; Shaders::Vector2D shader; @@ -224,7 +227,7 @@ shader.setTransformationProjectionMatrix(projection) renderer.mesh().draw(shader); @endcode -## Required OpenGL functionality +@section Text-Renderer-required-opengl-functionality Required OpenGL functionality Mutable text rendering requires @extension{ARB,map_buffer_range} on desktop OpenGL (also part of OpenGL ES 3.0). If neither @extension{EXT,map_buffer_range} @@ -264,7 +267,9 @@ template class MAGNUM_TEXT_EXPORT Renderer: public Abstr explicit Renderer(AbstractFont& font, const GlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft); Renderer(AbstractFont&, GlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */ + #ifndef DOXYGEN_GENERATING_OUTPUT using AbstractRenderer::render; + #endif }; /** @brief Two-dimensional text renderer */ diff --git a/src/Magnum/Text/Text.h b/src/Magnum/Text/Text.h index 2d4bd6f9f..ac9d44117 100644 --- a/src/Magnum/Text/Text.h +++ b/src/Magnum/Text/Text.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Forward declarations for @ref Magnum::Text namespace + * @brief Forward declarations for the @ref Magnum::Text namespace */ #include "Magnum/Types.h"