Trade: improve AbstractImageConverter API.

Provide a way to convert compressed images to data/file (i.e. saving DXT5-compressed image data to DDS file), improve feature flags so that the plugin can properly advertise what's supported (for example some plugin may just be able to compress RGBA to DXT5, but not to save that to DDS file). This is backwards-incompatible API breakage (renamed enum value), but because the original API wasn't in any official release yet, I'm not doing any deprecation and backwards compatibility.
11 years ago · 2cbb57c6da
2 changed files with 109 additions and 16 deletions
--- a/src/Magnum/Trade/AbstractImageConverter.cpp
+++ b/src/Magnum/Trade/AbstractImageConverter.cpp
@ -50,7 +50,7 @@ std::optional<Image2D> AbstractImageConverter::doExportToImage(const ImageView2D
 }

 std::optional<CompressedImage2D> AbstractImageConverter::exportToCompressedImage(const ImageView2D& image) const {
-    CORRADE_ASSERT(features() & Feature::CompressImage,
+    CORRADE_ASSERT(features() & Feature::ConvertCompressedImage,
        "Trade::AbstractImageConverter::exportToCompressedImage(): feature not supported", {});

    return doExportToCompressedImage(image);
@ -73,7 +73,22 @@ Containers::Array<char> AbstractImageConverter::doExportToData(const ImageView2D
    return nullptr;
 }

+Containers::Array<char> AbstractImageConverter::exportToData(const CompressedImageView2D& image) const {
+    CORRADE_ASSERT(features() & Feature::ConvertCompressedData,
+        "Trade::AbstractImageConverter::exportToData(): feature not supported", nullptr);
+
+    return doExportToData(image);
+}
+
+Containers::Array<char> AbstractImageConverter::doExportToData(const CompressedImageView2D&) const {
+    CORRADE_ASSERT(false, "Trade::AbstractImageConverter::exportToData(): feature advertised but not implemented", nullptr);
+    return nullptr;
+}
+
 bool AbstractImageConverter::exportToFile(const ImageView2D& image, const std::string& filename) const {
+    CORRADE_ASSERT(features() & Feature::ConvertFile,
+        "Trade::AbstractImageConverter::exportToFile(): feature not supported", {});
+
    return doExportToFile(image, filename);
 }

@ -92,4 +107,26 @@ bool AbstractImageConverter::doExportToFile(const ImageView2D& image, const std:
    return true;
 }

+bool AbstractImageConverter::exportToFile(const CompressedImageView2D& image, const std::string& filename) const {
+    CORRADE_ASSERT(features() & Feature::ConvertCompressedFile,
+        "Trade::AbstractImageConverter::exportToFile(): feature not supported", {});
+
+    return doExportToFile(image, filename);
+}
+
+bool AbstractImageConverter::doExportToFile(const CompressedImageView2D& image, const std::string& filename) const {
+    CORRADE_ASSERT(features() & Feature::ConvertCompressedData, "Trade::AbstractImageConverter::exportToFile(): not implemented", false);
+
+    const auto data = doExportToData(image);
+    if(!data) return false;
+
+    /* Open file */
+    if(!Utility::Directory::write(filename, data)) {
+        Error() << "Trade::AbstractImageConverter::exportToFile(): cannot write to file" << filename;
+        return false;
+    }
+
+    return true;
+}
+
 }}
--- a/src/Magnum/Trade/AbstractImageConverter.h
+++ b/src/Magnum/Trade/AbstractImageConverter.h
@ -55,10 +55,12 @@ checked by the implementation:

 -   Function @ref doExportToImage() is called only if @ref Feature::ConvertImage
    is supported.
-   Function @ref doExportToData() are called only if @ref Feature::ConvertData
-    is supported.
 -   Function @ref doExportToCompressedImage() is called only if
-    @ref Feature::CompressImage is supported.
+    @ref Feature::ConvertCompressedImage is supported.
+-   Function @ref doExportToData(const ImageView2D&) const is called only if
+    @ref Feature::ConvertData is supported.
+-   Function @ref doExportToData(const CompressedImageView2D&) const is called
+    only if @ref Feature::ConvertCompressedData is supported.

 Plugin interface string is `"cz.mosra.magnum.Trade.AbstractImageConverter/0.2.1"`.
 */
@ -76,10 +78,26 @@ class MAGNUM_EXPORT AbstractImageConverter: public PluginManager::AbstractPlugin
            ConvertImage = 1 << 0,

            /** Conversion to compressed image with @ref exportToCompressedImage() */
