Trade: rename/deprecate TextureData::Type to TextureType.

Because::This::Is::Colon::Cancer. Also rename Cube to CubeMap and get
rid of the comment that said cube map images are six consecutive 2D
images. Now it's one 3D image instead because that makes more sense, in
the very rare case we'd need to have six different images again we could
probably add a CubeFace value or some such.

doc/changelog.dox

@@ -591,6 +591,10 @@ See also:
     changed to have input first and output second, for consistency with other
     interfaces, together with a switch to @ref Containers::StringView. The
     original signature is marked as deprecated.
+-   @cpp Trade::TextureData::Type @ce was deprecated in favor of
+    @ref Trade::TextureType that is much less annoying to type, in addition
+    @cpp Trade::TextureData::Type::Cube @ce was deprecated in favor of
+    @ref Trade::TextureType::CubeMap for consistency.
 -   @cpp Vk::hasVkFormat(Magnum::VertexFormat) @ce,
     @cpp Vk::hasVkFormat(Magnum::PixelFormat) @ce,
     @cpp Vk::hasVkFormat(Magnum::CompressedPixelFormat) @ce,
@@ -723,6 +727,11 @@ See also:
     error handling.
 -   @ref Trade::TextureData constructor was not @cpp explicit @ce by mistake,
     now it is
+-   @ref Trade::TextureData::image() used to document that cube map images are
+    six consecutive 2D images with the ID being the index of the first one.
+    That's no longer the case and cube map images are 3D. Because no importer
+    implemented support for cube map images, this shouldn't cause a problem in
+    practice.
 
 @subsection changelog-latest-documentation Documentation
 

src/Magnum/Trade/Test/TextureDataTest.cpp

