SwCanvasfinal
ThorVG

A class for the rendering graphical elements with a software raster engine. More...

Inheritance diagram for SwCanvas:
[legend]

## Public Types

enum | Colorspace { ABGR8888 = 0, ARGB8888 }
| Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color. More...
enum | MempoolPolicy { Default = 0, Shareable, Individual }
| Enumeration specifying the methods of Memory Pool behavior policy. More...

## Public Member Functions

Result | target (uint32_t *buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept
| Sets the target buffer for the rasterization. More...
Result | mempool (MempoolPolicy policy) noexcept
| Set sw engine memory pool behavior policy. More...
Public Member Functions inherited from Canvas
Result | reserve (uint32_t n) noexcept
| Sets the size of the container, where all the paints pushed into the Canvas are stored. More...
virtual Result | push (std::unique_ptr< Paint > paint) noexcept
| Passes drawing elements to the Canvas using Paint objects. More...
virtual Result | clear (bool free=true) noexcept
| Sets the total number of the paints pushed into the canvas to be zero. Depending on the value of the `free` argument, the paints are freed or not. More...
virtual Result | update (Paint *paint) noexcept
| Request the canvas to update the paint objects. More...
virtual Result | draw () noexcept
| Request the canvas to draw the Paint objects. More...
virtual Result | sync () noexcept
| Guarantees that drawing task is finished. More...

## Static Public Member Functions

static std::unique_ptr< SwCanvas > | gen () noexcept
| Creates a new SwCanvas object. More...

## Detailed Description

A class for the rendering graphical elements with a software raster engine.

## Member Enumeration Documentation

## Colorspace

enum Colorspace

Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.

Enumerator
ABGR8888 | The channels are joined in the order: alpha, blue, green, red.
ARGB8888 | The channels are joined in the order: alpha, red, green, blue.

## MempoolPolicy

enum MempoolPolicy

Enumeration specifying the methods of Memory Pool behavior policy.

Enumerator
Default | Default behavior that ThorVG is designed to.
Shareable | Memory Pool is shared among the SwCanvases.
Individual | Allocate designated memory pool that is only used by current instance.

## Member Function Documentation

## gen()

static std::unique_ptr<SwCanvas> gen | ( |  | ) |

staticnoexcept

Creates a new SwCanvas object.

Returns
  A new SwCanvas object.

## mempool()

Result mempool | ( | MempoolPolicy | policy | ) |

noexcept

Set sw engine memory pool behavior policy.

Basically 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 memory pool policy to satisfy user demands, if it needs to guarantee the thread-safety of the internal data access.

Parameters

  [in] | policy | Use the shared cache memory. The default value is `true`

Return values

  Result::Success | When succeed.
  Result::InsufficientCondition | If the canvas has any paints.
  Result::NonSupport | In case the software engine is not supported.

Note
  When `policy` is set as `MempoolPolicy::Individual`, current instance of canvas uses its own individual memory data that 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.

## target()

Result target | ( | uint32_t * | buffer,
|  | uint32_t | stride,
|  | uint32_t | w,
|  | uint32_t | h,
|  | Colorspace | cs
| ) |  |

noexcept

Sets the target buffer for the rasterization.

The buffer of a desirable size should be allocated and owned by the caller.

Parameters

  [in] | buffer | A pointer to a memory block of the size `stride` x `h`, where the raster data are stored.
  [in] | stride | The stride of the raster image - greater than or equal to `w`.
  [in] | w | The width of the raster image.
  [in] | h | The height of the raster image.
  [in] | cs | The value specifying the way the 32-bits colors should be read/written.

Return values

  Result::Success | When succeed.
  Result::MemoryCorruption | When casting in the internal function implementation failed.
  Result::InvalidArguments | In case no valid pointer is provided or the width, or the height or the stride is zero.
  Result::NonSupport | In case the software engine is not supported.

Warning
  Do not access `buffer` during Canvas::draw() - Canvas::sync(). It should not be accessed while TVG is writing on it.