-            CompressImage = 1 << 1,
-
-            /** Exporting to raw data with @ref exportToData() */
-            ConvertData = 1 << 2
+            ConvertCompressedImage = 1 << 1,
+
+            /** Exporting to file with @ref exportToFile(const ImageView2D&, const std::string&) const */
+            ConvertFile = 1 << 2,
+
+            /** Exporting to file with @ref exportToFile(const CompressedImageView2D&, const std::string&) const */
+            ConvertCompressedFile = 1 << 3,
+
+            /**
+             * Exporting to raw data with @ref exportToData(const ImageView2D&) const.
+             * Implies @ref Feature::ConvertFile.
+             */
+            ConvertData = ConvertFile|(1 << 4),
+
+            /**
+             * Exporting compressed image to raw data with
+             * @ref exportToData(const CompressedImageView2D&) const. Implies
+             * @ref Feature::ConvertCompressedFile.
+             */
+            ConvertCompressedData = ConvertCompressedFile|(1 << 4)
        };

        /**
@ -110,8 +128,8 @@ class MAGNUM_EXPORT AbstractImageConverter: public PluginManager::AbstractPlugin
        /**
         * @brief Convert image to compressed format
         *
-         * Available only if @ref Feature::CompressImage is supported. Returns
-         * converted image on success, `std::nullopt` otherwise.
+         * Available only if @ref Feature::ConvertCompressedImage is supported.
+         * Returns converted image on success, `std::nullopt` otherwise.
         * @see @ref features(), @ref exportToData(), @ref exportToFile()
         */
        std::optional<CompressedImage2D> exportToCompressedImage(const ImageView2D& image) const;
@ -121,18 +139,43 @@ class MAGNUM_EXPORT AbstractImageConverter: public PluginManager::AbstractPlugin
         *
         * Available only if @ref Feature::ConvertData is supported. Returns
         * data on success, zero-sized array otherwise.
-         * @see @ref features(), @ref exportToImage(), @ref exportToFile()
+         * @see @ref features(), @ref exportToImage(),
+         *      @ref exportToFile(const ImageView2D&, const std::string&) const
         */
        Containers::Array<char> exportToData(const ImageView2D& image) const;

+        /**
+         * @brief Export compressed image to raw data
+         *
+         * Available only if @ref Feature::ConvertCompressedData is supported.
+         * Returns data on success, zero-sized array otherwise.
+         * @see @ref features(), @ref exportToCompressedImage(),
+         *      @ref exportToFile(const CompressedImageView2D&, const std::string&) const
+         */
+        Containers::Array<char> exportToData(const CompressedImageView2D& image) const;
+
        /**
         * @brief Export image to file
         *
-         * Returns `true` on success, `false` otherwise.
-         * @see @ref features(), @ref exportToImage(), @ref exportToData()
+         * Available only if @ref Feature::ConvertFile or
+         * @ref Feature::ConvertData is supported. Returns `true` on success,
+         * `false` otherwise.
+         * @see @ref features(), @ref exportToImage(),
+         *      @ref exportToData(const ImageView2D&) const
         */
        bool exportToFile(const ImageView2D& image, const std::string& filename) const;

+        /**
+         * @brief Export compressed image to file
+         *
+         * Available only if @ref Feature::ConvertCompressedFile or
+         * @ref Feature::ConvertCompressedData is supported. Returns `true` on
+         * success, `false` otherwise.
+         * @see @ref features(), @ref exportToCompressedImage(),
+         *      @ref exportToData(const CompressedImageView2D&) const
+         */
+        bool exportToFile(const CompressedImageView2D& image, const std::string& filename) const;
+
    #ifndef DOXYGEN_GENERATING_OUTPUT
    private:
    #else
@ -147,16 +190,29 @@ class MAGNUM_EXPORT AbstractImageConverter: public PluginManager::AbstractPlugin
        /** @brief Implementation of @ref exportToCompressedImage() */
        virtual std::optional<CompressedImage2D> doExportToCompressedImage(const ImageView2D& image) const;

-        /** @brief Implementation of @ref exportToData() */
+        /** @brief Implementation of @ref exportToData(const ImageView2D&) const */
        virtual Containers::Array<char> doExportToData(const ImageView2D& image) const;

+        /** @brief Implementation of @ref exportToData(const CompressedImageView2D&) const */
+        virtual Containers::Array<char> doExportToData(const CompressedImageView2D& image) const;
+
        /**
-         * @brief Implementation of @ref exportToFile()
+         * @brief Implementation of @ref exportToFile(const ImageView2D&, const std::string&) const
         *
         * If @ref Feature::ConvertData is supported, default implementation
-         * calls @ref doExportToData() and saves the result to given file.
+         * calls @ref doExportToData(const ImageView2D&) const and saves the
+         * result to given file.
         */
        virtual bool doExportToFile(const ImageView2D& image, const std::string& filename) const;
+
+        /**
+         * @brief Implementation of @ref exportToFile(const CompressedImageView2D&, const std::string&) const
+         *
+         * If @ref Feature::ConvertCompressedData is supported, default
+         * implementation calls @ref doExportToData(const CompressedImageView2D&) const
+         * and saves the result to given file.
+         */
+        virtual bool doExportToFile(const CompressedImageView2D& image, const std::string& filename) const;
 };

 CORRADE_ENUMSET_OPERATORS(AbstractImageConverter::Features)