| ThorVG v0.8

Enumerations | Functions
SwCanvas
ThorVG_CAPI » Canvas

A module for rendering the graphical elements using the software engine. More...

Collaboration diagram for SwCanvas:

## Enumerations
enum | Tvg_Mempool_Policy { TVG_MEMPOOL_POLICY_DEFAULT = 0, TVG_MEMPOOL_POLICY_SHAREABLE, TVG_MEMPOOL_POLICY_INDIVIDUAL }
| Enumeration specifying the methods of Memory Pool behavior policy. More...
enum | Tvg_Colorspace { TVG_COLORSPACE_ABGR8888 = 0, TVG_COLORSPACE_ARGB8888 }
| Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color. More...

## Functions
TVG_EXPORT Tvg_Canvas * | tvg_swcanvas_create ()
| Creates a Canvas object. More...
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)
| Sets the buffer used in the rasterization process and defines the used colorspace. More...
TVG_EXPORT Tvg_Result | tvg_swcanvas_set_mempool (Tvg_Canvas *canvas, Tvg_Mempool_Policy policy)
| Sets the software engine memory pool behavior policy. More...

## Detailed Description

A module for rendering the graphical elements using the software engine.

## Enumeration Type Documentation

## ◆ Tvg_Colorspace

enum Tvg_Colorspace

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

Enumerator
TVG_COLORSPACE_ABGR8888 | The 8-bit color channels are combined into 32-bit color in the order: alpha, blue, green, red.
TVG_COLORSPACE_ARGB8888 | The 8-bit color channels are combined into 32-bit color in the order: alpha, red, green, blue.

## ◆ Tvg_Mempool_Policy

enum Tvg_Mempool_Policy

Enumeration specifying the methods of Memory Pool behavior policy.

Enumerator
TVG_MEMPOOL_POLICY_DEFAULT | 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.

## Function Documentation

## ◆ tvg_swcanvas_create()

TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create | ( |  | ) |

Creates a Canvas object.

Tvg_Canvas *canvas = NULL;
tvg_engine_init(TVG_ENGINE_SW, 4);
canvas = tvg_swcanvas_create();
//set up the canvas buffer
uint32_t *buffer = NULL;
buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
if (!buffer) return;
tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
//set up paints and add them into the canvas before drawing it
tvg_canvas_destroy(canvas);
tvg_engine_term(TVG_ENGINE_SW);

Returns
  A new Tvg_Canvas object.

## ◆ tvg_swcanvas_set_mempool()

TVG_EXPORT Tvg_Result tvg_swcanvas_set_mempool | ( | Tvg_Canvas * | canvas,
|  | Tvg_Mempool_Policy | policy
| ) |  |

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.

Parameters

  [in] | canvas | The Tvg_Canvas object of which the Memory Pool behavior is to be specified.
  [in] | policy | The method specifying the Memory Pool behavior. The default value is `TVG_MEMPOOL_POLICY_DEFAULT`.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENTS | An invalid canvas pointer passed.
  TVG_RESULT_INSUFFICIENT_CONDITION | The canvas contains some paints already.
  TVG_RESULT_NOT_SUPPORTED | The software engine is not supported.

Note
  When `policy` is set as `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_swcanvas_set_target()

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
| ) |  |

Sets the buffer used in the rasterization process and defines the used colorspace.

For optimisation reasons TVG does not allocate memory for the output buffer on its own. The buffer of a desirable size should be allocated and owned by the caller.

Parameters

  [in] | canvas | The Tvg_Canvas object managing the `buffer`.
  [in] | buffer | A pointer to the allocated memory block of the size `stride` x `h`.
  [in] | stride | The stride of the raster image - in most cases same value as `w`.
  [in] | w | The width of the raster image.
  [in] | h | The height of the raster image.
  [in] | cs | The colorspace value defining the way the 32-bits colors should be read/written. TVG_COLORSPACE_ABGR8888 TVG_COLORSPACE_ARGB8888

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_MEMORY_CORRUPTION | Casting in the internal function implementation failed.
  TVG_RESULT_INVALID_ARGUMENTS | An invalid canvas or buffer pointer passed or one of the `stride`, `w` or `h` being zero.
  TVG_RESULT_NOT_SUPPORTED | The software engine is not supported.

Warning
  Do not access `buffer` during tvg_canvas_draw() - tvg_canvas_sync(). It should not be accessed while TVG is writing on it.

See also
  Tvg_Colorspace

tvg_swcanvas_set_target
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)
Sets the buffer used in the rasterization process and defines the used colorspace.
TVG_ENGINE_SW
@ TVG_ENGINE_SW
CPU rasterizer.
Definition: thorvg_capi.h:84
Tvg_Canvas
struct _Tvg_Canvas Tvg_Canvas
A structure responsible for managing and drawing graphical elements.
Definition: thorvg_capi.h:55
tvg_swcanvas_create
TVG_EXPORT Tvg_Canvas * tvg_swcanvas_create()
Creates a Canvas object.
tvg_engine_init
TVG_EXPORT Tvg_Result tvg_engine_init(Tvg_Engine engine_method, unsigned threads)
Initializes TVG engines.
TVG_COLORSPACE_ARGB8888
@ TVG_COLORSPACE_ARGB8888
The 8-bit color channels are combined into 32-bit color in the order: alpha, red, green,...
Definition: thorvg_capi.h:332
tvg_canvas_destroy
TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas *canvas)
Clears the canvas internal data, releases all paints stored by the canvas and destroys the canvas obj...
tvg_engine_term
TVG_EXPORT Tvg_Result tvg_engine_term(Tvg_Engine engine_method)
Terminates TVG engines.