diff --git a/doc/changelog-old.dox b/doc/changelog-old.dox index 70a22f908..e4fc58d17 100644 --- a/doc/changelog-old.dox +++ b/doc/changelog-old.dox @@ -1419,7 +1419,7 @@ for a high-level overview. - Removed deprecated `Shaders/magnumShadersResourceImport.hpp` file, use `Shaders/resourceImport.hpp` instead. - Removed deprecated @cpp Text::TextRenderer @ce alias, use - @ref Text::Renderer instead. + @cpp Text::Renderer @ce instead. - Removed long-deprecated @cpp BufferImage::setData() @ce overload, use the other one instead. @@ -1636,7 +1636,7 @@ No dependency changes in this release. @ref troubleshooting "troubleshooting page" for most common building and rendering issues - Support for horizontal and vertical text alignment and multi-line text in - @ref Text::Renderer (line wrapping is still left up to the user) + @cpp Text::Renderer @ce (line wrapping is still left up to the user) - New @ref magnum-fontconverter utility for converting between font formats (e.g. creating distance-field raster font from TTF font). Enable it with `WITH_FONTCONVERTER` CMake option (currently Linux only), see @@ -1766,7 +1766,7 @@ No dependency changes in this release. favor of less verbose `Magnum/Shaders/resourceImport.hpp` - @cpp Text::TextRenderer @ce class (and @cpp Text::TextRenderer2D @ce, @cpp Text::TextRenderer3D @ce typedefs) is deprecated, use less redundant - name @ref Text::Renderer instead + name @cpp Text::Renderer @ce instead @subsection changelog-2014-01-compatibility Potential compatibility breakages, removed APIs diff --git a/doc/changelog.dox b/doc/changelog.dox index 81fca970f..a5faed3fb 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -908,7 +908,7 @@ See also: - Added @ref Text::AbstractFont::glyphCount() and @relativeref{Text::AbstractFont,glyphSize()} -- Added @ref Text::Renderer::fontSize() +- Added @ref Text::AbstractRenderer::fontSize() - @ref Text::Alignment now has separate values for alignment based on font metrics and cursor position alone, which is the more commonly expected behavior, and `*GlyphBounds` values that align based on actual glyph @@ -1985,6 +1985,11 @@ See also: - The @ref Text::AbstractGlyphCache::image() query now returns a @ref MutableImageView3D instead of an @ref Image2D in order to support incremental population and texture arrays +- The @cpp Text::Renderer @ce class template was renamed to + @ref Text::BasicRenderer in order to make room for a new, more flexible + implementation. The assumption is that most existing code uses it through + the @ref Text::Renderer2D and @ref Text::Renderer3D typedefs and thus it + shouldn't result in any breakage. - The @ref Text::Alignment left, right, top and middle values now work with the font metrics and cursor position instead of glyph bounding rectangles, as that's the more commonly expected behavior. The original behavior with @@ -3154,7 +3159,7 @@ Released 2019-10-24, tagged as - A new @ref Text::AbstractGlyphCache base now makes @ref Text::AbstractFont and @ref Text::AbstractFontConverter independent on the graphics API used, meaning the @ref Text library now has just an optional dependency on - @ref GL. The @ref Text::Renderer, @cpp Text::GlyphCache @ce and + @ref GL. The @cpp Text::Renderer @ce, @cpp Text::GlyphCache @ce and @cpp Text::DistanceFieldGlyphCache @ce classes are now built only if `TARGET_GL` is enabled (done by default). - New @ref Text::AbstractFont::setFileCallback() to allow opening multi-file diff --git a/doc/snippets/Text-gl.cpp b/doc/snippets/Text-gl.cpp index 54ec38c4d..5727ff1fb 100644 --- a/doc/snippets/Text-gl.cpp +++ b/doc/snippets/Text-gl.cpp @@ -111,7 +111,7 @@ font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" the font pointer. I don't care, I just want you to check compilation errors, not more! */ PluginManager::Manager manager; -/* [Renderer-usage1] */ +/* [BasicRenderer-usage1] */ /* Font instance, received from a plugin manager */ Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); @@ -143,9 +143,9 @@ shader .setColor(0xffffff_rgbf) .bindVectorTexture(cache.texture()) .draw(mesh); -/* [Renderer-usage1] */ +/* [BasicRenderer-usage1] */ -/* [Renderer-usage2] */ +/* [BasicRenderer-usage2] */ /* Initialize the renderer and reserve memory for enough glyphs */ Text::Renderer2D renderer{*font, cache, 12.0f, Text::Alignment::LineCenter}; renderer.reserve(32, GL::BufferUsage::DynamicDraw, GL::BufferUsage::StaticDraw); @@ -158,17 +158,17 @@ shader.setTransformationProjectionMatrix(projectionMatrix) .setColor(0xffffff_rgbf) .bindVectorTexture(cache.texture()) .draw(renderer.mesh()); -/* [Renderer-usage2] */ +/* [BasicRenderer-usage2] */ } { -/* [Renderer-dpi-interface-size] */ +/* [BasicRenderer-dpi-interface-size] */ Vector2 interfaceSize = Vector2{windowSize()}/dpiScaling(); -/* [Renderer-dpi-interface-size] */ -/* [Renderer-dpi-size-multiplier] */ +/* [BasicRenderer-dpi-interface-size] */ +/* [BasicRenderer-dpi-size-multiplier] */ Float sizeMultiplier = (Vector2{framebufferSize()}*dpiScaling()/Vector2{windowSize()}).max(); -/* [Renderer-dpi-size-multiplier] */ +/* [BasicRenderer-dpi-size-multiplier] */ static_cast(interfaceSize); static_cast(sizeMultiplier); } diff --git a/src/Magnum/Text/AbstractFont.h b/src/Magnum/Text/AbstractFont.h index 65ac0616d..fe2850291 100644 --- a/src/Magnum/Text/AbstractFont.h +++ b/src/Magnum/Text/AbstractFont.h @@ -122,7 +122,7 @@ all error handling: See @ref plugins for more information about general plugin usage and the list of @m_class{m-doc} derived classes for available font plugins. See @ref GlyphCache for more information about glyph caches and -@ref Renderer for information about actual text rendering. +@ref BasicRenderer "Renderer*D" for information about actual text rendering. @subsection Text-AbstractFont-usage-font-size Font size @@ -136,14 +136,15 @@ properties are specified *in pixels* in @ref lineHeight(), @ref ascent() and @ref descent(). The font size used when opening the font affects how large the glyphs will be -when rendered into the @ref GlyphCache. Actual text rendering with @ref Renderer -however uses its own font size, and the rendered size is then additionally -depending on the actual projection used. This decoupling of font sizes is -useful for example in case of @ref DistanceFieldGlyphCache, where a single -prerendered glyph size can be used to render arbitrarily large font sizes -without becoming blurry or jaggy. When not using a distance field glyph cache, -it's usually desirable to have the font size and the actual rendered size -match. See @ref Text-Renderer-usage-font-size "the Renderer documentation" for +when rendered into the @ref GlyphCache. Actual text rendering with +@ref BasicRenderer "Renderer*D" however uses its own font size, and the +rendered size is then additionally depending on the actual projection used. +This decoupling of font sizes is useful for example in case of +@ref DistanceFieldGlyphCache, where a single prerendered glyph size can be used +to render arbitrarily large font sizes without becoming blurry or jaggy. When +not using a distance field glyph cache, it's usually desirable to have the font +size and the actual rendered size match. See +@ref Text-BasicRenderer-usage-font-size "the Renderer*D documentation" for further information about picking font sizes. @subsection Text-AbstractFont-usage-callbacks Loading data from memory, using file callbacks @@ -604,8 +605,8 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { * @ref AbstractShaper class instead. * * Note that the layouters support rendering of single-line text only. - * See @ref Renderer class for more advanced text layouting. Expects - * that a font is opened. + * See @ref BasicRenderer "Renderer*D" class for more advanced text + * layouting. Expects that a font is opened. * @see @ref fillGlyphCache(), @ref createGlyphCache() */ CORRADE_DEPRECATED("use createShaper() instead") Containers::Pointer layout(const AbstractGlyphCache& cache, Float size, Containers::StringView text); diff --git a/src/Magnum/Text/Alignment.h b/src/Magnum/Text/Alignment.h index 45e4924fb..c8a6bea2a 100644 --- a/src/Magnum/Text/Alignment.h +++ b/src/Magnum/Text/Alignment.h @@ -86,7 +86,8 @@ respectively, if @ref ShapeDirection::LeftToRight is passed to @ref ShapeDirection::RightToLeft is set (or detected for @ref ShapeDirection::Unspecified), they're swapped, i.e. `*Begin` becomes `*Right` and `*End` becomes `*Left`. -@see @ref Renderer::render(), @ref Renderer::Renderer(), +@see @ref BasicRenderer::render() "Renderer*D::render()", + @ref BasicRenderer::BasicRenderer() "Renderer*D::Renderer*D()", @see @ref alignmentForDirection() */ enum class Alignment: UnsignedByte { diff --git a/src/Magnum/Text/DistanceFieldGlyphCacheGL.h b/src/Magnum/Text/DistanceFieldGlyphCacheGL.h index 333c5cadd..bc3c63969 100644 --- a/src/Magnum/Text/DistanceFieldGlyphCacheGL.h +++ b/src/Magnum/Text/DistanceFieldGlyphCacheGL.h @@ -71,9 +71,9 @@ channels. @snippet Text-gl.cpp DistanceFieldGlyphCacheGL-usage -See the @ref Renderer class for information about text rendering. The -@ref AbstractGlyphCache base class has more information about general glyph -cache usage. +See the @ref BasicRenderer "Renderer*D" class for information about text +rendering. The @ref AbstractGlyphCache base class has more information about +general glyph cache usage. @section Text-DistanceFieldGlyphCacheGL-internal-format Internal texture format diff --git a/src/Magnum/Text/GlyphCacheGL.h b/src/Magnum/Text/GlyphCacheGL.h index d4021bb45..773df468d 100644 --- a/src/Magnum/Text/GlyphCacheGL.h +++ b/src/Magnum/Text/GlyphCacheGL.h @@ -52,9 +52,9 @@ Create the @ref GlyphCacheGL object with sufficient size and then call @snippet Text-gl.cpp GlyphCacheGL-usage -See the @ref Renderer class for information about text rendering. The -@ref AbstractGlyphCache base class has more information about general glyph -cache usage. +See the @ref BasicRenderer "Renderer*D" class for information about text +rendering. The @ref AbstractGlyphCache base class has more information about +general glyph cache usage. @section Text-GlyphCacheGL-internal-format Internal texture format diff --git a/src/Magnum/Text/Renderer.cpp b/src/Magnum/Text/Renderer.cpp index c27ec0471..b06c70f32 100644 --- a/src/Magnum/Text/Renderer.cpp +++ b/src/Magnum/Text/Renderer.cpp @@ -585,7 +585,7 @@ std::tuple, std::vector, std::vector, return std::make_tuple(Utility::move(positions), Utility::move(textureCoordinates), Utility::move(indices), rectangle); } -template std::tuple Renderer::render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment) { +template std::tuple BasicRenderer::render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment) { /* Finalize mesh configuration and return the result */ auto r = renderInternal(font, cache, size, text, vertexBuffer, indexBuffer, usage, alignment); GL::Mesh& mesh = std::get<0>(r); @@ -652,7 +652,7 @@ AbstractRenderer::AbstractRenderer(AbstractFont& font, const AbstractGlyphCache& AbstractRenderer::~AbstractRenderer() = default; -template Renderer::Renderer(AbstractFont& font, const AbstractGlyphCache& cache, const Float size, const Alignment alignment): AbstractRenderer(font, cache, size, alignment) { +template BasicRenderer::BasicRenderer(AbstractFont& font, const AbstractGlyphCache& cache, const Float size, const Alignment alignment): AbstractRenderer(font, cache, size, alignment) { /* Finalize mesh configuration */ _mesh.addVertexBuffer(_vertexBuffer, 0, typename Shaders::GenericGL::Position( @@ -717,8 +717,8 @@ void AbstractRenderer::render(const std::string& text) { _mesh.setCount(indexCount); } -template class MAGNUM_TEXT_EXPORT Renderer<2>; -template class MAGNUM_TEXT_EXPORT Renderer<3>; +template class MAGNUM_TEXT_EXPORT BasicRenderer<2>; +template class MAGNUM_TEXT_EXPORT BasicRenderer<3>; #endif }} diff --git a/src/Magnum/Text/Renderer.h b/src/Magnum/Text/Renderer.h index bedb3d869..ee967f7b2 100644 --- a/src/Magnum/Text/Renderer.h +++ b/src/Magnum/Text/Renderer.h @@ -27,7 +27,7 @@ */ /** @file Text/Renderer.h - * @brief Class @ref Magnum::Text::AbstractRenderer, @ref Magnum::Text::Renderer, typedef @ref Magnum::Text::Renderer2D, @ref Magnum::Text::Renderer3D, function @ref Magnum::Text::renderLineGlyphPositionsInto(), @ref Magnum::Text::renderGlyphQuadsInto(), @ref Magnum::Text::alignRenderedLine(), @ref Magnum::Text::alignRenderedBlock(), @ref Magnum::Text::renderGlyphQuadIndicesInto() + * @brief Class @ref Magnum::Text::AbstractRenderer, typedef @ref Magnum::Text::Renderer2D, @ref Magnum::Text::Renderer3D, function @ref Magnum::Text::renderLineGlyphPositionsInto(), @ref Magnum::Text::renderGlyphQuadsInto(), @ref Magnum::Text::alignRenderedLine(), @ref Magnum::Text::alignRenderedBlock(), @ref Magnum::Text::renderGlyphQuadIndicesInto() */ #include "Magnum/Magnum.h" @@ -339,9 +339,9 @@ MAGNUM_TEXT_EXPORT Containers::Pair glyphRangeForBytes #ifdef MAGNUM_TARGET_GL /** -@brief Base for text renderers +@brief Base for OpenGL text renderers -Not meant to be used directly, see the @ref Renderer class for more +Not meant to be used directly, see the @ref BasicRenderer class for more information. @note This class is available only if Magnum is compiled with @@ -470,19 +470,19 @@ class MAGNUM_TEXT_EXPORT AbstractRenderer { }; /** -@brief Text renderer +@brief OpenGL text renderer Lays out the text into mesh using given font. Use of ligatures, kerning etc. depends on features supported by particular font and its layouter. -@section Text-Renderer-usage Usage +@section Text-BasicRenderer-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: -@snippet Text-gl.cpp Renderer-usage1 +@snippet Text-gl.cpp BasicRenderer-usage1 See @ref render(AbstractFont&, const AbstractGlyphCache&, Float, const std::string&, Alignment) and @ref render(AbstractFont&, const AbstractGlyphCache&, Float, const std::string&, GL::Buffer&, GL::Buffer&, GL::BufferUsage, Alignment) @@ -492,17 +492,18 @@ 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: -@snippet Text-gl.cpp Renderer-usage2 +@snippet Text-gl.cpp BasicRenderer-usage2 -@subsection Text-Renderer-usage-font-size Font size +@subsection Text-BasicRenderer-usage-font-size Font size As mentioned in @ref Text-AbstractFont-usage-font-size "AbstractFont class documentation", the size at which the font is loaded is decoupled from the size at which a concrete text is rendered. In particular, with a concrete projection matrix, -the size you pass to either @ref render() or to the @ref Renderer() constructor -will always result in the same size of the rendered text, independently of the -size the font was loaded in. Size of the loaded font is the size at which the -glyphs get prerendered into the glyph cache, affecting visual quality. +the size you pass to either @ref render() or to the @ref BasicRenderer() +constructor will always result in the same size of the rendered text, +independently of the size the font was loaded in. Size of the loaded font is +the size at which the glyphs get prerendered into the glyph cache, affecting +visual quality. When rendering the text, there are two common approaches --- either setting up the size to match a global user interface scale, or having the text size @@ -514,7 +515,7 @@ If using the regular @ref GlyphCache, for best visual quality it should be created with the @ref AbstractFont loaded at the same size as the text to be rendered, although often a double supersampling achieves a crisper result. I.e., loading the font with 24 pt, but rendering with 12 pt. See below for -@ref Text-Renderer-usage-font-size-dpi "additional considerations for proper DPI awareness". +@ref Text-BasicRenderer-usage-font-size-dpi "additional considerations for proper DPI awareness". The second approach, with text size being relative to the window size, is for cases where the text is meant to match surrounding art, such as in a game menu. @@ -525,7 +526,7 @@ provide text at different sizes with minimal quality loss. See its documentation for details about picking the right font size and other parameters for best results. -@subsection Text-Renderer-usage-font-size-dpi DPI awareness +@subsection Text-BasicRenderer-usage-font-size-dpi DPI awareness To achieve crisp rendering and/or text size matching other applications on HiDPI displays, additional steps need to be taken. There are two separate @@ -536,8 +537,8 @@ concepts for DPI-aware rendering: units", so a 12 pt font is still a 12 pt font independently of how the interface is scaled compared to actual display properties (for example by setting a global 150% scale in the desktop environment, or by zooming a - browser window). The size used by the @ref Renderer should match these - virtual units. + browser window). The size used by the @ref BasicRenderer "Renderer*D" + should match these virtual units. - Framebuffer size --- how many pixels is actually there. If a 192 DPI display has a 200% interface scale, a 12 pt font would be 32 pixels. But if it only has a 150% scale, all interface elements will be smaller, and a 12 @@ -554,14 +555,15 @@ documented thoroughly in @ref Platform-Sdl2Application-dpi, for this particular case a scaled interface size, used instead of window size for the projection, would be calculated like this: -@snippet Text-gl.cpp Renderer-dpi-interface-size +@snippet Text-gl.cpp BasicRenderer-dpi-interface-size And a multiplier for the @ref AbstractFont and @ref GlyphCache font size like -this. The @ref Renderer keeps using the size without this multiplier. +this. The @ref BasicRenderer "Renderer*D" keeps using the size without this +multiplier. -@snippet Text-gl.cpp Renderer-dpi-size-multiplier +@snippet Text-gl.cpp BasicRenderer-dpi-size-multiplier -@section Text-Renderer-required-opengl-functionality Required OpenGL functionality +@section Text-BasicRenderer-required-opengl-functionality Required OpenGL functionality Mutable text rendering requires @gl_extension{ARB,map_buffer_range} on desktop OpenGL (also part of OpenGL ES 3.0). If @gl_extension{EXT,map_buffer_range} is not @@ -576,7 +578,7 @@ asynchronous buffer updates. There is no similar extension in WebGL, thus plain @see @ref Renderer2D, @ref Renderer3D, @ref AbstractFont, @ref Shaders::VectorGL, @ref Shaders::DistanceFieldVectorGL */ -template class MAGNUM_TEXT_EXPORT Renderer: public AbstractRenderer { +template class MAGNUM_TEXT_EXPORT BasicRenderer: public AbstractRenderer { public: /** * @brief Render text @@ -603,8 +605,8 @@ template class MAGNUM_TEXT_EXPORT Renderer: public Abstr * @param size Font size * @param alignment Text alignment */ - explicit Renderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft); - Renderer(AbstractFont&, AbstractGlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */ + explicit BasicRenderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft); + BasicRenderer(AbstractFont&, AbstractGlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */ #ifndef DOXYGEN_GENERATING_OUTPUT using AbstractRenderer::render; @@ -618,7 +620,7 @@ template class MAGNUM_TEXT_EXPORT Renderer: public Abstr @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features for more information. */ -typedef Renderer<2> Renderer2D; +typedef BasicRenderer<2> Renderer2D; /** @brief Three-dimensional text renderer @@ -627,7 +629,7 @@ typedef Renderer<2> Renderer2D; @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features for more information. */ -typedef Renderer<3> Renderer3D; +typedef BasicRenderer<3> Renderer3D; #endif }} diff --git a/src/Magnum/Text/Text.h b/src/Magnum/Text/Text.h index b567e7b6e..b30c1bf36 100644 --- a/src/Magnum/Text/Text.h +++ b/src/Magnum/Text/Text.h @@ -64,9 +64,9 @@ typedef CORRADE_DEPRECATED("use DistanceFieldGlyphCacheGL instead") DistanceFiel typedef CORRADE_DEPRECATED("use GlyphCacheGL instead") GlyphCacheGL GlyphCache; #endif class AbstractRenderer; -template class Renderer; -typedef Renderer<2> Renderer2D; -typedef Renderer<3> Renderer3D; +template class BasicRenderer; +typedef BasicRenderer<2> Renderer2D; +typedef BasicRenderer<3> Renderer3D; #endif }}