@@ -52,7 +52,7 @@ TextureDataTest::TextureDataTest() {
 
 void TextureDataTest::construct() {
     const int a{};
-    const TextureData data{TextureData::Type::Cube,
+    const TextureData data{TextureType::CubeMap,
         SamplerFilter::Linear,
         SamplerFilter::Nearest,
         SamplerMipmap::Nearest,
@@ -60,7 +60,7 @@ void TextureDataTest::construct() {
         42,
         &a};
 
-    CORRADE_COMPARE(data.type(), TextureData::Type::Cube);
+    CORRADE_COMPARE(data.type(), TextureType::CubeMap);
     CORRADE_COMPARE(data.minificationFilter(), SamplerFilter::Linear);
     CORRADE_COMPARE(data.magnificationFilter(), SamplerFilter::Nearest);
     CORRADE_COMPARE(data.mipmapFilter(), SamplerMipmap::Nearest);
@@ -76,7 +76,7 @@ void TextureDataTest::constructCopy() {
 
 void TextureDataTest::constructMove() {
     const int a{};
-    TextureData data{TextureData::Type::Cube,
+    TextureData data{TextureType::CubeMap,
         SamplerFilter::Linear,
         SamplerFilter::Nearest,
         SamplerMipmap::Nearest,
@@ -86,7 +86,7 @@ void TextureDataTest::constructMove() {
 
     TextureData b{std::move(data)};
 
-    CORRADE_COMPARE(b.type(), TextureData::Type::Cube);
+    CORRADE_COMPARE(b.type(), TextureType::CubeMap);
     CORRADE_COMPARE(b.minificationFilter(), SamplerFilter::Linear);
     CORRADE_COMPARE(b.magnificationFilter(), SamplerFilter::Nearest);
     CORRADE_COMPARE(b.mipmapFilter(), SamplerMipmap::Nearest);
@@ -95,7 +95,7 @@ void TextureDataTest::constructMove() {
     CORRADE_COMPARE(b.importerState(), &a);
 
     const int c{};
-    TextureData d{TextureData::Type::Texture2D,
+    TextureData d{TextureType::Texture2D,
         SamplerFilter::Nearest,
         SamplerFilter::Linear,
         SamplerMipmap::Base,
@@ -104,7 +104,7 @@ void TextureDataTest::constructMove() {
         &c};
     d = std::move(b);
 
-    CORRADE_COMPARE(d.type(), TextureData::Type::Cube);
+    CORRADE_COMPARE(d.type(), TextureType::CubeMap);
     CORRADE_COMPARE(d.minificationFilter(), SamplerFilter::Linear);
     CORRADE_COMPARE(d.magnificationFilter(), SamplerFilter::Nearest);
     CORRADE_COMPARE(d.mipmapFilter(), SamplerMipmap::Nearest);
@@ -119,8 +119,8 @@ void TextureDataTest::constructMove() {
 void TextureDataTest::debugType() {
     std::ostringstream out;
 
-    Debug(&out) << TextureData::Type::Texture3D << TextureData::Type(0xbe);
-    CORRADE_COMPARE(out.str(), "Trade::TextureData::Type::Texture3D Trade::TextureData::Type(0xbe)\n");
+    Debug(&out) << TextureType::Texture3D << TextureType(0xbe);
+    CORRADE_COMPARE(out.str(), "Trade::TextureType::Texture3D Trade::TextureType(0xbe)\n");
 }
 
 }}}}

src/Magnum/Trade/TextureData.cpp

@@ -28,16 +28,16 @@
 namespace Magnum { namespace Trade {
 
 #ifndef DOXYGEN_GENERATING_OUTPUT
-Debug& operator<<(Debug& debug, const TextureData::Type value) {
-    debug << "Trade::TextureData::Type" << Debug::nospace;
+Debug& operator<<(Debug& debug, const TextureType value) {
+    debug << "Trade::TextureType" << Debug::nospace;
 
     switch(value) {
         /* LCOV_EXCL_START */
-        #define _c(value) case TextureData::Type::value: return debug << "::" #value;
+        #define _c(value) case TextureType::value: return debug << "::" #value;
         _c(Texture1D)
         _c(Texture2D)
         _c(Texture3D)
-        _c(Cube)
+        _c(CubeMap)
         #undef _c
         /* LCOV_EXCL_STOP */
     }

src/Magnum/Trade/TextureData.h

@@ -40,6 +40,48 @@
 
 namespace Magnum { namespace Trade {
 
+/**
+@brief Texture type
+@m_since_latest
+
+@see @ref TextureData::type()
+*/
+enum class TextureType: UnsignedByte {
+    /**
+     * One-dimensional texture. The @ref TextureData::image() ID corresponds to
+     * an image from @ref AbstractImporter::image1D().
+     */
+    Texture1D,
+
+    /**
+     * Two-dimensional texture. The @ref TextureData::image() ID corresponds to
+     * an image from @ref AbstractImporter::image2D().
+     */
+    Texture2D,
+
+    /**
+     * Three-dimensional texture. The @ref TextureData::image() ID corresponds
+     * to an image from @ref AbstractImporter::image3D().
+     */
+    Texture3D,
+
+    /**
+     * Cube map texture. The @ref TextureData::image() ID corresponds to an
+     * image from @ref AbstractImporter::image3D(), which is assumed to have
+     * exactly 6 layers in order +X, -X, +Y, -Y, +Z, -Z.
+     * @m_since_latest
+     */
+    CubeMap,
+
+    #ifdef MAGNUM_BUILD_DEPRECATED
+    /**
+     * Cube map texture.
+     * @m_deprecated_since_latest Use @ref TextureType::CubeMap instead.
+     */
+    Cube CORRADE_DEPRECATED_ENUM("use TextureType::CubeMap instead") = CubeMap
+    #endif
+};
+
 /**
 @brief Texture data
 
@@ -47,17 +89,12 @@ namespace Magnum { namespace Trade {
 */
 class TextureData {
     public:
-        /**
-         * @brief Texture type
-         *
-         * @see @ref type()
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief TextureType
+         * @m_deprecated_since_latest Use @ref TextureType instead.
          */
-        enum class Type: UnsignedByte {
-            Texture1D,  /**< One-dimensional texture */
-            Texture2D,  /**< Two-dimensional texture */
-            Texture3D,  /**< Three-dimensional texture */
-            Cube        /**< Cube map texture */
-        };
+        typedef CORRADE_DEPRECATED("use TextureType instead") TextureType Type;
+        #endif
 
         /**
          * @brief Constructor
@@ -69,15 +106,15 @@ class TextureData {
          * @param image                 Texture image ID
          * @param importerState         Importer-specific state
          */
-        explicit TextureData(Type type, SamplerFilter minificationFilter, SamplerFilter magnificationFilter, SamplerMipmap mipmapFilter, const Math::Vector3<SamplerWrapping>& wrapping, UnsignedInt image, const void* importerState = nullptr) noexcept: _type{type}, _minificationFilter{minificationFilter}, _magnificationFilter{magnificationFilter}, _mipmapFilter{mipmapFilter}, _wrapping{wrapping}, _image{image}, _importerState{importerState} {}
+        explicit TextureData(TextureType type, SamplerFilter minificationFilter, SamplerFilter magnificationFilter, SamplerMipmap mipmapFilter, const Math::Vector3<SamplerWrapping>& wrapping, UnsignedInt image, const void* importerState = nullptr) noexcept: _type{type}, _minificationFilter{minificationFilter}, _magnificationFilter{magnificationFilter}, _mipmapFilter{mipmapFilter}, _wrapping{wrapping}, _image{image}, _importerState{importerState} {}
 
         /**
          * @brief Construct with the same wrapping for all dimensions
          *
-         * Same as calling @ref TextureData(Type, SamplerFilter, SamplerFilter, SamplerMipmap, const Math::Vector3<SamplerWrapping>&, UnsignedInt, const void*)
+         * Same as calling @ref TextureData(TextureType, SamplerFilter, SamplerFilter, SamplerMipmap, const Math::Vector3<SamplerWrapping>&, UnsignedInt, const void*)
          * with the same @p wrapping value for all dimensions.
          */
-        explicit TextureData(Type type, SamplerFilter minificationFilter, SamplerFilter magnificationFilter, SamplerMipmap mipmapFilter, SamplerWrapping wrapping, UnsignedInt image, const void* importerState = nullptr) noexcept: _type{type}, _minificationFilter{minificationFilter}, _magnificationFilter{magnificationFilter}, _mipmapFilter{mipmapFilter}, _wrapping{wrapping}, _image{image}, _importerState{importerState} {}
+        explicit TextureData(TextureType type, SamplerFilter minificationFilter, SamplerFilter magnificationFilter, SamplerMipmap mipmapFilter, SamplerWrapping wrapping, UnsignedInt image, const void* importerState = nullptr) noexcept: _type{type}, _minificationFilter{minificationFilter}, _magnificationFilter{magnificationFilter}, _mipmapFilter{mipmapFilter}, _wrapping{wrapping}, _image{image}, _importerState{importerState} {}
 
         /** @brief Copying is not allowed */
         TextureData(const TextureData&) = delete;
@@ -92,7 +129,7 @@ class TextureData {
         TextureData& operator=(TextureData&&) noexcept = default;
 
         /** @brief Texture type */
-        Type type() const { return _type; }
+        TextureType type() const { return _type; }
 
         /** @brief Minification filter */
         SamplerFilter minificationFilter() const { return _minificationFilter; }
@@ -109,11 +146,10 @@ class TextureData {
         /**
          * @brief Image ID
          *
-         * ID of 1D, 2D or 3D image based on texture type. If type is
-         * @ref Type::Cube the function returns first of six consecutive
-         * IDs of cube map sides, ordered +X, -X, +Y, -Y, +Z, -Z.
+         * ID of a 1D, 2D or 3D image depending on @ref type().
          * @see @ref type(), @ref AbstractImporter::image1D(),
-         *      @ref AbstractImporter::image2D(), @ref AbstractImporter::image3D()
+         *      @ref AbstractImporter::image2D(),
+         *      @ref AbstractImporter::image3D()
          */
         UnsignedInt image() const { return _image; }
 
@@ -125,7 +161,7 @@ class TextureData {
         const void* importerState() const { return _importerState; }
 
     private:
-        Type _type;
+        TextureType _type;
         SamplerFilter _minificationFilter, _magnificationFilter;
         SamplerMipmap _mipmapFilter;
         Math::Vector3<SamplerWrapping> _wrapping;
@@ -133,8 +169,8 @@ class TextureData {
         const void* _importerState;
 };
 
-/** @debugoperatorclassenum{TextureData,TextureData::Type} */
-MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, TextureData::Type value);
+/** @debugoperatorenum{TextureType} */
+MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, TextureType value);
 
 }}