From 046b9558b73d64292cf1af5111160b7a952dd4eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 20 Jul 2021 20:02:41 +0200 Subject: [PATCH] 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 | 9 +++ src/Magnum/Trade/Test/TextureDataTest.cpp | 16 ++--- src/Magnum/Trade/TextureData.cpp | 8 +-- src/Magnum/Trade/TextureData.h | 78 +++++++++++++++++------ 4 files changed, 78 insertions(+), 33 deletions(-) diff --git a/doc/changelog.dox b/doc/changelog.dox index a4a315ac1..a49085b51 100644 --- a/doc/changelog.dox +++ b/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 diff --git a/src/Magnum/Trade/Test/TextureDataTest.cpp b/src/Magnum/Trade/Test/TextureDataTest.cpp index 5f7d27be7..4e3f3a6fc 100644 --- a/src/Magnum/Trade/Test/TextureDataTest.cpp +++ b/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"); } }}}} diff --git a/src/Magnum/Trade/TextureData.cpp b/src/Magnum/Trade/TextureData.cpp index 01b37cf16..905343394 100644 --- a/src/Magnum/Trade/TextureData.cpp +++ b/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 */ } diff --git a/src/Magnum/Trade/TextureData.h b/src/Magnum/Trade/TextureData.h index f84109cb9..fb025fa01 100644 --- a/src/Magnum/Trade/TextureData.h +++ b/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& 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& 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&, UnsignedInt, const void*) + * Same as calling @ref TextureData(TextureType, SamplerFilter, SamplerFilter, SamplerMipmap, const Math::Vector3&, 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 _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); }}