saver: Revised the API for the 1.0 release

replaced the 'compress' option with 'quality'

API changes:
Result Saver::save(std::unique_ptr<Paint> paint, const std::string& path, bool compress) ->
Result Saver::save(std::unique_ptr<Paint> paint, const std::string& path, uint32_t quality = 100)

TVG_API Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, bool compress) ->
Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, uint32_t quality)

Issue: #1372

inc/thorvg.h

@@ -1753,7 +1753,7 @@ public:
      *
      * @param[in] paint The paint to be saved with all its associated properties.
      * @param[in] path A path to the file, in which the paint data is to be saved.
-     * @param[in] compress If @c true then compress data if possible.
+     * @param[in] quality The encoded quality level. @c 0 is the minimum, @c 100 is the maximum value(recommended).
      *
      * @retval Result::Success When succeed.
      * @retval Result::InsufficientCondition If currently saving other resources.
@@ -1766,7 +1766,7 @@ public:
      *
      * @since 0.5
      */
-    Result save(std::unique_ptr<Paint> paint, const std::string& path, bool compress = true) noexcept;
+    Result save(std::unique_ptr<Paint> paint, const std::string& path, uint32_t quality = 100) noexcept;
 
     /**
      * @brief Guarantees that the saving task is finished.

src/bindings/capi/thorvg_capi.h

@@ -2145,7 +2145,7 @@ TVG_API Tvg_Saver* tvg_saver_new();
 * \param[in] saver The Tvg_Saver object connected with the saving task.
 * \param[in] paint The paint to be saved with all its associated properties.
 * \param[in] path A path to the file, in which the paint data is to be saved.
-* \param[in] compress If @c true then compress data if possible.
+* \param[in] quality The encoded quality level. @c 0 is the minimum, @c 100 is the maximum value(recommended).
 *
 * \return Tvg_Result enumeration.
 * \retval TVG_RESULT_SUCCESS Succeed.
@@ -2158,7 +2158,7 @@ TVG_API Tvg_Saver* tvg_saver_new();
 * \note Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call tvg_saver_sync() afterwards.
 * \see tvg_saver_sync()
 */
