SwCanvas

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_API Tvg_Canvas *	tvg_swcanvas_create ()
	Creates a Canvas object. More...
TVG_API 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_API 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_API 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_API 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_API 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