Deprecate MagnumFont and MagnumFontConverter.

With StbTrueTypeFont no longer being embarrassingly slow due to a stupid
error, the MagnumFont plugin doesn't really provide any advantage
anymore. Originally I thought I'd update it to not be forcibly relying
on a TGA format and maybe add kerning support, but the image + text
format is extremely inefficient compared to basically anything else and
so I don't see a point in supporting it further. Marking it as
deprecated should also hint to people that using this thing is not a
good idea.

The MagnumFontConverter plugin was also the only user of the
AbstractFontConverter APIs, which right now are the last that didn't go
through a STL cleanup process. I plan to make a converter plugin for
font "minification" using HarfBuzz subsetting functionality, and not
having to support anything else that relies on the outdated APIs will
make the font converter API updates a bit easier.

Finally, the MagnumFont plugin was also the last one that directly
instantiated the TgaImporter plugin, instead of going through
AnyImageConverter. Marking it deprecated allows me to deprecate direct
instatiation in the remaining plugins as well.

doc/changelog-old.dox

@@ -1626,10 +1626,10 @@ No dependency changes in this release.
 
 -   MSVC 2013 support in `compatibility` branch
 -   Dependency-less plugins from Magnum Plugins repository are now part of
-    Magnum to make their usage easier, in particular the @ref Text::MagnumFont "MagnumFont",
+    Magnum to make their usage easier, in particular the @cpp MagnumFont @ce,
-    @ref Text::MagnumFontConverter "MagnumFontConverter",
+    @cpp MagnumFontConverter @ce, @ref Trade::TgaImporter "TgaImporter",
-    @ref Trade::TgaImporter "TgaImporter", @ref Trade::TgaImageConverter "TgaImageConverter"
+    @ref Trade::TgaImageConverter "TgaImageConverter" and
-    and @ref Audio::WavImporter "WavAudioImporter" plugins.
+    @ref Audio::WavImporter "WavAudioImporter" plugins.
 -   Documented @ref opengl-support "state of OpenGL support",
     @ref opengl-mapping "mapping between OpenGL and Magnum API",
     @ref plugins "general plugin usage" and added

doc/changelog.dox

@@ -1837,6 +1837,11 @@ See also:
     @type_vk{PrimitiveToplogy} are deprecated in favor of
     @ref Vk::hasMeshPrimitive() and @ref Vk::meshPrimitive() that return the
     new @ref Vk::MeshPrimitive enum
+-   The ancient @cpp MagnumFont @ce and @cpp MagnumFontConverter @ce plugins
+    are deprecated as they no longer provide any advantage over other font
+    plugins, be it speed, efficiency, file size or portability. Use the
+    @relativeref{Text,StbTrueTypeFont} plugin instead, which doesn't require
+    any font preprocessing upfront.
 
 @subsection changelog-latest-compatibility Potential compatibility breakages, removed APIs
 

doc/custom-buildsystems-order-plugins.dot

