Text: (temporarily) rename the Renderer template to BasicRenderer.

I'm going to make a new Renderer class that's unlike the old one, and
isn't templated anymore either, so gotta make room for it first. I assume
that all existing code used the Renderer2D / Renderer3D typedefs so this
should be pretty much painless.

Ultimately this class will be gone, with only (then deprecated)
AbstractRenderer left, and Renderer2D / Renderer3D being aliases to it
-- internally it doesn't actually do anything dfferent, even the
positions are two-component in both cases.

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
 

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

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<Text::AbstractFont> manager;
-/* [Renderer-usage1] */
+/* [BasicRenderer-usage1] */
 /* Font instance, received from a plugin manager */
 Containers::Pointer<Text::AbstractFont> 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<void>(interfaceSize);
 static_cast<void>(sizeMultiplier);
 }

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} <a href="#derived-classes">derived classes</a> 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<AbstractLayouter> layout(const AbstractGlyphCache& cache, Float size, Containers::StringView text);

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 {

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
 

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
 

src/Magnum/Text/Renderer.cpp

@@ -585,7 +585,7 @@ std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>,
     return std::make_tuple(Utility::move(positions), Utility::move(textureCoordinates), Utility::move(indices), rectangle);
 }
 
-template<UnsignedInt dimensions> std::tuple<GL::Mesh, Range2D> Renderer<dimensions>::render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment) {
+template<UnsignedInt dimensions> std::tuple<GL::Mesh, Range2D> BasicRenderer<dimensions>::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<UnsignedInt dimensions> Renderer<dimensions>::Renderer(AbstractFont& font, const AbstractGlyphCache& cache, const Float size, const Alignment alignment): AbstractRenderer(font, cache, size, alignment) {
+template<UnsignedInt dimensions> BasicRenderer<dimensions>::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<dimensions>::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
 
 }}

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<UnsignedInt, UnsignedInt> 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<UnsignedInt dimensions> class MAGNUM_TEXT_EXPORT Renderer: public AbstractRenderer {
+template<UnsignedInt dimensions> class MAGNUM_TEXT_EXPORT BasicRenderer: public AbstractRenderer {
     public:
         /**
          * @brief Render text
@@ -603,8 +605,8 @@ template<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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
 
 }}

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<UnsignedInt> class Renderer;
-typedef Renderer<2> Renderer2D;
-typedef Renderer<3> Renderer3D;
+template<UnsignedInt> class BasicRenderer;
+typedef BasicRenderer<2> Renderer2D;
+typedef BasicRenderer<3> Renderer3D;
 #endif
 
 }}