Trade: support mip levels in image import

doc/changelog.dox

@@ -150,6 +150,13 @@ See also:
     and @ref SceneGraph::AbstractBasicTranslationRotation3D::rotateLocal(const Math::Quaternion<T>&) "rotateLocal()"
     overloads taking a @ref Math::Quaternion
 
+@subsubsection changelog-latest-new-trade Trade library
+
+-   Ability to import image mip levels via an additional parameter in
+    @ref Trade::AbstractImporter::image2D(),
+    @ref Trade::AbstractImporter::image2DLevelCount() and similar APIs for 1D
+    and 3D images
+
 @subsubsection changelog-latest-new-vk Vk library
 
 -   Updated Vulkan headers for version 1.2

src/Magnum/Trade/AbstractImporter.cpp

@@ -52,7 +52,7 @@
 namespace Magnum { namespace Trade {
 
 std::string AbstractImporter::pluginInterface() {
-    return "cz.mosra.magnum.Trade.AbstractImporter/0.3";
+    return "cz.mosra.magnum.Trade.AbstractImporter/0.3.1";
 }
 
 #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT
@@ -538,6 +538,16 @@ UnsignedInt AbstractImporter::image1DCount() const {
 
 UnsignedInt AbstractImporter::doImage1DCount() const { return 0; }
 
+UnsignedInt AbstractImporter::image1DLevelCount(const UnsignedInt id) {
+    CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image1DLevelCount(): no file opened", {});
+    CORRADE_ASSERT(id < doImage1DCount(), "Trade::AbstractImporter::image1DLevelCount(): index" << id << "out of range for" << doImage1DCount() << "entries", {});
+    const UnsignedInt out = doImage1DLevelCount(id);
+    CORRADE_ASSERT(out, "Trade::AbstractImporter::image1DLevelCount(): implementation reported zero levels", {});
+    return out;
+}
+
+UnsignedInt AbstractImporter::doImage1DLevelCount(UnsignedInt) { return 1; }
+
 Int AbstractImporter::image1DForName(const std::string& name) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image1DForName(): no file opened", {});
     return doImage1DForName(name);
@@ -553,15 +563,27 @@ std::string AbstractImporter::image1DName(const UnsignedInt id) {
 
 std::string AbstractImporter::doImage1DName(UnsignedInt) { return {}; }
 
-Containers::Optional<ImageData1D> AbstractImporter::image1D(const UnsignedInt id) {
+Containers::Optional<ImageData1D> AbstractImporter::image1D(const UnsignedInt id, const UnsignedInt level) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image1D(): no file opened", {});
     CORRADE_ASSERT(id < doImage1DCount(), "Trade::AbstractImporter::image1D(): index" << id << "out of range for" << doImage1DCount() << "entries", {});
-    Containers::Optional<ImageData1D> image = doImage1D(id);
+    #ifndef CORRADE_NO_ASSERT
+    /* Check for the range only if requested level is nonzero, as
+       image*DLevelCount() is expected to return >= 1. This is done to prevent
+       random assertions and messages from a doImage*DLevelCount() to be
+       printed (e.g., many plugins delegate image loading and assert an access
+       to the manager for that), which may be confusing */
+    if(level) {
+        const UnsignedInt levelCount = doImage1DLevelCount(id);
+        CORRADE_ASSERT(levelCount, "Trade::AbstractImporter::image1D(): implementation reported zero levels", {});
+        CORRADE_ASSERT(level < levelCount, "Trade::AbstractImporter::image1D(): level" << level << "out of range for" << levelCount << "entries", {});
+    }
+    #endif
+    Containers::Optional<ImageData1D> image = doImage1D(id, level);
     CORRADE_ASSERT(!image || !image->_data.deleter(), "Trade::AbstractImporter::image1D(): implementation is not allowed to use a custom Array deleter", {});
     return image;
 }
 
-Containers::Optional<ImageData1D> AbstractImporter::doImage1D(UnsignedInt) {
+Containers::Optional<ImageData1D> AbstractImporter::doImage1D(UnsignedInt, UnsignedInt) {
     CORRADE_ASSERT(false, "Trade::AbstractImporter::image1D(): not implemented", {});
 }
 
@@ -572,6 +594,16 @@ UnsignedInt AbstractImporter::image2DCount() const {
 
 UnsignedInt AbstractImporter::doImage2DCount() const { return 0; }
 
+UnsignedInt AbstractImporter::image2DLevelCount(const UnsignedInt id) {
+    CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image2DLevelCount(): no file opened", {});
+    CORRADE_ASSERT(id < doImage2DCount(), "Trade::AbstractImporter::image2DLevelCount(): index" << id << "out of range for" << doImage2DCount() << "entries", {});
+    const UnsignedInt out = doImage2DLevelCount(id);
+    CORRADE_ASSERT(out, "Trade::AbstractImporter::image2DLevelCount(): implementation reported zero levels", {});
+    return out;
+}
+
+UnsignedInt AbstractImporter::doImage2DLevelCount(UnsignedInt) { return 1; }
+
 Int AbstractImporter::image2DForName(const std::string& name) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image2DForName(): no file opened", {});
     return doImage2DForName(name);
@@ -587,15 +619,27 @@ std::string AbstractImporter::image2DName(const UnsignedInt id) {
 
 std::string AbstractImporter::doImage2DName(UnsignedInt) { return {}; }
 
-Containers::Optional<ImageData2D> AbstractImporter::image2D(const UnsignedInt id) {
+Containers::Optional<ImageData2D> AbstractImporter::image2D(const UnsignedInt id, const UnsignedInt level) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image2D(): no file opened", {});
     CORRADE_ASSERT(id < doImage2DCount(), "Trade::AbstractImporter::image2D(): index" << id << "out of range for" << doImage2DCount() << "entries", {});
-    Containers::Optional<ImageData2D> image = doImage2D(id);
+    #ifndef CORRADE_NO_ASSERT
+    /* Check for the range only if requested level is nonzero, as
+       image*DLevelCount() is expected to return >= 1. This is done to prevent
+       random assertions and messages from a doImage*DLevelCount() to be
+       printed (e.g., many plugins delegate image loading and assert an access
+       to the manager for that), which may be confusing */
+    if(level) {
+        const UnsignedInt levelCount = doImage2DLevelCount(id);
+        CORRADE_ASSERT(levelCount, "Trade::AbstractImporter::image2D(): implementation reported zero levels", {});
+        CORRADE_ASSERT(level < levelCount, "Trade::AbstractImporter::image2D(): level" << level << "out of range for" << levelCount << "entries", {});
+    }
+    #endif
+    Containers::Optional<ImageData2D> image = doImage2D(id, level);
     CORRADE_ASSERT(!image || !image->_data.deleter(), "Trade::AbstractImporter::image2D(): implementation is not allowed to use a custom Array deleter", {});
     return image;
 }
 
-Containers::Optional<ImageData2D> AbstractImporter::doImage2D(UnsignedInt) {
+Containers::Optional<ImageData2D> AbstractImporter::doImage2D(UnsignedInt, UnsignedInt) {
     CORRADE_ASSERT(false, "Trade::AbstractImporter::image2D(): not implemented", {});
 }
 
@@ -606,6 +650,16 @@ UnsignedInt AbstractImporter::image3DCount() const {
 
 UnsignedInt AbstractImporter::doImage3DCount() const { return 0; }
 
+UnsignedInt AbstractImporter::image3DLevelCount(const UnsignedInt id) {
+    CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image3DLevelCount(): no file opened", {});
+    CORRADE_ASSERT(id < doImage3DCount(), "Trade::AbstractImporter::image3DLevelCount(): index" << id << "out of range for" << doImage3DCount() << "entries", {});
+    const UnsignedInt out = doImage3DLevelCount(id);
+    CORRADE_ASSERT(out, "Trade::AbstractImporter::image3DLevelCount(): implementation reported zero levels", {});
+    return out;
+}
+
+UnsignedInt AbstractImporter::doImage3DLevelCount(UnsignedInt) { return 1; }
+
 Int AbstractImporter::image3DForName(const std::string& name) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image3DForName(): no file opened", {});
     return doImage3DForName(name);
@@ -621,15 +675,27 @@ std::string AbstractImporter::image3DName(const UnsignedInt id) {
 
 std::string AbstractImporter::doImage3DName(UnsignedInt) { return {}; }
 
-Containers::Optional<ImageData3D> AbstractImporter::image3D(const UnsignedInt id) {
+Containers::Optional<ImageData3D> AbstractImporter::image3D(const UnsignedInt id, const UnsignedInt level) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::image3D(): no file opened", {});
     CORRADE_ASSERT(id < doImage3DCount(), "Trade::AbstractImporter::image3D(): index" << id << "out of range for" << doImage3DCount() << "entries", {});
-    Containers::Optional<ImageData3D> image = doImage3D(id);
+    #ifndef CORRADE_NO_ASSERT
+    /* Check for the range only if requested level is nonzero, as
+       image*DLevelCount() is expected to return >= 1. This is done to prevent
+       random assertions and messages from a doImage*DLevelCount() to be
+       printed (e.g., many plugins delegate image loading and assert an access
+       to the manager for that), which may be confusing */
+    if(level) {
+        const UnsignedInt levelCount = doImage3DLevelCount(id);
+        CORRADE_ASSERT(levelCount, "Trade::AbstractImporter::image3D(): implementation reported zero levels", {});
+        CORRADE_ASSERT(level < levelCount, "Trade::AbstractImporter::image3D(): level" << level << "out of range for" << levelCount << "entries", {});
+    }
+    #endif
+    Containers::Optional<ImageData3D> image = doImage3D(id, level);
     CORRADE_ASSERT(!image || !image->_data.deleter(), "Trade::AbstractImporter::image3D(): implementation is not allowed to use a custom Array deleter", {});
     return image;
 }
 
-Containers::Optional<ImageData3D> AbstractImporter::doImage3D(UnsignedInt) {
+Containers::Optional<ImageData3D> AbstractImporter::doImage3D(UnsignedInt, UnsignedInt) {
     CORRADE_ASSERT(false, "Trade::AbstractImporter::image3D(): not implemented", {});
 }
 

src/Magnum/Trade/AbstractImporter.h

@@ -243,6 +243,9 @@ checked by the implementation:
     there is any file opened.
 -   All `do*()` implementations taking data ID as parameter are called only if
     the ID is from valid range.
+-   For `doImage*()` and @p level parameter being nonzero, implementations are
+    called only if it is from valid range. Level zero is always expected to be
+    present and thus no check is done in that case.
 
 @m_class{m-block m-warning}
 
@@ -282,7 +285,7 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          * @brief Plugin interface
          *
          * @code{.cpp}
-         * "cz.mosra.magnum.Trade.AbstractImporter/0.3"
+         * "cz.mosra.magnum.Trade.AbstractImporter/0.3.1"
          * @endcode
          */
         static std::string pluginInterface();
@@ -813,9 +816,20 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          * @brief One-dimensional image count
          *
          * Expects that a file is opened.
+         * @see @ref image1DLevelCount()
          */
         UnsignedInt image1DCount() const;
 
+        /**
+         * @brief One-dimensional image mip level count
+         * @param id        Image ID, from range [0, @ref image1DCount())
+         * @m_since_latest
+         *
+         * Always returns at least one level, import failures are deferred to
+         * @ref image1D(). Expects that a file is opened.
+         */
+        UnsignedInt image1DLevelCount(UnsignedInt id);
+
         /**
          * @brief One-dimensional image ID for given name
          *
@@ -837,19 +851,31 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /**
          * @brief One-dimensional image
          * @param id        Image ID, from range [0, @ref image1DCount()).
+         * @param level     Mip level, from range [0, @ref image1DLevelCount())
          *
          * Returns given image or @ref Containers::NullOpt if importing failed.
          * Expects that a file is opened.
          */
-        Containers::Optional<ImageData1D> image1D(UnsignedInt id);
+        Containers::Optional<ImageData1D> image1D(UnsignedInt id, UnsignedInt level = 0);
 
         /**
          * @brief Two-dimensional image count
          *
          * Expects that a file is opened.
+         * @see @ref image2DLevelCount()
          */
         UnsignedInt image2DCount() const;
 
+        /**
+         * @brief Two-dimensional image mip level count
+         * @param id        Image ID, from range [0, @ref image2DCount()).
+         * @m_since_latest
+         *
+         * Always returns at least one level, import failures are deferred to
+         * @ref image2D(). Expects that a file is opened.
+         */
+        UnsignedInt image2DLevelCount(UnsignedInt id);
+
         /**
          * @brief Two-dimensional image ID for given name
          *
@@ -871,19 +897,31 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /**
          * @brief Two-dimensional image
          * @param id        Image ID, from range [0, @ref image2DCount()).
+         * @param level     Mip level, from range [0, @ref image2DLevelCount())
          *
          * Returns given image or @ref Containers::NullOpt if importing failed.
          * Expects that a file is opened.
          */
-        Containers::Optional<ImageData2D> image2D(UnsignedInt id);
+        Containers::Optional<ImageData2D> image2D(UnsignedInt id, UnsignedInt level = 0);
 
         /**
          * @brief Three-dimensional image count
          *
          * Expects that a file is opened.
+         * @see @ref image3DLevelCount()
          */
         UnsignedInt image3DCount() const;
 
+        /**
+         * @brief Three-dimensional image mip level count
+         * @param id        Image ID, from range [0, @ref image3DCount())
+         * @m_since_latest
+         *
+         * Always returns at least one level, import failures are deferred to
+         * @ref image3D(). Expects that a file is opened.
+         */
+        UnsignedInt image3DLevelCount(UnsignedInt id);
+
         /**
          * @brief Three-dimensional image ID for given name
          *
@@ -905,11 +943,12 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /**
          * @brief Three-dimensional image
          * @param id        Image ID, from range [0, @ref image3DCount()).
+         * @param level     Mip level, from range [0, @ref image3DLevelCount())
          *
          * Returns given image or @ref Containers::NullOpt if importing failed.
          * Expects that a file is opened.
          */
-        Containers::Optional<ImageData3D> image3D(UnsignedInt id);
+        Containers::Optional<ImageData3D> image3D(UnsignedInt id, UnsignedInt level = 0);
 
         /*@}*/
 
@@ -1228,6 +1267,14 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         virtual UnsignedInt doImage1DCount() const;
 
+        /**
+         * @brief Implementation for @ref image1DLevelCount()
+         *
+         * Default implementation returns @cpp 1 @ce. See
+         * @ref doImage2DLevelCount() for expected implementation behavior.
+         */
+        virtual UnsignedInt doImage1DLevelCount(UnsignedInt id);
+
         /**
          * @brief Implementation for @ref image1DForName()
          *
@@ -1243,7 +1290,7 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         virtual std::string doImage1DName(UnsignedInt id);
 
         /** @brief Implementation for @ref image1D() */
-        virtual Containers::Optional<ImageData1D> doImage1D(UnsignedInt id);
+        virtual Containers::Optional<ImageData1D> doImage1D(UnsignedInt id, UnsignedInt level);
 
         /**
          * @brief Implementation for @ref image2DCount()
@@ -1252,6 +1299,22 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         virtual UnsignedInt doImage2DCount() const;
 
+        /**
+         * @brief Implementation for @ref image2DLevelCount()
+         *
+         * Default implementation returns @cpp 1 @ce. Similarly to all other
+         * `*Count()` functions, this function isn't expected to fail --- if an
+         * import error occus, this function should return @cpp 1 @ce and the
+         * error state should be returned from @ref image2D() instead; if a
+         * file really contains a zero-level image, the implementation should
+         * exclude that image from @ref doImage2DCount() instead of returning
+         * @cpp 0 @ce here.
+         *
+         * Deliberately not @cpp const @ce to allow plugins cache decoded
+         * data.
+         */
+        virtual UnsignedInt doImage2DLevelCount(UnsignedInt id);
+
         /**
          * @brief Implementation for @ref image2DForName()
          *
@@ -1267,7 +1330,7 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         virtual std::string doImage2DName(UnsignedInt id);
 
         /** @brief Implementation for @ref image2D() */
-        virtual Containers::Optional<ImageData2D> doImage2D(UnsignedInt id);
+        virtual Containers::Optional<ImageData2D> doImage2D(UnsignedInt id, UnsignedInt level);
 
         /**
          * @brief Implementation for @ref image3DCount()
@@ -1276,6 +1339,14 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         virtual UnsignedInt doImage3DCount() const;
 
+        /**
+         * @brief Implementation for @ref image3DLevelCount()
+         *
+         * Default implementation returns @cpp 1 @ce. See
+         * @ref doImage2DLevelCount() for expected implementation behavior.
+         */
+        virtual UnsignedInt doImage3DLevelCount(UnsignedInt id);
+
         /**
          * @brief Implementation for @ref image3DForName()
          *
@@ -1291,7 +1362,7 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         virtual std::string doImage3DName(UnsignedInt id);
 
         /** @brief Implementation for @ref image3D() */
-        virtual Containers::Optional<ImageData3D> doImage3D(UnsignedInt id);
+        virtual Containers::Optional<ImageData3D> doImage3D(UnsignedInt id, UnsignedInt level);
 
         /** @brief Implementation for @ref importerState() */
         virtual const void* doImporterState() const;