TextureTools: deprecate the atlas() bad joke.

Replacing this thing took almost 11 years.

doc/changelog.dox

@@ -1236,6 +1236,10 @@ See also:
 -   @cpp Shaders::PhongGL::setLightColor(const Magnum::Color4&) @ce is deprecated
     in favor of @ref Shaders::PhongGL::setLightColors() with a single item ---
     it's short enough to not warrant the existence of a dedicated overload
+-   The @cpp TextureTools::atlas() @ce utility is deprecated in favor of
+    @ref TextureTools::AtlasLandfill, which has a vastly better packing
+    efficiency, supports incremental packing and doesn't force the caller to
+    use a @ref std::vector
 -   @cpp Trade::AbstractMaterialData @ce as well as its containing header
     `Magnum/Trade/AbstractMaterialData.h` is now a deprecated alias to the new
     and more flexible @ref Trade::MaterialData.

src/Magnum/TextureTools/Atlas.cpp

@@ -26,7 +26,6 @@
 #include "Atlas.h"
 
 #include <algorithm>
-#include <vector>
 #include <Corrade/Containers/Array.h>
 #include <Corrade/Containers/BitArrayView.h>
 #include <Corrade/Containers/EnumSet.hpp>
@@ -34,9 +33,15 @@
 #include <Corrade/Containers/Pair.h>
 #include <Corrade/Containers/StridedArrayView.h>
 
+#include "Magnum/Math/Vector3.h"
 #include "Magnum/Math/Functions.h"
 #include "Magnum/Math/FunctionsBatch.h"
+
+#ifdef MAGNUM_BUILD_DEPRECATED
+#include <vector>
+
 #include "Magnum/Math/Range.h"