-TVG_API Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, bool compress);
+TVG_API Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, uint32_t quality);
 
 
 /*!
@@ -2226,7 +2226,7 @@ TVG_API Tvg_Animation* tvg_animation_new();
 * \return Tvg_Result enumeration.
 * \retval TVG_RESULT_SUCCESS Succeed.
 * \retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Animation pointer.
-* \retval TVG_RESULT_INSUFFICIENT_CONDITION No animatable data loaded from the Picture.
+* \retval TVG_RESULT_INSUFFICIENT_CONDITION if the given @p no is the same as the current frame value.
 * \retval TVG_RESULT_NOT_SUPPORTED The picture data does not support animations.
 *
 * \see tvg_animation_get_total_frame()

src/bindings/capi/tvgCapi.cpp

@@ -696,10 +696,10 @@ TVG_API Tvg_Saver* tvg_saver_new()
 }
 
 
-TVG_API Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, bool compress)
+TVG_API Tvg_Result tvg_saver_save(Tvg_Saver* saver, Tvg_Paint* paint, const char* path, uint32_t quality)
 {
     if (!saver || !paint || !path) return TVG_RESULT_INVALID_ARGUMENT;
-    return (Tvg_Result) reinterpret_cast<Saver*>(saver)->save(unique_ptr<Paint>((Paint*)paint), path, compress);
+    return (Tvg_Result) reinterpret_cast<Saver*>(saver)->save(unique_ptr<Paint>((Paint*)paint), path, quality);
 }
 
 

src/renderer/tvgSaveModule.h

@@ -33,7 +33,7 @@ class SaveModule
 public:
     virtual ~SaveModule() {}
 
-    virtual bool save(Paint* paint, const string& path, bool compress) = 0;
+    virtual bool save(Paint* paint, const string& path, uint32_t quality) = 0;
     virtual bool close() = 0;
 };
 

src/renderer/tvgSaver.cpp

@@ -98,7 +98,7 @@ Saver::~Saver()
 }
 
 
-Result Saver::save(std::unique_ptr<Paint> paint, const string& path, bool compress) noexcept
+Result Saver::save(std::unique_ptr<Paint> paint, const string& path, uint32_t quality) noexcept
 {
     auto p = paint.release();
     if (!p) return Result::MemoryCorruption;
@@ -110,7 +110,7 @@ Result Saver::save(std::unique_ptr<Paint> paint, const string& path, bool compre
     }
 
     if (auto saveModule = _find(path)) {
-        if (saveModule->save(p, path, compress)) {
+        if (saveModule->save(p, path, quality)) {
             pImpl->saveModule = saveModule;
             return Result::Success;
         } else {

src/savers/tvg/tvgTvgSaver.cpp

@@ -135,8 +135,6 @@ static bool _merge(Shape* from, Shape* to)
 
 bool TvgSaver::saveEncoding(const std::string& path)
 {
-    if (!compress) return flushTo(path);
-
     //Try encoding
     auto uncompressed = buffer.data + headerSize;
     auto uncompressedSize = buffer.count - headerSize;
@@ -793,7 +791,7 @@ bool TvgSaver::close()
 }
 
 
-bool TvgSaver::save(Paint* paint, const string& path, bool compress)
+bool TvgSaver::save(Paint* paint, const string& path, TVG_UNUSED uint32_t quality)
 {
     close();
 
@@ -814,7 +812,6 @@ bool TvgSaver::save(Paint* paint, const string& path, bool compress)
     if (!this->path) return false;
 
     this->paint = paint;
-    this->compress = compress;
 
     TaskScheduler::request(this);
 

src/savers/tvg/tvgTvgSaver.h

@@ -38,7 +38,6 @@ private:
     char *path = nullptr;
     uint32_t headerSize;
     float vsize[2] = {0.0f, 0.0f};
-    bool compress;
 
     bool flushTo(const std::string& path);
     bool saveEncoding(const std::string& path);
@@ -68,7 +67,7 @@ private:
 public:
     ~TvgSaver();
 
-    bool save(Paint* paint, const string& path, bool compress) override;
+    bool save(Paint* paint, const string& path, uint32_t quality) override;
     bool close() override;
     void run(unsigned tid) override;
 };

test/capi/capiSavers.cpp

@@ -55,21 +55,21 @@ TEST_CASE("Save a paint into a file", "[capiSaver]")
     REQUIRE(paint3);
 
     //An invalid argument
-    REQUIRE(tvg_saver_save(nullptr, paint_empty, TEST_DIR"/test.tvg", false) == TVG_RESULT_INVALID_ARGUMENT);
+    REQUIRE(tvg_saver_save(nullptr, paint_empty, TEST_DIR"/test.tvg", 50) == TVG_RESULT_INVALID_ARGUMENT);
-    REQUIRE(tvg_saver_save(saver, nullptr, TEST_DIR"/test.tvg", false) == TVG_RESULT_INVALID_ARGUMENT);
+    REQUIRE(tvg_saver_save(saver, nullptr, TEST_DIR"/test.tvg", 999999) == TVG_RESULT_INVALID_ARGUMENT);
-    REQUIRE(tvg_saver_save(saver, paint_empty, nullptr, false) == TVG_RESULT_INVALID_ARGUMENT);
+    REQUIRE(tvg_saver_save(saver, paint_empty, nullptr, 100) == TVG_RESULT_INVALID_ARGUMENT);
 
     //Save an empty paint
-    REQUIRE(tvg_saver_save(saver, paint_empty, TEST_DIR"/test.tvg", false) == TVG_RESULT_UNKNOWN);
+    REQUIRE(tvg_saver_save(saver, paint_empty, TEST_DIR"/test.tvg", 0) == TVG_RESULT_UNKNOWN);
 
     //Unsupported target file format
-    REQUIRE(tvg_saver_save(saver, paint1, TEST_DIR"/test.err", false) == TVG_RESULT_NOT_SUPPORTED);
+    REQUIRE(tvg_saver_save(saver, paint1, TEST_DIR"/test.err", 0) == TVG_RESULT_NOT_SUPPORTED);
 
     //Correct call
-    REQUIRE(tvg_saver_save(saver, paint2, TEST_DIR"/test.tvg", false) == TVG_RESULT_SUCCESS);
+    REQUIRE(tvg_saver_save(saver, paint2, TEST_DIR"/test.tvg", 100) == TVG_RESULT_SUCCESS);
 
     //Busy - saving some resources
-    REQUIRE(tvg_saver_save(saver, paint3, TEST_DIR"/test.tvg", false) == TVG_RESULT_INSUFFICIENT_CONDITION);
+    REQUIRE(tvg_saver_save(saver, paint3, TEST_DIR"/test.tvg", 100) == TVG_RESULT_INSUFFICIENT_CONDITION);
 
     REQUIRE(tvg_saver_del(saver) == TVG_RESULT_SUCCESS);
 }
@@ -92,11 +92,11 @@ TEST_CASE("Synchronize a Saver", "[capiSaver]")
     //Nothing to be synced
     REQUIRE(tvg_saver_sync(saver) == TVG_RESULT_INSUFFICIENT_CONDITION);
 
-    REQUIRE(tvg_saver_save(saver, paint1, TEST_DIR"/test.tvg", true) == TVG_RESULT_SUCCESS);
+    REQUIRE(tvg_saver_save(saver, paint1, TEST_DIR"/test.tvg", 100) == TVG_RESULT_SUCCESS);
 
     //Releasing the saving task
     REQUIRE(tvg_saver_sync(saver) == TVG_RESULT_SUCCESS);
-    REQUIRE(tvg_saver_save(saver, paint2, TEST_DIR"/test.tvg", true) == TVG_RESULT_SUCCESS);
+    REQUIRE(tvg_saver_save(saver, paint2, TEST_DIR"/test.tvg", 100) == TVG_RESULT_SUCCESS);
 
     REQUIRE(tvg_saver_del(saver) == TVG_RESULT_SUCCESS);
 }