@@ -39,8 +39,8 @@ digraph "Magnum plugin dependency order" {
     AudioImporter [label="*AudioImporter" class="m-success"]
     ImageConverter [label="*ImageConverter" class="m-success"]
     Importer [label="*Importer" class="m-success"]
-    MagnumFont [class="m-success"]
+    MagnumFont [class="m-dim"]
-    MagnumFontConverter [class="m-success"]
+    MagnumFontConverter [class="m-dim"]
     ObjImporter [class="m-success"]
     TgaImageConverter [class="m-success"]
     TgaImporter [class="m-success"]
@@ -48,10 +48,10 @@ digraph "Magnum plugin dependency order" {
     AudioImporter -> MagnumAudio
     ImageConverter -> MagnumTrade
     Importer -> MagnumTrade
-    MagnumFont -> MagnumText
+    MagnumFont -> MagnumText [class="m-dim"]
-    MagnumFont -> TgaImporter
+    MagnumFont -> TgaImporter [class="m-dim"]
-    MagnumFontConverter -> MagnumText
+    MagnumFontConverter -> MagnumText [class="m-dim"]
-    MagnumFontConverter -> TgaImageConverter
+    MagnumFontConverter -> TgaImageConverter [class="m-dim"]
     ObjImporter -> MagnumTrade
     ObjImporter -> MagnumMeshTools
     TgaImageConverter -> MagnumTrade

package/ci/unix-desktop.sh

@@ -44,8 +44,8 @@ cmake .. \
     -DMAGNUM_WITH_ANYSCENECONVERTER=ON \
     -DMAGNUM_WITH_ANYSCENEIMPORTER=ON \
     -DMAGNUM_WITH_ANYSHADERCONVERTER=ON \
-    -DMAGNUM_WITH_MAGNUMFONT=ON \
+    -DMAGNUM_WITH_MAGNUMFONT=$BUILD_DEPRECATED \
-    -DMAGNUM_WITH_MAGNUMFONTCONVERTER=ON \
+    -DMAGNUM_WITH_MAGNUMFONTCONVERTER=$BUILD_DEPRECATED \
     -DMAGNUM_WITH_OBJIMPORTER=ON \
     -DMAGNUM_WITH_TGAIMAGECONVERTER=ON \
     -DMAGNUM_WITH_TGAIMPORTER=ON \

src/MagnumPlugins/MagnumFont/CMakeLists.txt

@@ -24,9 +24,11 @@
 #   DEALINGS IN THE SOFTWARE.
 #
 
+if(NOT MAGNUM_BUILD_DEPRECATED)
+    message(SEND_ERROR "The MagnumFont plugin is deprecated. Either remove MAGNUM_WITH_MAGNUMFONT from your options or rebuild Magnum with MAGNUM_BUILD_DEPRECATED enabled to keep using the plugin.")
+endif()
+
 if(NOT MAGNUM_TARGET_GL)
-    # TODO: remove (and update all other docs) when we have better
-    # createGlyphCache() APIs
     message(SEND_ERROR "MagnumFont is available only if MAGNUM_TARGET_GL is enabled")
 endif()
 

src/MagnumPlugins/MagnumFont/MagnumFont.cpp

@@ -24,6 +24,8 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#define _MAGNUM_NO_DEPRECATED_MAGNUMFONT /* So it doesn't yell here */
+
 #include "MagnumFont.h"
 
 #include <sstream>
@@ -173,8 +175,6 @@ Containers::Pointer<AbstractGlyphCache> MagnumFont::doCreateGlyphCache() {
        control over both the source and processed format (where
        DistanceFieldGlyphCache may set the processed format to RGBA if there's
        no renderable single-channel format). */
-    /** @todo figure out a nicer way, and ideally how to do this with
-        fillGlyphCache() instead */
     struct Cache: GlyphCacheGL {
         explicit Cache(PixelFormat format, const Vector2i& size, PixelFormat processedFormat, const Vector2i& processedSize, const Vector2i& padding): GlyphCacheGL{format, size, processedFormat, processedSize, padding} {}
 
@@ -253,5 +253,7 @@ Containers::Pointer<AbstractShaper> MagnumFont::doCreateShaper() {
 
 }}
 
+CORRADE_IGNORE_DEPRECATED_PUSH
 CORRADE_PLUGIN_REGISTER(MagnumFont, Magnum::Text::MagnumFont,
     MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE)
+CORRADE_IGNORE_DEPRECATED_POP

src/MagnumPlugins/MagnumFont/MagnumFont.h

@@ -26,13 +26,19 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 /** @file
  * @brief Class @ref Magnum::Text::MagnumFont
+ * @m_deprecated_since_latest Use @ref MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h
+ *      and the @relativeref{Magnum::Text,StbTrueTypeFont} plugin instead,
+ *      which is more efficient and has a larger feature set without needing a
+ *      custom font preprocessing step.
  */
+#endif
 
 #include "Magnum/configure.h"
 
-#ifdef MAGNUM_TARGET_GL
+#if defined(MAGNUM_BUILD_DEPRECATED) && defined(MAGNUM_TARGET_GL)
 #include <Corrade/Containers/Pointer.h>
 
 #include "Magnum/Text/AbstractFont.h"
@@ -54,10 +60,17 @@
 #define MAGNUM_MAGNUMFONT_LOCAL
 #endif
 
+#ifndef _MAGNUM_NO_DEPRECATED_MAGNUMFONT
+CORRADE_DEPRECATED_FILE("use MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h and the StbTrueTypeFont plugin instead")
+#endif
+
 namespace Magnum { namespace Text {
 
 /**
 @brief Simple bitmap font plugin
+@m_deprecated_since_latest Use the @ref StbTrueTypeFont plugin instead, which
+    is more efficient and has a larger feature set without needing a custom
+    font preprocessing step.
 
 The font consists of two files, one text file containing character and glyph
 info and one TGA file containing the glyphs in distance field format. The font
@@ -161,7 +174,7 @@ need to instantiate a manager for them and register it with
 See @ref building, @ref cmake, @ref plugins and @ref file-formats for more
 information.
 */
-class MAGNUM_MAGNUMFONT_EXPORT MagnumFont: public AbstractFont {
+class CORRADE_DEPRECATED("use StbTrueTypeFont instead") MAGNUM_MAGNUMFONT_EXPORT MagnumFont: public AbstractFont {
     public:
         /** @brief Default constructor */
         explicit MagnumFont();
@@ -190,7 +203,9 @@ class MAGNUM_MAGNUMFONT_EXPORT MagnumFont: public AbstractFont {
 };
 
 }}
-#else
+#elif !defined(MAGNUM_BUILD_DEPRECATED)
+#error use MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h and the StbTrueTypeFont plugin instead
+#elif !defined(MAGNUM_TARGET_GL)
 #error this header is available only in the OpenGL build
 #endif
 

src/MagnumPlugins/MagnumFont/Test/MagnumFontTest.cpp

@@ -33,7 +33,7 @@
 #include <Corrade/TestSuite/Compare/Container.h>
 #include <Corrade/TestSuite/Compare/String.h>
 #include <Corrade/Utility/Path.h>
-#include <Corrade/Utility/DebugStl.h> /** @todo remove file callbacks are std::string-free */
+#include <Corrade/Utility/DebugStl.h>
 
 #include "Magnum/FileCallback.h"
 #include "Magnum/PixelFormat.h"

src/MagnumPlugins/MagnumFontConverter/CMakeLists.txt

@@ -24,6 +24,10 @@
 #   DEALINGS IN THE SOFTWARE.
 #
 
+if(NOT MAGNUM_BUILD_DEPRECATED)
+    message(SEND_ERROR "The MagnumFontConverter plugin is deprecated. Either remove MAGNUM_WITH_MAGNUMFONTCONVERTER from your options or rebuild Magnum with MAGNUM_BUILD_DEPRECATED enabled to keep using the plugin.")
+endif()
+
 find_package(Corrade REQUIRED PluginManager)
 
 if(MAGNUM_BUILD_PLUGINS_STATIC AND NOT DEFINED MAGNUM_MAGNUMFONTCONVERTER_BUILD_STATIC)

src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.cpp

@@ -24,6 +24,8 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#define _MAGNUM_NO_DEPRECATED_MAGNUMFONTCONVERTER /* So it doesn't yell here */
+
 #include "MagnumFontConverter.h"
 
 #include <algorithm> /* std::sort() */
@@ -108,8 +110,6 @@ std::vector<std::pair<std::string, Containers::Array<char>>> MagnumFontConverter
     for(const std::pair<UnsignedInt, std::pair<Vector2i, Range2Di>>& glyph: sortedGlyphs)
         glyphIdMap.emplace(glyph.first, glyphIdMap.size());
 
-    /** @todo Save only glyphs contained in @p characters */
-
     /* Inverse map from new glyph IDs to old ones */
     std::vector<UnsignedInt> inverseGlyphIdMap(glyphIdMap.size());
     for(const std::pair<const UnsignedInt, UnsignedInt>& map: glyphIdMap)
@@ -128,11 +128,7 @@ std::vector<std::pair<std::string, Containers::Array<char>>> MagnumFontConverter
 
     /* Save glyph properties in order which preserves their IDs, remove padding
        from the values so they aren't added twice when using the font later */
-    /** @todo Some better way to handle this padding stuff */
     for(UnsignedInt oldGlyphId: inverseGlyphIdMap) {
-        /** @todo this branch is messy, clean up; also there's now a
-            distinction between a cache-global invalid glyph and font-local,
-            what to do there? */
         Containers::Triple<Vector2i, Int, Range2Di> glyph =
             oldGlyphId ? cache.glyph(*fontId, oldGlyphId) : cache.glyph(0);
         Utility::ConfigurationGroup* group = configuration.addGroup("glyph");
@@ -170,5 +166,7 @@ std::vector<std::pair<std::string, Containers::Array<char>>> MagnumFontConverter
 
 }}
 
+CORRADE_IGNORE_DEPRECATED_PUSH
 CORRADE_PLUGIN_REGISTER(MagnumFontConverter, Magnum::Text::MagnumFontConverter,
     MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE)
+CORRADE_IGNORE_DEPRECATED_POP

src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h

@@ -26,10 +26,19 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 /** @file
  * @brief Class @ref Magnum::Text::MagnumFontConverter
+ * @m_deprecated_since_latest Use @ref MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h
+ *      and the @relativeref{Magnum::Text,StbTrueTypeFont} plugin instead,
+ *      which is more efficient and has a larger feature set without needing a
+ *      custom font preprocessing step.
  */
+#endif
+
+#include "Magnum/configure.h"
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 #include "Magnum/Text/AbstractFontConverter.h"
 
 #include "MagnumPlugins/MagnumFontConverter/configure.h"
@@ -50,10 +59,17 @@
 #define MAGNUM_MAGNUMFONTCONVERTER_LOCAL
 #endif
 
+#ifndef _MAGNUM_NO_DEPRECATED_MAGNUMFONTCONVERTER
+CORRADE_DEPRECATED_FILE("use MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h and the StbTrueTypeFont plugin instead")
+#endif
+
 namespace Magnum { namespace Text {
 
 /**
 @brief MagnumFont converter plugin
+@m_deprecated_since_latest Use the @ref StbTrueTypeFont plugin instead, which
+    is more efficient and has a larger feature set without needing a custom
+    font preprocessing step.
 
 Expects filename prefix, creates two files, `prefix.conf` and `prefix.tga`. See
 @ref MagnumFont for more information about the font. The plugin requires the
@@ -109,7 +125,7 @@ you need to instantiate a manager for them and register it with
 
 See @ref building, @ref cmake and @ref plugins for more information.
 */
-class MAGNUM_MAGNUMFONTCONVERTER_EXPORT MagnumFontConverter: public Text::AbstractFontConverter {
+class CORRADE_DEPRECATED("use StbTrueTypeFont instead") MAGNUM_MAGNUMFONTCONVERTER_EXPORT MagnumFontConverter: public Text::AbstractFontConverter {
     public:
         /** @brief Default constructor */
         explicit MagnumFontConverter();
@@ -123,5 +139,8 @@ class MAGNUM_MAGNUMFONTCONVERTER_EXPORT MagnumFontConverter: public Text::Abstra
 };
 
 }}
+#else
+#error use MagnumPlugins/StbTrueTypeFont/StbTrueTypeFont.h and the StbTrueTypeFont plugin instead
+#endif
 
 #endif

src/MagnumPlugins/MagnumFontConverter/Test/MagnumFontConverterTest.cpp

@@ -24,11 +24,11 @@
     DEALINGS IN THE SOFTWARE.
 */
 
-#include <string> /** @todo remove once AbstractFontConverter is STL-free */
+#include <string>
 #include <Corrade/Containers/Optional.h>
 #include <Corrade/Containers/StridedArrayView.h>
 #include <Corrade/Containers/String.h>
-#include <Corrade/Containers/StringStl.h> /** @todo remove once AbstractFontConverter is STL-free */
+#include <Corrade/Containers/StringStl.h>
 #include <Corrade/TestSuite/Tester.h>
 #include <Corrade/TestSuite/Compare/File.h>
 #include <Corrade/Utility/Algorithms.h>