SwCanvas

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

Inheritance diagram for SwCanvas:

Collaboration diagram for SwCanvas:

Public Types
enum	Colorspace { ABGR8888 = 0 , ARGB8888 , ABGR8888S , ARGB8888S }
	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 drawing target for the rasterization. More...
Result	mempool (MempoolPolicy policy) noexcept
	Set sw engine memory pool behavior policy. More...
Public Member Functions inherited from Canvas
std::list< Paint * > &	paints () noexcept
	Returns the list of the paints that currently held by the Canvas. 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
	Clear the internal canvas resources that used for the drawing. More...
virtual Result	update (Paint *paint=nullptr) noexcept
	Request the canvas to update the paint objects. More...
virtual Result	draw () noexcept
	Requests the canvas to draw the Paint objects. More...
virtual Result	viewport (int32_t x, int32_t y, int32_t w, int32_t h) noexcept
	Sets the drawing region in the canvas. 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. Colors are alpha-premultiplied. (a << 24 | b << 16 | g << 8 | r)
ARGB8888	The channels are joined in the order: alpha, red, green, blue. Colors are alpha-premultiplied. (a << 24 | r << 16 | g << 8 | b)
ABGR8888S	The channels are joined in the order: alpha, blue, green, red. Colors are un-alpha-premultiplied. Since 0.12
ARGB8888S	The channels are joined in the order: alpha, red, green, blue. Colors are un-alpha-premultiplied. Since 0.12

MempoolPolicy

enum MempoolPolicy

Enumeration specifying the methods of Memory Pool behavior policy.

Since

0.4

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

Parameters

[in]

policy

The method specifying the Memory Pool behavior. The default value is MempoolPolicy::Default.

Return values

Result::InsufficientCondition	If the canvas contains some paints already.
Result::NonSupport	In case the software engine is not supported.

Note

When policy is set as MempoolPolicy::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.

Since

0.4

target()

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

noexcept

Sets the drawing target 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::InvalidArguments	In case no valid pointer is provided or the width, or the height or the stride is zero.
Result::InsufficientCondition	if the canvas is performing rendering. Please ensure the canvas is synced.
Result::NonSupport	In case the software engine is not supported.

Warning

Do not access buffer during Canvas::push() - Canvas::sync(). It should not be accessed while the engine is writing on it.

See also

Canvas::viewport()

Canvas::sync()