inc/thorvg.h

   1 /*!
   2  * @file thorvg.h
   3  *
   4  * The main APIs enabling the TVG initialization, preparation of the canvas and provisioning of its content:
   5  * - drawing shapes such as line, curve, arc, rectangle, circle or user-defined
   6  * - drawing pictures - SVG, PNG, RAW
   7  * - solid or gradient filling
   8  * - continuous and dashed stroking
   9  * - clipping and masking
  10  * and finally drawing the canvas and TVG termination.
  11  */
  12
  13
  14 #ifndef _THORVG_H_
  15 #define _THORVG_H_
  16
  17 #include <memory>
  18 #include <string>
  19
  20 #ifdef TVG_BUILD
  21     #define TVG_EXPORT __attribute__ ((visibility ("default")))
  22 #else
  23     #define TVG_EXPORT
  24 #endif
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30
  31 #define _TVG_DECLARE_PRIVATE(A) \
  32 protected: \
  33     struct Impl; \
  34     Impl* pImpl; \
  35     A(const A&) = delete; \
  36     const A& operator=(const A&) = delete; \
  37     A()
  38
  39 #define _TVG_DISABLE_CTOR(A) \
  40     A() = delete; \
  41     ~A() = delete
  42
  43 #define _TVG_DECLARE_ACCESSOR() \
  44     friend Canvas; \
  45     friend Scene; \
  46     friend Picture; \
  47     friend Saver;
  48
  49
  50 #define _TVG_DECALRE_IDENTIFIER() \
  51     auto id() const { return _id; } \
  52 protected: \
  53     unsigned _id
  54
  55 namespace tvg
  56 {
  57
  58 class RenderMethod;
  59 class Scene;
  60 class Picture;
  61 class Canvas;
  62 class Saver;
  63
  64 /**
  65  * @defgroup ThorVG ThorVG
  66  * @brief ThorVG classes and enumerations providing C++ APIs.
  67  */
  68
  69 /**@{*/
  70
  71 /**
  72  * @brief Enumeration specifying the result from the APIs.
  73  */
  74 enum class TVG_EXPORT Result
  75 {
  76     Success = 0,           ///< The value returned in case of a correct request execution.
  77     InvalidArguments,      ///< The value returned in the event of a problem with the arguments given to the API - e.g. empty paths or null pointers.
  78     InsufficientCondition, ///< The value returned in case the request cannot be processed - e.g. asking for properties of an object, which does not exist.
  79     FailedAllocation,      ///< The value returned in case of unsuccessful memory allocation.
  80     MemoryCorruption,      ///< The value returned in the event of bad memory handling - e.g. failing in pointer releasing or casting
  81     NonSupport,            ///< The value returned in case of choosing unsupported options.
  82     Unknown                ///< The value returned in all other cases.
  83 };
  84
  85 /**
  86  * @brief Enumeration specifying the values of the path commands accepted by TVG.
  87  *
  88  * Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others).
  89  * TVG interprets all of them and translates to the ones from the PathCommand values.
  90  */
  91 enum class TVG_EXPORT PathCommand
  92 {
  93     Close = 0, ///< Ends the current sub-path and connects it with its initial point. This command doesn't expect any points.
  94     MoveTo,    ///< Sets a new initial point of the sub-path and a new current point. This command expects 1 point: the starting position.
  95     LineTo,    ///< Draws a line from the current point to the given point and sets a new value of the current point. This command expects 1 point: the end-position of the line.
  96     CubicTo    ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point. This command expects 3 points: the 1st control-point, the 2nd control-point, the end-point of the curve.
  97 };
  98
  99 /**
 100  * @brief Enumeration determining the ending type of a stroke in the open sub-paths.
 101  */
 102 enum class TVG_EXPORT StrokeCap
 103 {
 104     Square = 0, ///< The stroke is extended in both end-points of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width.
 105     Round,      ///< The stroke is extended in both end-points of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered.
 106     Butt        ///< The stroke ends exactly at each of the two end-points of a sub-path. For zero length sub-paths no stroke is rendered.
 107 };
 108
 109 /**
 110  * @brief Enumeration determining the style used at the corners of joined stroked path segments.
 111  */
 112 enum class TVG_EXPORT StrokeJoin
 113 {
 114     Bevel = 0, ///< The outer corner of the joined path segments is bevelled at the join point. The triangular region of the corner is enclosed by a straight line between the outer corners of each stroke.
 115     Round,     ///< The outer corner of the joined path segments is rounded. The circular region is centered at the join point.
 116     Miter      ///< The outer corner of the joined path segments is spiked. The spike is created by extension beyond the join point of the outer edges of the stroke until they intersect. In case the extension goes beyond the limit, the join style is converted to the Bevel style.
 117 };
 118
 119 /**
 120  * @brief Enumeration specifying how to fill the area outside the gradient bounds.
 121  */
 122 enum class TVG_EXPORT FillSpread
 123 {
 124     Pad = 0, ///< The remaining area is filled with the closest stop color.
 125     Reflect, ///< The gradient pattern is reflected outside the gradient area until the expected region is filled.
 126     Repeat   ///< The gradient pattern is repeated continuously beyond the gradient area until the expected region is filled.
 127 };
 128
 129 /**
 130  * @brief Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape.
 131  */
 132 enum class TVG_EXPORT FillRule
 133 {
 134     Winding = 0, ///< A line from the point to a location outside the shape is drawn. The intersections of the line with the path segment of the shape are counted. Starting from zero, if the path segment of the shape crosses the line clockwise, one is added, otherwise one is subtracted. If the resulting sum is non zero, the point is inside the shape.
 135     EvenOdd      ///< A line from the point to a location outside the shape is drawn and its intersections with the path segments of the shape are counted. If the number of intersections is an odd number, the point is inside the shape.
 136 };
 137
 138 /**
 139  * @brief Enumeration indicating the method used in the composition of two objects - the target and the source.
 140  */
 141 enum class TVG_EXPORT CompositeMethod
 142 {
 143     None = 0,     ///< No composition is applied.
 144     ClipPath,     ///< The intersection of the source and the target is determined and only the resulting pixels from the source are rendered.
 145     AlphaMask,    ///< The pixels of the source and the target are alpha blended. As a result, only the part of the source, which intersects with the target is visible.
 146     InvAlphaMask  ///< The pixels of the source and the complement to the target's pixels are alpha blended. As a result, only the part of the source which is not covered by the target is visible.
 147 };
 148
 149 /**
 150  * @brief Enumeration specifying the engine type used for the graphics backend. For multiple backeneds bitwise operation is allowed.
 151  */
 152 enum class TVG_EXPORT CanvasEngine
 153 {
 154     Sw = (1 << 1), ///< CPU rasterizer.
 155     Gl = (1 << 2)  ///< OpenGL rasterizer.
 156 };
 157
 158
 159 /**
 160  * @brief A data structure representing a point in two-dimensional space.
 161  */
 162 struct Point
 163 {
 164     float x, y;
 165 };
 166
 167
 168 /**
 169  * @brief A data structure representing a three-dimensional matrix.
 170  *
 171  * The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor.
 172  * The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively.
 173  * The elements e31 and e32 are set to 0, e33 is set to 1.
 174  */
 175 struct Matrix
 176 {
 177     float e11, e12, e13;
 178     float e21, e22, e23;
 179     float e31, e32, e33;
 180 };
 181
 182
 183 /**
 184  * @class Paint
 185  *
 186  * @brief An abstract class for managing graphical elements.
 187  *
 188  * A graphical element in TVG is any object composed into a Canvas.
 189  * Paint represents such a graphical object and its behaviors such as duplication, transformation and composition.
 190  * TVG recommends the user to regard a paint as a set of volatile commands. They can prepare a Paint and then request a Canvas to run them.
 191  */
 192 class TVG_EXPORT Paint
 193 {
 194 public:
 195     virtual ~Paint();
 196
 197     /**
 198      * @brief Sets the angle by which the object is rotated.
 199      *
 200      * The angle in measured clockwise from the horizontal axis.
 201      * The rotational axis passes through the point on the object with zero coordinates.
 202      *
 203      * @param[in] degree The value of the angle in degrees.
 204      *
 205      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 206      */
 207     Result rotate(float degree) noexcept;
 208
 209     /**
 210      * @brief Sets the scale value of the object.
 211      *
 212      * @param[in] factor The value of the scaling factor. The default value is 1.
 213      *
 214      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 215      */
 216     Result scale(float factor) noexcept;
 217
 218     /**
 219      * @brief Sets the values by which the object is moved in a two-dimensional space.
 220      *
 221      * The origin of the coordinate system is in the upper left corner of the canvas.
 222      * The horizontal and vertical axes point to the right and down, respectively.
 223      *
 224      * @param[in] x The value of the horizontal shift.
 225      * @param[in] y The value of the vertical shift.
 226      *
 227      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 228      */
 229     Result translate(float x, float y) noexcept;
 230
 231     /**
 232      * @brief Sets the matrix of the affine transformation for the object.
 233      *
 234      * The augmented matrix of the transformation is expected to be given.
 235      *
 236      * @param[in] m The 3x3 augmented matrix.
 237      *
 238      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 239      */
 240     Result transform(const Matrix& m) noexcept;
 241
 242     /**
 243      * @brief Gets the matrix of the affine transformation of the object.
 244      *
 245      * The values of the matrix can be set by the transform() API, as well by the translate(),
 246      * scale() and rotate(). In case no transformation was applied, the identity matrix is returned.
 247      *
 248      * @retval The augmented transformation matrix.
 249      *
 250      * @BETA_API
 251      */
 252     Matrix transform() noexcept;
 253
 254     /**
 255      * @brief Sets the opacity of the object.
 256      *
 257      * @param[in] o The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
 258      *
 259      * @return Result::Success when succeed.
 260      *
 261      * @note Setting the opacity with this API may require multiple render pass for composition. It is recommended to avoid changing the opacity if possible.
 262      */
 263     Result opacity(uint8_t o) noexcept;
 264
 265     /**
 266      * @brief Sets the composition target object and the composition method.
 267      *
 268      * @param[in] target The paint of the target object.
 269      * @param[in] method The method used to composite the source object with the target.
 270      *
 271      * @return Result::Success when succeed, Result::InvalidArguments otherwise.
 272      */
 273     Result composite(std::unique_ptr<Paint> target, CompositeMethod method) noexcept;
 274
 275     /**
 276      * @brief Gets the bounding box of the paint object before any transformation.
 277      *
 278      * @param[out] x The x coordinate of the upper left corner of the object.
 279      * @param[out] y The y coordinate of the upper left corner of the object.
 280      * @param[out] w The width of the object.
 281      * @param[out] h The height of the object.
 282      *
 283      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 284      *
 285      * @note The bounding box doesn't indicate the final rendered region. It's the smallest rectangle that encloses the object.
 286      */
 287     Result bounds(float* x, float* y, float* w, float* h) const noexcept;
 288
 289     /**
 290      * @brief Duplicates the object.
 291      *
 292      * Creates a new object and sets its all properties as in the original object.
 293      *
 294      * @return The created object when succeed, @c nullptr otherwise.
 295      */
 296     Paint* duplicate() const noexcept;
 297
 298     /**
 299      * @brief Gets the opacity value of the object.
 300      *
 301      * @return The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
 302      */
 303     uint8_t opacity() const noexcept;
 304
 305     /**
 306      * @brief Gets the composition target object and the composition method.
 307      *
 308      * @param[out] target The paint of the target object.
 309      *
 310      * @return The method used to composite the source object with the target.
 311      *
 312      * @BETA_API
 313      */
 314     CompositeMethod composite(const Paint** target) const noexcept;
 315
 316     _TVG_DECLARE_ACCESSOR();
 317     _TVG_DECALRE_IDENTIFIER();
 318     _TVG_DECLARE_PRIVATE(Paint);
 319 };
 320
 321
 322 /**
 323  * @class Fill
 324  *
 325  * @brief An abstract class representing the gradient fill of the Shape object.
 326  *
 327  * It contains the information about the gradient colors and their arrangement
 328  * inside the gradient bounds. The gradients bounds are defined in the LinearGradient
 329  * or RadialGradient class, depending on the type of the gradient to be used.
 330  * It specifies the gradient behavior in case the area defined by the gradient bounds
 331  * is smaller than the area to be filled.
 332  */
 333 class TVG_EXPORT Fill
 334 {
 335 public:
 336     /**
 337      * @brief A data structure storing the information about the color and its relative position inside the gradient bounds.
 338      */
 339     struct ColorStop
 340     {
 341         float offset; /**< The relative position of the color. */
 342         uint8_t r;    /**< The red color channel value in the range [0 ~ 255]. */
 343         uint8_t g;    /**< The green color channel value in the range [0 ~ 255]. */
 344         uint8_t b;    /**< The blue color channel value in the range [0 ~ 255]. */
 345         uint8_t a;    /**< The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. */
 346     };
 347
 348     virtual ~Fill();
 349
 350     /**
 351      * @brief Sets the parameters of the colors of the gradient and their position.
 352      *
 353      * @param[in] colorStops An array of ColorStop data structure.
 354      * @param[in] cnt The count of the @p colorStops array equal to the colors number used in the gradient.
 355      *
 356      * @return Result::Success when succeed.
 357      */
 358     Result colorStops(const ColorStop* colorStops, uint32_t cnt) noexcept;
 359
 360     /**
 361      * @brief Sets the FillSpread value, which specifies how to fill the area outside the gradient bounds.
 362      *
 363      * @param[in] s The FillSpread value.
 364      *
 365      * @return Result::Success when succeed.
 366      */
 367     Result spread(FillSpread s) noexcept;
 368
 369     /**
 370      * @brief Gets the parameters of the colors of the gradient, their position and number.
 371      *
 372      * @param[in] colorStops A pointer to the memory location, where the array of the gradient's ColorStop is stored.
 373      *
 374      * @return The number of colors used in the gradient. This value corresponds to the length of the @p colorStops array.
 375      */
 376     uint32_t colorStops(const ColorStop** colorStops) const noexcept;
 377
 378     /**
 379      * @brief Gets the FillSpread value of the fill.
 380      *
 381      * @return The FillSpread value of this Fill.
 382      */
 383     FillSpread spread() const noexcept;
 384
 385     /**
 386      * @brief Creates a copy of the Fill object.
 387      *
 388      * Return a newly created Fill object with the properties copied from the original.
 389      *
 390      * @return A copied Fill object when succeed, @c nullptr otherwise.
 391      */
 392     Fill* duplicate() const noexcept;
 393
 394     _TVG_DECALRE_IDENTIFIER();
 395     _TVG_DECLARE_PRIVATE(Fill);
 396 };
 397
 398
 399 /**
 400  * @class Canvas
 401  *
 402  * @brief An abstract class for drawing graphical elements.
 403  *
 404  * A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.
 405  *
 406  * @note A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.
 407  * @warning The Paint objects belonging to one Canvas can't be shared among multiple Canvases.
 408  */
 409 class TVG_EXPORT Canvas
 410 {
 411 public:
 412     Canvas(RenderMethod*);
 413     virtual ~Canvas();
 414
 415     /**
 416      * @brief Sets the size of the container, where all the paints pushed into the Canvas are stored.
 417      *
 418      * If the number of objects pushed into the Canvas is known in advance, calling the function
 419      * prevents multiple memory reallocation, thus improving the performance.
 420      *
 421      * @param[in] n The number of objects for which the memory is to be reserved.
 422      *
 423      * @return Result::Success when succeed.
 424      */
 425     Result reserve(uint32_t n) noexcept;
 426
 427     /**
 428      * @brief Passes drawing elements to the Canvas using Paint objects.
 429      *
 430      * Only pushed paints in the canvas will be drawing targets.
 431      * They are retained by the canvas until you call Canvas::clear().
 432      * If you know the number of the pushed objects in the advance, please call Canvas::reserve().
 433      *
 434      * @param[in] paint A Paint object to be drawn.
 435      *
 436      * @retval Result::Success When succeed.
 437      * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument.
 438      * @retval Result::InsufficientCondition An internal error.
 439      *
 440      * @note The rendering order of the paints is the same as the order as they were pushed into the canvas. Consider sorting the paints before pushing them if you intend to use layering.
 441      * @see Canvas::reserve()
 442      * @see Canvas::clear()
 443      */
 444     virtual Result push(std::unique_ptr<Paint> paint) noexcept;
 445
 446     /**
 447      * @brief Sets the total number of the paints pushed into the canvas to be zero.
 448      * Depending on the value of the @p free argument, the paints are freed or not.
 449      *
 450      * @param[in] free If @c true, the memory occupied by paints is deallocated, otherwise it is not.
 451      *
 452      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 453      *
 454      * @warning If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the @p free argument only when you know how it works, otherwise it's not recommended.
 455      */
 456     virtual Result clear(bool free = true) noexcept;
 457
 458     /**
 459      * @brief Request the canvas to update the paint objects.
 460      *
 461      * If a @c nullptr is passed all paint objects retained by the Canvas are updated,
 462      * otherwise only the paint to which the given @p paint points.
 463      *
 464      * @param[in] paint A pointer to the Paint object or @c nullptr.
 465      *
 466      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 467      *
 468      * @note The Update behavior can be asynchronous if the assigned thread number is greater than zero.
 469      */
 470     virtual Result update(Paint* paint) noexcept;
 471
 472     /**
 473      * @brief Request the canvas to draw the Paint objects.
 474      *
 475      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 476      *
 477      * @note Drawing can be asynchronous if the assigned thread number is greater than zero. To guarantee the drawing is done, call sync() afterwards.
 478      * @see Canvas::sync()
 479      */
 480     virtual Result draw() noexcept;
 481
 482     /**
 483      * @brief Guarantees that drawing task is finished.
 484      *
 485      * The Canvas rendering can be performed asynchronously. To make sure that rendering is finished,
 486      * the sync() must be called after the draw() regardless of threading.
 487      *
 488      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 489      * @see Canvas::draw()
 490      */
 491     virtual Result sync() noexcept;
 492
 493     _TVG_DECLARE_PRIVATE(Canvas);
 494 };
 495
 496
 497 /**
 498  * @class LinearGradient
 499  *
 500  * @brief A class representing the linear gradient fill of the Shape object.
 501  *
 502  * Besides the APIs inherited from the Fill class, it enables setting and getting the linear gradient bounds.
 503  * The behavior outside the gradient bounds depends on the value specified in the spread API.
 504  */
 505 class TVG_EXPORT LinearGradient final : public Fill
 506 {
 507 public:
 508     ~LinearGradient();
 509
 510     /**
 511      * @brief Sets the linear gradient bounds.
 512      *
 513      * The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing
 514      * the given points (@p x1, @p y1) and (@p x2, @p y2), respectively. Both lines are perpendicular to the line linking
 515      * (@p x1, @p y1) and (@p x2, @p y2).
 516      *
 517      * @param[in] x1 The horizontal coordinate of the first point used to determine the gradient bounds.
 518      * @param[in] y1 The vertical coordinate of the first point used to determine the gradient bounds.
 519      * @param[in] x2 The horizontal coordinate of the second point used to determine the gradient bounds.
 520      * @param[in] y2 The vertical coordinate of the second point used to determine the gradient bounds.
 521      *
 522      * @return Result::Success when succeed, Result::InvalidArguments otherwise.
 523      */
 524     Result linear(float x1, float y1, float x2, float y2) noexcept;
 525
 526     /**
 527      * @brief Gets the linear gradient bounds.
 528      *
 529      * The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing
 530      * the given points (@p x1, @p y1) and (@p x2, @p y2), respectively. Both lines are perpendicular to the line linking
 531      * (@p x1, @p y1) and (@p x2, @p y2).
 532      *
 533      * @param[out] x1 The horizontal coordinate of the first point used to determine the gradient bounds.
 534      * @param[out] y1 The vertical coordinate of the first point used to determine the gradient bounds.
 535      * @param[out] x2 The horizontal coordinate of the second point used to determine the gradient bounds.
 536      * @param[out] y2 The vertical coordinate of the second point used to determine the gradient bounds.
 537      *
 538      * @return Result::Success when succeed.
 539      */
 540     Result linear(float* x1, float* y1, float* x2, float* y2) const noexcept;
 541
 542     /**
 543      * @brief Creates a new LinearGradient object.
 544      *
 545      * @return A new LinearGradient object.
 546      */
 547     static std::unique_ptr<LinearGradient> gen() noexcept;
 548
 549     _TVG_DECLARE_PRIVATE(LinearGradient);
 550 };
 551
 552
 553 /**
 554  * @class RadialGradient
 555  *
 556  * @brief A class representing the radial gradient fill of the Shape object.
 557  *
 558  */
 559 class TVG_EXPORT RadialGradient final : public Fill
 560 {
 561 public:
 562     ~RadialGradient();
 563
 564     /**
 565      * @brief Sets the radial gradient bounds.
 566      *
 567      * The radial gradient bounds are defined as a circle centered in a given point (@p cx, @p cy) of a given radius.
 568      *
 569      * @param[in] cx The horizontal coordinate of the center of the bounding circle.
 570      * @param[in] cy The vertical coordinate of the center of the bounding circle.
 571      * @param[in] radius The radius of the bounding circle.
 572      *
 573      * @return Result::Success when succeed, Result::InvalidArguments otherwise.
 574      */
 575     Result radial(float cx, float cy, float radius) noexcept;
 576
 577     /**
 578      * @brief Gets the radial gradient bounds.
 579      *
 580      * The radial gradient bounds are defined as a circle centered in a given point (@p cx, @p cy) of a given radius.
 581      *
 582      * @param[out] cx The horizontal coordinate of the center of the bounding circle.
 583      * @param[out] cy The vertical coordinate of the center of the bounding circle.
 584      * @param[out] radius The radius of the bounding circle.
 585      *
 586      * @return Result::Success when succeed.
 587      */
 588     Result radial(float* cx, float* cy, float* radius) const noexcept;
 589
 590     /**
 591      * @brief Creates a new RadialGradient object.
 592      *
 593      * @return A new RadialGradient object.
 594      */
 595     static std::unique_ptr<RadialGradient> gen() noexcept;
 596
 597     _TVG_DECLARE_PRIVATE(RadialGradient);
 598 };
 599
 600
 601 /**
 602  * @class Shape
 603  *
 604  * @brief A class representing two-dimensional figures and their properties.
 605  *
 606  * A shape has three major properties: shape outline, stroking, filling. The outline in the Shape is retained as the path.
 607  * Path can be composed by accumulating primitive commands such as moveTo(), lineTo(), cubicTo(), or complete shape interfaces such as appendRect(), appendCircle(), etc.
 608  * Path can consists of sub-paths. One sub-path is determined by a close command.
 609  *
 610  * The stroke of Shape is an optional property in case the Shape needs to be represented with/without the outline borders.
 611  * It's efficient since the shape path and the stroking path can be shared with each other. It's also convenient when controlling both in one context.
 612  */
 613 class TVG_EXPORT Shape final : public Paint
 614 {
 615 public:
 616     ~Shape();
 617
 618     /**
 619      * @brief Resets the properties of the shape path.
 620      *
 621      * The color, the fill and the stroke properties are retained.
 622      *
 623      * @return Result::Success when succeed.
 624      *
 625      * @note The memory, where the path data is stored, is not deallocated at this stage for caching effect.
 626      */
 627     Result reset() noexcept;
 628
 629     /**
 630      * @brief Sets the initial point of the sub-path.
 631      *
 632      * The value of the current point is set to the given point.
 633      *
 634      * @param[in] x The horizontal coordinate of the initial point of the sub-path.
 635      * @param[in] y The vertical coordinate of the initial point of the sub-path.
 636      *
 637      * @return Result::Success when succeed.
 638      */
 639     Result moveTo(float x, float y) noexcept;
 640
 641     /**
 642      * @brief Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point.
 643      *
 644      * The value of the current point is set to the given end-point.
 645      *
 646      * @param[in] x The horizontal coordinate of the end-point of the line.
 647      * @param[in] y The vertical coordinate of the end-point of the line.
 648      *
 649      * @return Result::Success when succeed.
 650      *
 651      * @note In case this is the first command in the path, it corresponds to the moveTo() call.
 652      */
 653     Result lineTo(float x, float y) noexcept;
 654
 655     /**
 656      * @brief Adds new points to the sub-path, which results in drawing a cubic Bezier curve starting
 657      * at the current point and ending at the given end-point (@p x, @p y) using the control points (@p cx1, @p cy1) and (@p cx2, @p cy2).
 658      *
 659      * The value of the current point is set to the given end-point.
 660      *
 661      * @param[in] cx1 The horizontal coordinate of the 1st control point.
 662      * @param[in] cy1 The vertical coordinate of the 1st control point.
 663      * @param[in] cx2 The horizontal coordinate of the 2nd control point.
 664      * @param[in] cy2 The vertical coordinate of the 2nd control point.
 665      * @param[in] x The horizontal coordinate of the end-point of the curve.
 666      * @param[in] y The vertical coordinate of the end-point of the curve.
 667      *
 668      * @return Result::Success when succeed.
 669      *
 670      * @note In case this is the first command in the path, no data from the path are rendered.
 671      */
 672     Result cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) noexcept;
 673
 674     /**
 675      * @brief Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path.
 676      *
 677      * The value of the current point is set to the initial point of the closed sub-path.
 678      *
 679      * @return Result::Success when succeed.
 680      *
 681      * @note In case the sub-path does not contain any points, this function has no effect.
 682      */
 683     Result close() noexcept;
 684
 685     /**
 686      * @brief Appends a rectangle to the path.
 687      *
 688      * The rectangle with rounded corners can be achieved by setting non-zero values to @p rx and @p ry arguments.
 689      * The @p rx and @p ry values specify the radii of the ellipse defining the rounding of the corners.
 690      *
 691      * The position of the rectangle is specified by the coordinates of its upper left corner - @p x and @p y arguments.
 692      *
 693      * The rectangle is treated as a new sub-path - it is not connected with the previous sub-path.
 694      *
 695      * The value of the current point is set to (@p x + @p rx, @p y) - in case @p rx is greater
 696      * than @p w/2 the current point is set to (@p x + @p w/2, @p y)
 697      *
 698      * @param[in] x The horizontal coordinate of the upper left corner of the rectangle.
 699      * @param[in] y The vertical coordinate of the upper left corner of the rectangle.
 700      * @param[in] w The width of the rectangle.
 701      * @param[in] h The height of the rectangle.
 702      * @param[in] rx The x-axis radius of the ellipse defining the rounded corners of the rectangle.
 703      * @param[in] ry The y-axis radius of the ellipse defining the rounded corners of the rectangle.
 704      *
 705      * @return Result::Success when succeed.
 706      *
 707      * @note For @p rx and @p ry greater than or equal to the half of @p w and the half of @p h, respectively, the shape become an ellipse.
 708      */
 709     Result appendRect(float x, float y, float w, float h, float rx, float ry) noexcept;
 710
 711     /**
 712      * @brief Appends an ellipse to the path.
 713      *
 714      * The position of the ellipse is specified by the coordinates of its center - @p cx and @p cy arguments.
 715      *
 716      * The ellipse is treated as a new sub-path - it is not connected with the previous sub-path.
 717      *
 718      * The value of the current point is set to (@p cx, @p cy - @p ry).
 719      *
 720      * @param[in] cx The horizontal coordinate of the center of the ellipse.
 721      * @param[in] cy The vertical coordinate of the center of the ellipse.
 722      * @param[in] rx The x-axis radius of the ellipse.
 723      * @param[in] ry The y-axis radius of the ellipse.
 724      *
 725      * @return Result::Success when succeed.
 726      */
 727     Result appendCircle(float cx, float cy, float rx, float ry) noexcept;
 728
 729     /**
 730      * @brief Appends a circular arc to the path.
 731      *
 732      * The arc is treated as a new sub-path - it is not connected with the previous sub-path.
 733      * The current point value is set to the end-point of the arc in case @p pie is @c false, and to the center of the arc otherwise.
 734      *
 735      * @param[in] cx The horizontal coordinate of the center of the arc.
 736      * @param[in] cy The vertical coordinate of the center of the arc.
 737      * @param[in] radius The radius of the arc.
 738      * @param[in] startAngle The start angle of the arc given in degrees, measured counter-clockwise from the horizontal line.
 739      * @param[in] sweep The central angle of the arc given in degrees, measured counter-clockwise from @p startAngle.
 740      * @param[in] pie Specifies whether to draw radii from the arc's center to both of its end-point - drawn if @c true.
 741      *
 742      * @return Result::Success when succeed.
 743      *
 744      * @note Setting @p sweep value greater than 360 degrees, is equivalent to calling appendCircle(cx, cy, radius, radius).
 745      */
 746     Result appendArc(float cx, float cy, float radius, float startAngle, float sweep, bool pie) noexcept;
 747
 748     /**
 749      * @brief Appends a given sub-path to the path.
 750      *
 751      * The current point value is set to the last point from the sub-path.
 752      * For each command from the @p cmds array, an appropriate number of points in @p pts array should be specified.
 753      *
 754      * @param[in] cmds The array of the commands in the sub-path.
 755      * @param[in] cmdCnt The number of the sub-path's commands.
 756      * @param[in] pts The array of the two-dimensional points.
 757      * @param[in] ptsCnt The number of the points in the @p pts array.
 758      *
 759      * @return Result::Success when succeed, Result::InvalidArguments otherwise.
 760      *
 761      * @note The interface is designed for optimal path setting if the caller has a completed path commands already.
 762      */
 763     Result appendPath(const PathCommand* cmds, uint32_t cmdCnt, const Point* pts, uint32_t ptsCnt) noexcept;
 764
 765     /**
 766      * @brief Sets the stroke width for all of the figures from the path.
 767      *
 768      * @param[in] width The width of the stroke. The default value is 0.
 769      *
 770      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 771      */
 772     Result stroke(float width) noexcept;
 773
 774     /**
 775      * @brief Sets the color of the stroke for all of the figures from the path.
 776      *
 777      * @param[in] r The red color channel value in the range [0 ~ 255]. The default value is 0.
 778      * @param[in] g The green color channel value in the range [0 ~ 255]. The default value is 0.
 779      * @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0.
 780      * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.
 781      *
 782      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 783      */
 784     Result stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
 785
 786     /**
 787      * @brief Sets the gradient fill of the stroke for all of the figures from the path.
 788      *
 789      * @param[in] f The gradient fill.
 790      *
 791      * @retval Result::Success When succeed.
 792      * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be filled.
 793      * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument.
 794      */
 795     Result stroke(std::unique_ptr<Fill> f) noexcept;
 796
 797     /**
 798      * @brief Sets the dash pattern of the stroke.
 799      *
 800      * @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length.
 801      * @param[in] cnt The length of the @p dashPattern array.
 802      *
 803      * @retval Result::Success When succeed.
 804      * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be dashed.
 805      * @retval Result::InvalidArguments In case that either @p dashPattern is @c nullptr or @p cnt is zero.
 806      *
 807      * @note If any of the dash pattern values is zero, this function has no effect.
 808      * @note To reset the stroke dash pattern, pass @c nullptr to @p dashPattern and zero to @p cnt.
 809      * @warning @p cnt must be greater than 1 if the dash pattern is valid.
 810      */
 811     Result stroke(const float* dashPattern, uint32_t cnt) noexcept;
 812
 813     /**
 814      * @brief Sets the cap style of the stroke in the open sub-paths.
 815      *
 816      * @param[in] cap The cap style value. The default value is @c StrokeCap::Square.
 817      *
 818      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 819      */
 820     Result stroke(StrokeCap cap) noexcept;
 821
 822     /**
 823      * @brief Sets the join style for stroked path segments.
 824      *
 825      * The join style is used for joining the two line segment while stroking the path.
 826      *
 827      * @param[in] join The join style value. The default value is @c StrokeJoin::Bevel.
 828      *
 829      * @return Result::Success when succeed, Result::FailedAllocation otherwise.
 830      */
 831     Result stroke(StrokeJoin join) noexcept;
 832
 833     /**
 834      * @brief Sets the solid color for all of the figures from the path.
 835      *
 836      * The parts of the shape defined as inner are colored.
 837      *
 838      * @param[in] r The red color channel value in the range [0 ~ 255]. The default value is 0.
 839      * @param[in] g The green color channel value in the range [0 ~ 255]. The default value is 0.
 840      * @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0.
 841      * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.
 842      *
 843      * @return Result::Success when succeed.
 844      *
 845      * @note Either a solid color or a gradient fill is applied, depending on what was set as last.
 846      */
 847     Result fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
 848
 849     /**
 850      * @brief Sets the gradient fill for all of the figures from the path.
 851      *
 852      * The parts of the shape defined as inner are filled.
 853      *
 854      * @param[in] f The unique pointer to the gradient fill.
 855      *
 856      * @return Result::Success when succeed, Result::MemoryCorruption otherwise.
 857      *
 858      * @note Either a solid color or a gradient fill is applied, depending on what was set as last.
 859      */
 860     Result fill(std::unique_ptr<Fill> f) noexcept;
 861
 862     /**
 863      * @brief Sets the fill rule for the Shape object.
 864      *
 865      * @param[in] r The fill rule value.
 866      *
 867      * @return Result::Success when succeed.
 868      */
 869     Result fill(FillRule r) noexcept;
 870
 871     /**
 872      * @brief Gets the commands data of the path.
 873      *
 874      * @param[out] cmds The pointer to the array of the commands from the path.
 875      *
 876      * @return The length of the @p cmds array when succeed, zero otherwise.
 877      */
 878     uint32_t pathCommands(const PathCommand** cmds) const noexcept;
 879
 880     /**
 881      * @brief Gets the points values of the path.
 882      *
 883      * @param[out] pts The pointer to the array of the two-dimensional points from the path.
 884      *
 885      * @return The length of the @p pts array when succeed, zero otherwise.
 886      */
 887     uint32_t pathCoords(const Point** pts) const noexcept;
 888
 889     /**
 890      * @brief Gets the pointer to the gradient fill of the shape.
 891      *
 892      * @return The pointer to the gradient fill of the stroke when succeed, @c nullptr in case no fill was set.
 893      */
 894     const Fill* fill() const noexcept;
 895
 896     /**
 897      * @brief Gets the solid color of the shape.
 898      *
 899      * @param[out] r The red color channel value in the range [0 ~ 255].
 900      * @param[out] g The green color channel value in the range [0 ~ 255].
 901      * @param[out] b The blue color channel value in the range [0 ~ 255].
 902      * @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
 903      *
 904      * @return Result::Success when succeed.
 905      */
 906     Result fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept;
 907
 908     /**
 909      * @brief Gets the fill rule value.
 910      *
 911      * @return The fill rule value of the shape.
 912      */
 913     FillRule fillRule() const noexcept;
 914
 915     /**
 916      * @brief Gets the stroke width.
 917      *
 918      * @return The stroke width value when succeed, zero if no stroke was set.
 919      */
 920     float strokeWidth() const noexcept;
 921
 922     /**
 923      * @brief Gets the color of the shape's stroke.
 924      *
 925      * @param[out] r The red color channel value in the range [0 ~ 255].
 926      * @param[out] g The green color channel value in the range [0 ~ 255].
 927      * @param[out] b The blue color channel value in the range [0 ~ 255].
 928      * @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
 929      *
 930      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
 931      */
 932     Result strokeColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept;
 933
 934     /**
 935      * @brief Gets the pointer to the gradient fill of the stroke.
 936      *
 937      * @return The pointer to the gradient fill of the stroke when succeed, @c nullptr otherwise.
 938      */
 939     const Fill* strokeFill() const noexcept;
 940
 941     /**
 942      * @brief Gets the dash pattern of the stroke.
 943      *
 944      * @param[out] dashPattern The pointer to the memory, where the dash pattern array is stored.
 945      *
 946      * @return The length of the @p dashPattern array.
 947      */
 948     uint32_t strokeDash(const float** dashPattern) const noexcept;
 949
 950     /**
 951      * @brief Gets the cap style used for stroking the path.
 952      *
 953      * @return The cap style value of the stroke.
 954      */
 955     StrokeCap strokeCap() const noexcept;
 956
 957     /**
 958      * @brief Gets the join style value used for stroking the path.
 959      *
 960      * @return The join style value of the stroke.
 961      */
 962     StrokeJoin strokeJoin() const noexcept;
 963
 964     /**
 965      * @brief Creates a new Shape object.
 966      *
 967      * @return A new Shape object.
 968      */
 969     static std::unique_ptr<Shape> gen() noexcept;
 970
 971     _TVG_DECLARE_PRIVATE(Shape);
 972 };
 973
 974
 975 /**
 976  * @class Picture
 977  *
 978  * @brief A class representing an image read in one of the supported formats: raw, svg, png and etc.
 979  * Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas.
 980  *
 981  * @note Supported formats are depended on the available TVG loaders.
 982  */
 983 class TVG_EXPORT Picture final : public Paint
 984 {
 985 public:
 986     ~Picture();
 987
 988     /**
 989      * @brief Loads a picture data directly from a file.
 990      *
 991      * @param[in] path A path to the picture file.
 992      *
 993      * @retval Result::Success When succeed.
 994      * @retval Result::InvalidArguments In case the @p path is invalid.
 995      * @retval Result::NonSupport When trying to load a file with an unknown extension.
 996      * @retval Result::Unknown If an error occurs at a later stage.
 997      *
 998      * @note The Load behavior can be asynchronous if the assigned thread number is greater than zero.
 999      * @see Initializer::init()
1000      */
1001     Result load(const std::string& path) noexcept;
1002
1003     /**
1004      * @brief Loads a picture data from a memory block of a given size.
1005      *
1006      * @param[in] data A pointer to a memory location where the content of the picture file is stored.
1007      * @param[in] size The size in bytes of the memory occupied by the @p data.
1008      * @param[in] copy Decides whether the data should be copied into the engine local buffer.
1009      *
1010      * @retval Result::Success When succeed.
1011      * @retval Result::InvalidArguments In case no data are provided or the @p size is zero or less.
1012      * @retval Result::NonSupport When trying to load a file with an unknown extension.
1013      * @retval Result::Unknown If an error occurs at a later stage.
1014      *
1015      * @note: This api supports only SVG format
1016      *
1017      * @warning: you have responsibility to release the @p data memory if the @p copy is true
1018      */
1019     Result load(const char* data, uint32_t size, bool copy) noexcept;
1020     Result load(const char* data, uint32_t size) noexcept;
1021
1022     /**
1023      * @brief Resize the picture content with the given width and height.
1024      *
1025      * Resize the picture content while keeping the default size aspect ratio.
1026      * The scaling factor is established for each of dimensions and the smaller value is applied to both of them.
1027      *
1028      * @param[in] w A new width of the image in pixels.
1029      * @param[in] h A new height of the image in pixels.
1030      *
1031      * @return Result::Success when succeed, Result::InsufficientCondition otherwise.
1032      */
1033     Result size(float w, float h) noexcept;
1034
1035     /**
1036      * @brief Gets the size of the image.
1037      *
1038      * @param[out] w The width of the image in pixels.
1039      * @param[out] h The height of the image in pixels.
1040      *
1041      * @return Result::Success when succeed.
1042      */
1043     Result size(float* w, float* h) const noexcept;
1044
1045     /**
1046      * @brief Gets the pixels information of the picture.
1047      *
1048      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1049      *
1050      * @BETA_API
1051      */
1052     const uint32_t* data() const noexcept;
1053
1054     /**
1055      * @brief Set paint for the picture.
1056      *
1057      * @param[in] paint A Paint object to be drawn.
1058      *
1059      * @return Result::Success when succeed.
1060      * @return Result::InsufficientCondition if paint already set.
1061      * @return Result::MemoryCorruption when bad memory handling.
1062      *
1063      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1064      *
1065      * @BETA_API
1066      */
1067     Result paint(std::unique_ptr<Paint> paint) noexcept;
1068
1069     /**
1070      * @brief Loads a raw data from a memory block with a given size.
1071      *
1072      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1073      *
1074      * @BETA_API
1075      */
1076     Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept;
1077
1078     /**
1079      * @brief Gets the position and the size of the loaded picture.
1080      *
1081      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1082      *
1083      * @BETA_API
1084      */
1085     Result viewbox(float* x, float* y, float* w, float* h) const noexcept;
1086
1087     /**
1088      * @brief Creates a new Picture object.
1089      *
1090      * @return A new Picture object.
1091      */
1092     static std::unique_ptr<Picture> gen() noexcept;
1093
1094     _TVG_DECLARE_PRIVATE(Picture);
1095 };
1096
1097
1098 /**
1099  * @class Scene
1100  *
1101  * @brief A class to composite children paints.
1102  *
1103  * As the traditional graphics rendering method, TVG also enables scene-graph mechanism.
1104  * This feature supports an array function for managing the multiple paints as one group paint.
1105  *
1106  * As a group, the scene can be transformed, made translucent and composited with other target paints,
1107  * its children will be affected by the scene world.
1108  */
1109 class TVG_EXPORT Scene final : public Paint
1110 {
1111 public:
1112     ~Scene();
1113
1114     /**
1115      * @brief Passes drawing elements to the Scene using Paint objects.
1116      *
1117      * Only pushed paints in the scene will be drawing targets.
1118      * They are retained by the scene until you call Scene::clear().
1119      * If you know the number of the pushed objects in the advance, please call Scene::reserve().
1120      *
1121      * @param[in] paint A Paint object to be drawn.
1122      *
1123      * @return Result::Success when succeed, Result::MemoryCorruption otherwise.
1124      *
1125      * @note The rendering order of the paints is the same as the order as they were pushed. Consider sorting the paints before pushing them if you intend to use layering.
1126      * @see Scene::reserve()
1127      */
1128     Result push(std::unique_ptr<Paint> paint) noexcept;
1129
1130     /**
1131      * @brief Sets the size of the container, where all the paints pushed into the Scene are stored.
1132      *
1133      * If the number of objects pushed into the scene is known in advance, calling the function
1134      * prevents multiple memory reallocation, thus improving the performance.
1135      *
1136      * @param[in] size The number of objects for which the memory is to be reserved.
1137      *
1138      * @return Result::Success when succeed.
1139      */
1140     Result reserve(uint32_t size) noexcept;
1141
1142     /**
1143      * @brief Sets the total number of the paints pushed into the scene to be zero.
1144      * Depending on the value of the @p free argument, the paints are freed or not.
1145      *
1146      * @param[in] free If @c true, the memory occupied by paints is deallocated, otherwise it is not.
1147      *
1148      * @return Result::Success when succeed
1149      *
1150      * @warning If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the @p free argument only when you know how it works, otherwise it's not recommended.
1151      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1152      *
1153      * @since 0.2
1154      */
1155     Result clear(bool free = true) noexcept;
1156
1157     /**
1158      * @brief Creates a new Scene object.
1159      *
1160      * @return A new Scene object.
1161      */
1162     static std::unique_ptr<Scene> gen() noexcept;
1163
1164     _TVG_DECLARE_PRIVATE(Scene);
1165 };
1166
1167
1168 /**
1169  * @class SwCanvas
1170  *
1171  * @brief A class for the rendering graphical elements with a software raster engine.
1172  */
1173 class TVG_EXPORT SwCanvas final : public Canvas
1174 {
1175 public:
1176     ~SwCanvas();
1177
1178     /**
1179      * @brief Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.
1180      */
1181     enum Colorspace
1182     {
1183         ABGR8888 = 0, ///< The channels are joined in the order: alpha, blue, green, red.
1184         ARGB8888      ///< The channels are joined in the order: alpha, red, green, blue.
1185     };
1186
1187     /**
1188      * @brief Enumeration specifying the methods of Memory Pool behavior policy.
1189      *
1190      * @BETA_API
1191      */
1192     enum MempoolPolicy
1193     {
1194         Default = 0, ///< Default behavior that ThorVG is designed to.
1195         Shareable,   ///< Memory Pool is shared among the SwCanvases.
1196         Individual   ///< Allocate designated memory pool that is only used by current instance.
1197     };
1198
1199     /**
1200      * @brief Sets the target buffer for the rasterization.
1201      *
1202      * The buffer of a desirable size should be allocated and owned by the caller.
1203      *
1204      * @param[in] buffer A pointer to a memory block of the size @p stride x @p h, where the raster data are stored.
1205      * @param[in] stride The stride of the raster image - greater than or equal to @p w.
1206      * @param[in] w The width of the raster image.
1207      * @param[in] h The height of the raster image.
1208      * @param[in] cs The value specifying the way the 32-bits colors should be read/written.
1209      *
1210      * @retval Result::Success When succeed.
1211      * @retval Result::MemoryCorruption When casting in the internal function implementation failed.
1212      * @retval Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero.
1213      * @retval Result::NonSupport In case the software engine is not supported.
1214      *
1215      * @warning Do not access @p buffer during Canvas::draw() - Canvas::sync(). It should not be accessed while TVG is writing on it.
1216     */
1217     Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept;
1218
1219     /**
1220      * @brief Set sw engine memory pool behavior policy.
1221      *
1222      * Basically ThorVG draws a lot of shapes, it allocates/deallocates a few chunk of memory
1223      * while processing rendering. It internally uses one shared memory pool
1224      * which can be reused among the canvases in order to avoid memory overhead.
1225      *
1226      * Thus ThorVG suggests memory pool policy to satisfy user demands,
1227      * if it needs to guarantee the thread-safety of the internal data access.
1228      *
1229      * @param[in] policy Use the shared cache memory. The default value is @c true
1230      *
1231      * @retval Result::Success When succeed.
1232      * @retval Result::InsufficientCondition If the canvas has any paints.
1233      * @retval Result::NonSupport In case the software engine is not supported.
1234      *
1235      * @note When @c policy is set as @c MempoolPolicy::Individual, current instance of canvas uses its own individual
1236      *       memory data that is not shared with others. This is necessary when the canvas is accessed on a worker-thread.
1237      *
1238      * @warning It's not allowed after pushing any paints.
1239      *
1240      * @BETA_API
1241     */
1242     Result mempool(MempoolPolicy policy) noexcept;
1243
1244     /**
1245      * @brief Creates a new SwCanvas object.
1246      * @return A new SwCanvas object.
1247      */
1248     static std::unique_ptr<SwCanvas> gen() noexcept;
1249
1250     _TVG_DECLARE_PRIVATE(SwCanvas);
1251 };
1252
1253
1254 /**
1255  * @class GlCanvas
1256  *
1257  * @brief A class for the rendering graphic elements with a GL raster engine.
1258  *
1259  * @warning Please do not use it. This class is not fully supported yet.
1260  *
1261  * @BETA_API
1262  */
1263 class TVG_EXPORT GlCanvas final : public Canvas
1264 {
1265 public:
1266     ~GlCanvas();
1267
1268     /**
1269      * @brief Sets the target buffer for the rasterization.
1270      *
1271      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
1272      *
1273      * @BETA_API
1274      */
1275     Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h) noexcept;
1276
1277     /**
1278      * @brief Creates a new GlCanvas object.
1279      *
1280      * @return A new GlCanvas object.
1281      *
1282      * @BETA_API
1283      */
1284     static std::unique_ptr<GlCanvas> gen() noexcept;
1285
1286     _TVG_DECLARE_PRIVATE(GlCanvas);
1287 };
1288
1289
1290 /**
1291  * @class Initializer
1292  *
1293  * @brief A class that enables initialization and termination of the TVG engines.
1294  */
1295 class TVG_EXPORT Initializer final
1296 {
1297 public:
1298     /**
1299      * @brief Initializes TVG engines.
1300      *
1301      * TVG requires the running-engine environment.
1302      * TVG runs its own task-scheduler for parallelizing rendering tasks efficiently.
1303      * You can indicate the number of threads, the count of which is designated @p threads.
1304      * In the initialization step, TVG will generate/spawn the threads as set by @p threads count.
1305      *
1306      * @param[in] engine The engine types to initialize. This is relative to the Canvas types, in which it will be used. For multiple backeneds bitwise operation is allowed.
1307      * @param[in] threads The number of additional threads. Zero indicates only the main thread is to be used.
1308      *
1309      * @retval Result::Success When succeed.
1310      * @retval Result::FailedAllocation An internal error possibly with memory allocation.
1311      * @retval Result::InvalidArguments If unknown engine type chosen.
1312      * @retval Result::NonSupport In case the engine type is not supported on the system.
1313      * @retval Result::Unknown Others.
1314      *
1315      * @note The Initializer keeps track of the number of times it was called. Threads count is fixed at the first init() call.
1316      * @see Initializer::term()
1317      */
1318     static Result init(CanvasEngine engine, uint32_t threads) noexcept;
1319
1320     /**
1321      * @brief Terminates TVG engines.
1322      *
1323      * @param[in] engine The engine types to terminate. This is relative to the Canvas types, in which it will be used. For multiple backeneds bitwise operation is allowed
1324      *
1325      * @retval Result::Success When succeed.
1326      * @retval Result::InsufficientCondition In case there is nothing to be terminated.
1327      * @retval Result::InvalidArguments If unknown engine type chosen.
1328      * @retval Result::NonSupport In case the engine type is not supported on the system.
1329      * @retval Result::Unknown Others.
1330      *
1331      * @note Initializer does own reference counting for multiple calls.
1332      * @see Initializer::init()
1333      */
1334     static Result term(CanvasEngine engine) noexcept;
1335
1336     _TVG_DISABLE_CTOR(Initializer);
1337 };
1338
1339
1340 /**
1341  * @class Saver
1342  *
1343  * @brief A class enabling saving a paint in a binary format.
1344  *
1345  * @BETA_API
1346  */
1347 class TVG_EXPORT Saver
1348 {
1349 public:
1350     ~Saver();
1351
1352     /**
1353      * @brief Saves all the paints from the tree in a binary format.
1354      *
1355      * @param[in] paint The root paint to be saved with all its nodes.
1356      * @param[in] path A path to the file, in which the data is to be saved.
1357      *
1358      * @retval Result::Success When succeed.
1359      * @retval Result::InvalidArguments the @p path is invalid.
1360      * @retval Result::FailedAllocation An internal error with a memory allocation for the Saver object.
1361      * @retval Result::MemoryCorruption When casting in the internal function implementation failed.
1362      * @retval Result::Unknown Others.
1363      *
1364      */
1365     Result save(std::unique_ptr<Paint> paint, const std::string& path) noexcept;
1366     Result sync() noexcept;
1367
1368     static std::unique_ptr<Saver> gen() noexcept;
1369
1370     _TVG_DECLARE_PRIVATE(Saver);
1371 };
1372
1373
1374 /** @}*/
1375
1376 } //namespace
1377
1378 #ifdef __cplusplus
1379 }
1380 #endif
1381
1382 #endif //_THORVG_H_