capi: tvg_swcanvas_set_mempool capi added (#903)

* capi: tvg_swcanvas_set_mempool capi added

* tests: tvg_swcanvas_set_mempool added to the tests

src/bindings/capi/thorvg_capi.h

@@ -318,6 +318,16 @@ TVG_EXPORT Tvg_Result tvg_engine_term(unsigned engine_method);
 /* SwCanvas API                                                         */
 /************************************************************************/
 
+/**
+ * \brief Enumeration specifying the methods of Memory Pool behavior policy.
+ */
+typedef enum {
+    TVG_MEMPOOL_POLICY_DEFAULT = 0, ///< Default behavior that ThorVG is designed to.
+    TVG_MEMPOOL_POLICY_SHAREABLE,   ///< Memory Pool is shared among canvases.
+    TVG_MEMPOOL_POLICY_INDIVIDUAL   ///< Allocate designated memory pool that is used only by the current canvas instance.
+} Tvg_Mempool_Policy;
+
+
 /**
  * \brief Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.
  */
@@ -326,6 +336,7 @@ typedef enum {
     TVG_COLORSPACE_ARGB8888      ///< The 8-bit color channels are combined into 32-bit color in the order: alpha, red, green, blue.
 } Tvg_Colorspace;
 
+
 /*!
 * \brief Creates a Canvas object.
 *
@@ -381,6 +392,32 @@ TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create();
 TVG_EXPORT Tvg_Result tvg_swcanvas_set_target(Tvg_Canvas* canvas, uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Tvg_Colorspace cs);
 
 
+/*!
+* \brief Sets the software engine memory pool behavior policy.
+*
+* ThorVG draws a lot of shapes, it allocates/deallocates a few chunk of memory
+* while processing rendering. It internally uses one shared memory pool
+* which can be reused among the canvases in order to avoid memory overhead.
+*
+* Thus ThorVG suggests using a memory pool policy to satisfy user demands,
+* if it needs to guarantee the thread-safety of the internal data access.
+*
+* \param[in] canvas The Tvg_Canvas object of which the Memory Pool behavior is to be specified.
+* \param[in] policy The method specifying the Memory Pool behavior. The default value is @c TVG_MEMPOOL_POLICY_DEFAULT.
+*
+* \return Tvg_Result enumeration.
+* \retval TVG_RESULT_SUCCESS Succeed.
+* \retval TVG_RESULT_INVALID_ARGUMENTS An invalid canvas pointer passed.
+* \retval TVG_RESULT_INSUFFICIENT_CONDITION The canvas contains some paints already.
+* \retval TVG_RESULT_NOT_SUPPORTED The software engine is not supported.
+*
+* \note When @c policy is set as @c TVG_MEMPOOL_POLICY_INDIVIDUAL, the current instance of canvas uses its own individual
+*       memory data, which is not shared with others. This is necessary when the canvas is accessed on a worker-thread.
+*
+* \warning It's not allowed after pushing any paints.
+*/
+TVG_EXPORT Tvg_Result tvg_swcanvas_set_mempool(Tvg_Canvas* canvas, Tvg_Mempool_Policy policy);
+
 /** \} */   // end defgroup ThorVGCapi_SwCanvas
 
 

src/bindings/capi/tvgCapi.cpp

@@ -68,6 +68,13 @@ TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas* canvas)
 }
 
 
+TVG_EXPORT Tvg_Result tvg_swcanvas_set_mempool(Tvg_Canvas* canvas, Tvg_Mempool_Policy policy)
+{
+    if (!canvas) return TVG_RESULT_INVALID_ARGUMENT;
+    return (Tvg_Result) reinterpret_cast<SwCanvas*>(canvas)->mempool(static_cast<SwCanvas::MempoolPolicy>(policy));
+}
+
+
 TVG_EXPORT Tvg_Result tvg_swcanvas_set_target(Tvg_Canvas* canvas, uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Tvg_Colorspace cs)
 {
     if (!canvas) return TVG_RESULT_INVALID_ARGUMENT;

test/capi/capiSwCanvas.cpp

@@ -76,6 +76,8 @@ TEST_CASE("Canvas initialization", "[capiSwCanvas]")
 
     REQUIRE(tvg_swcanvas_set_target(canvas, buffer, 200, 200, 200, TVG_COLORSPACE_ARGB8888) == TVG_RESULT_SUCCESS);
 
+    REQUIRE(tvg_swcanvas_set_mempool(canvas, TVG_MEMPOOL_POLICY_DEFAULT) == TVG_RESULT_SUCCESS);
+
     REQUIRE(tvg_canvas_destroy(canvas) == TVG_RESULT_SUCCESS);
 
     REQUIRE(tvg_engine_term(TVG_ENGINE_SW) == TVG_RESULT_SUCCESS);