+#endif
 
 namespace Magnum { namespace TextureTools {
 
@@ -387,6 +392,7 @@ bool AtlasLandfillArray::add(const std::initializer_list<Vector2i> sizes, const
     return add(Containers::stridedArrayView(sizes), offsets);
 }
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 std::vector<Range2Di> atlas(const Vector2i& atlasSize, const std::vector<Vector2i>& sizes, const Vector2i& padding) {
     if(sizes.empty()) return {};
 
@@ -407,7 +413,8 @@ std::vector<Range2Di> atlas(const Vector2i& atlasSize, const std::vector<Vector2
         return atlas;
     }
 
-    /** @todo actual magic implementation, not this joke */
+    /* I could also just delegate to the AtlasLandfill class, but that'd be a
+       waste of time as the interface of this API is extremely bad anyway. */
 
     atlas.reserve(sizes.size());
     for(std::size_t i = 0; i != sizes.size(); ++i)
@@ -415,6 +422,7 @@ std::vector<Range2Di> atlas(const Vector2i& atlasSize, const std::vector<Vector2
 
     return atlas;
 }
+#endif
 
 Int atlasArrayPowerOfTwo(const Vector2i& layerSize, const Containers::StridedArrayView1D<const Vector2i>& sizes, const Containers::StridedArrayView1D<Vector3i>& offsets) {
     CORRADE_ASSERT(offsets.size() == sizes.size(),

src/Magnum/TextureTools/Atlas.h

@@ -30,7 +30,6 @@
  */
 
 #include <Corrade/Containers/Pointer.h>
-#include <Corrade/Utility/StlForwardVector.h>
 
 #include "Magnum/Magnum.h"
 #include "Magnum/Math/Vector2.h"
@@ -38,6 +37,7 @@
 
 #ifdef MAGNUM_BUILD_DEPRECATED
 #include <Corrade/Utility/Macros.h>
+#include <Corrade/Utility/StlForwardVector.h>
 #endif
 
 namespace Magnum { namespace TextureTools {
@@ -512,20 +512,26 @@ class MAGNUM_TEXTURETOOLS_EXPORT AtlasLandfillArray {
         Containers::Pointer<Implementation::AtlasLandfillState> _state;
 };
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 /**
-@brief Pack textures into texture atlas
-@param atlasSize    Size of resulting atlas
+@brief Pack textures into a texture atlas
+@param atlasSize    Size of the resulting atlas
 @param sizes        Sizes of all textures in the atlas
 @param padding      Padding around each texture
 
 Packs many small textures into one larger. If the textures cannot be packed
-into required size, empty vector is returned.
+into required size, an empty vector is returned.
 
 Padding is added twice to each size and the atlas is laid out so the padding
 don't overlap. Returned sizes are the same as original sizes, i.e. without the
 padding.
+
+@m_deprecated_since_latest Use the @ref AtlasLandfill class, which has a vastly
+    better packing efficiency, supports incremental packing and doesn't force
+    the caller to use a @ref std::vector.
 */
-std::vector<Range2Di> MAGNUM_TEXTURETOOLS_EXPORT atlas(const Vector2i& atlasSize, const std::vector<Vector2i>& sizes, const Vector2i& padding = Vector2i());
+MAGNUM_TEXTURETOOLS_EXPORT CORRADE_DEPRECATED("use the AtlasLandfill class instead") std::vector<Range2Di> atlas(const Vector2i& atlasSize, const std::vector<Vector2i>& sizes, const Vector2i& padding = {});
+#endif
 
 /**
 @brief Pack square power-of-two textures into a texture atlas array

src/Magnum/TextureTools/Test/AtlasTest.cpp

@@ -24,7 +24,6 @@
 */
 
 #include <sstream>
-#include <vector>
 #include <Corrade/Containers/Array.h>
 #include <Corrade/Containers/StridedBitArrayView.h>
 #include <Corrade/Containers/Pair.h>
@@ -36,9 +35,15 @@
 #include <Corrade/Utility/DebugStl.h>
 #include <Corrade/Utility/FormatStl.h>
 
-#include "Magnum/Math/Range.h"
+#include "Magnum/Math/Vector3.h"
 #include "Magnum/TextureTools/Atlas.h"
 
+#ifdef MAGNUM_BUILD_DEPRECATED
+#include <vector>
+
+#include "Magnum/Math/Range.h"
+#endif
+
 namespace Magnum { namespace TextureTools { namespace Test { namespace {
 
 struct AtlasTest: TestSuite::Tester {
@@ -70,10 +75,12 @@ struct AtlasTest: TestSuite::Tester {
     void landfillAddTooLargeElement();
     void landfillAddTooLargeElementPadded();
 
-    void basic();
-    void padding();
-    void empty();
-    void tooSmall();
+    #ifdef MAGNUM_BUILD_DEPRECATED
+    void deprecatedBasic();
+    void deprecatedPadding();
+    void deprecatedEmpty();
+    void deprecatedTooSmall();
+    #endif
 
     void arrayPowerOfTwoEmpty();
     void arrayPowerOfTwoSingleElement();
@@ -456,10 +463,12 @@ AtlasTest::AtlasTest() {
               &AtlasTest::landfillAddTooLargeElement,
               &AtlasTest::landfillAddTooLargeElementPadded,
 
-              &AtlasTest::basic,
-              &AtlasTest::padding,
-              &AtlasTest::empty,
-              &AtlasTest::tooSmall,
+              #ifdef MAGNUM_BUILD_DEPRECATED
+              &AtlasTest::deprecatedBasic,
+              &AtlasTest::deprecatedPadding,
+              &AtlasTest::deprecatedEmpty,
+              &AtlasTest::deprecatedTooSmall,
+              #endif
 
               &AtlasTest::arrayPowerOfTwoEmpty,
               &AtlasTest::arrayPowerOfTwoSingleElement,
@@ -1126,12 +1135,15 @@ void AtlasTest::landfillAddTooLargeElementPadded() {
         TestSuite::Compare::String);
 }
 
-void AtlasTest::basic() {
+#ifdef MAGNUM_BUILD_DEPRECATED
+void AtlasTest::deprecatedBasic() {
+    CORRADE_IGNORE_DEPRECATED_PUSH
     std::vector<Range2Di> atlas = TextureTools::atlas({64, 64}, {
         {12, 18},
         {32, 15},
         {23, 25}
     });
+    CORRADE_IGNORE_DEPRECATED_POP
 
     CORRADE_COMPARE(atlas.size(), 3);
     CORRADE_COMPARE(atlas, (std::vector<Range2Di>{
@@ -1140,12 +1152,14 @@ void AtlasTest::basic() {
         Range2Di::fromSize({0, 25}, {23, 25})}));
 }
 
-void AtlasTest::padding() {
+void AtlasTest::deprecatedPadding() {
+    CORRADE_IGNORE_DEPRECATED_PUSH
     std::vector<Range2Di> atlas = TextureTools::atlas({64, 64}, {
         {8, 16},
         {28, 13},
         {19, 23}
     }, {2, 1});
+    CORRADE_IGNORE_DEPRECATED_POP
 
     CORRADE_COMPARE(atlas.size(), 3);
     CORRADE_COMPARE(atlas, (std::vector<Range2Di>{
@@ -1154,23 +1168,28 @@ void AtlasTest::padding() {
         Range2Di::fromSize({2, 26}, {19, 23})}));
 }
 
-void AtlasTest::empty() {
+void AtlasTest::deprecatedEmpty() {
+    CORRADE_IGNORE_DEPRECATED_PUSH
     std::vector<Range2Di> atlas = TextureTools::atlas({}, {});
+    CORRADE_IGNORE_DEPRECATED_POP
     CORRADE_VERIFY(atlas.empty());
 }
 
-void AtlasTest::tooSmall() {
+void AtlasTest::deprecatedTooSmall() {
     std::ostringstream o;
     Error redirectError{&o};
 
+    CORRADE_IGNORE_DEPRECATED_PUSH
     std::vector<Range2Di> atlas = TextureTools::atlas({64, 32}, {
         {8, 16},
         {21, 13},
         {19, 29}
     }, {2, 1});
+    CORRADE_IGNORE_DEPRECATED_POP
     CORRADE_VERIFY(atlas.empty());
     CORRADE_COMPARE(o.str(), "TextureTools::atlas(): requested atlas size Vector(64, 32) is too small to fit 3 Vector(25, 31) textures. Generated atlas will be empty.\n");
 }
+#endif
 
 void AtlasTest::arrayPowerOfTwoEmpty() {
     Containers::ArrayView<Vector3i> offsets;