From 330dbc747e890bbcfe7bdd3cc22e20ed739607f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 27 Sep 2023 15:58:44 +0200 Subject: [PATCH] TextureTools: deprecate the atlas() bad joke. Replacing this thing took almost 11 years. --- doc/changelog.dox | 4 ++ src/Magnum/TextureTools/Atlas.cpp | 12 +++++- src/Magnum/TextureTools/Atlas.h | 16 +++++--- src/Magnum/TextureTools/Test/AtlasTest.cpp | 47 +++++++++++++++------- 4 files changed, 58 insertions(+), 21 deletions(-) diff --git a/doc/changelog.dox b/doc/changelog.dox index 4e6d58035..4a1c99cf9 100644 --- a/doc/changelog.dox +++ b/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. diff --git a/src/Magnum/TextureTools/Atlas.cpp b/src/Magnum/TextureTools/Atlas.cpp index 8086c77e8..14662ba4d 100644 --- a/src/Magnum/TextureTools/Atlas.cpp +++ b/src/Magnum/TextureTools/Atlas.cpp @@ -26,7 +26,6 @@ #include "Atlas.h" #include -#include #include #include #include @@ -34,9 +33,15 @@ #include #include +#include "Magnum/Math/Vector3.h" #include "Magnum/Math/Functions.h" #include "Magnum/Math/FunctionsBatch.h" + +#ifdef MAGNUM_BUILD_DEPRECATED +#include + #include "Magnum/Math/Range.h" +#endif namespace Magnum { namespace TextureTools { @@ -387,6 +392,7 @@ bool AtlasLandfillArray::add(const std::initializer_list sizes, const return add(Containers::stridedArrayView(sizes), offsets); } +#ifdef MAGNUM_BUILD_DEPRECATED std::vector atlas(const Vector2i& atlasSize, const std::vector& sizes, const Vector2i& padding) { if(sizes.empty()) return {}; @@ -407,7 +413,8 @@ std::vector atlas(const Vector2i& atlasSize, const std::vector atlas(const Vector2i& atlasSize, const std::vector& sizes, const Containers::StridedArrayView1D& offsets) { CORRADE_ASSERT(offsets.size() == sizes.size(), diff --git a/src/Magnum/TextureTools/Atlas.h b/src/Magnum/TextureTools/Atlas.h index de8688f1f..0f240c1f9 100644 --- a/src/Magnum/TextureTools/Atlas.h +++ b/src/Magnum/TextureTools/Atlas.h @@ -30,7 +30,6 @@ */ #include -#include #include "Magnum/Magnum.h" #include "Magnum/Math/Vector2.h" @@ -38,6 +37,7 @@ #ifdef MAGNUM_BUILD_DEPRECATED #include +#include #endif namespace Magnum { namespace TextureTools { @@ -512,20 +512,26 @@ class MAGNUM_TEXTURETOOLS_EXPORT AtlasLandfillArray { Containers::Pointer _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 MAGNUM_TEXTURETOOLS_EXPORT atlas(const Vector2i& atlasSize, const std::vector& sizes, const Vector2i& padding = Vector2i()); +MAGNUM_TEXTURETOOLS_EXPORT CORRADE_DEPRECATED("use the AtlasLandfill class instead") std::vector atlas(const Vector2i& atlasSize, const std::vector& sizes, const Vector2i& padding = {}); +#endif /** @brief Pack square power-of-two textures into a texture atlas array diff --git a/src/Magnum/TextureTools/Test/AtlasTest.cpp b/src/Magnum/TextureTools/Test/AtlasTest.cpp index c126b2d49..17e4b65bf 100644 --- a/src/Magnum/TextureTools/Test/AtlasTest.cpp +++ b/src/Magnum/TextureTools/Test/AtlasTest.cpp @@ -24,7 +24,6 @@ */ #include -#include #include #include #include @@ -36,9 +35,15 @@ #include #include -#include "Magnum/Math/Range.h" +#include "Magnum/Math/Vector3.h" #include "Magnum/TextureTools/Atlas.h" +#ifdef MAGNUM_BUILD_DEPRECATED +#include + +#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 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{ @@ -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 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{ @@ -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 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 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 offsets;