ThorVG  v0.1
ThorVG is a platform-independent portable library for drawing vector-based scene and animation. It's an open-source software that is freely used by a variety of software platforms and applications. ThorVG provides neat and easy APIs, its library has no dependencies and keeps cheap and super compact size. It serves as the vector graphics engine for Tizen OS that powers many products.
Modules | Macros | Functions
Canvas
ThorVG_CAPI (BETA version)

A module for managing and drawing graphical elements. More...

Collaboration diagram for Canvas:

Modules

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

Macros

#define TVG_COLORSPACE_ABGR8888   0
 The 8-bit color channels are combined into 32-bit color in the order: alpha, blue, green, red.
 
#define TVG_COLORSPACE_ARGB8888   1
 The 8-bit color channels are combined into 32-bit color in the order: alpha, red, green, blue.
 

Functions

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 object itself. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_push (Tvg_Canvas *canvas, Tvg_Paint *paint)
 Inserts a drawing element into the canvas using a Tvg_Paint object. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_reserve (Tvg_Canvas *canvas, uint32_t n)
 Reserves a memory block where the objects pushed into a canvas are stored. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_clear (Tvg_Canvas *canvas, bool free)
 Clears a Tvg_Canvas objects from pushed paints. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_update (Tvg_Canvas *canvas)
 Updates all paints in a canvas. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_update_paint (Tvg_Canvas *canvas, Tvg_Paint *paint)
 Updates the given Tvg_Paint object from the canvas before the rendering. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_draw (Tvg_Canvas *canvas)
 The function start rendering process. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_sync (Tvg_Canvas *canvas)
 Guarantees the drawing process is finished. More...
 

Detailed Description

A module for managing and drawing graphical elements.

Function Documentation

◆ tvg_canvas_clear()

TVG_EXPORT Tvg_Result tvg_canvas_clear ( Tvg_Canvas *  canvas,
bool  free 
)

Clears a Tvg_Canvas objects from pushed paints.

Tvg_Paint objects stored in the canvas are released if free is set to true, otherwise the memory is not deallocated and all paints should be released manually in order to avoid memory leaks.

Parameters
[in]canvasThe Tvg_Canvas object to be cleared.
[in]freeIf true the memory occupied by paints is deallocated, otherwise it is not.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.
Warning
Please use the free argument only when you know how it works, otherwise it's not recommended.
See also
tvg_canvas_destroy()

◆ 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 object itself.

static Tvg_Canvas *canvas = NULL;
static uint32_t *buffer = NULL;
static void _init() {
canvas = tvg_swcanvas_create();
buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
}
//a task called from main function in a loop
static void _job(const int cmd) {
switch (cmd) {
case CMD_EXIT: return 0;
case CMD_ADD_RECT:
//define valid rectangle shape
tvg_canvas_push(canvas, rect);
break;
case CMD_DEL_RECT:
tvg_paint_del(rect);
//now to safely delete Tvg_Canvas, tvg_canvas_clear() API have to be used
break;
default:
break;
}
}
int main(int argc, char **argv) {
int cmd = 0;
int stop = 1;
tvg_engine_init(TVG_ENGINE_SW, 4);
while (stop) {
//wait for a command e.g. from a console
stop = _job(cmd);
}
tvg_canvas_clear(canvas, false);
tvg_canvas_destroy(canvas);
tvg_engine_term(TVG_ENGINE_SW);
return 0;
}
tvg_canvas_destroy(canvas);
tvg_engine_term()
Parameters
[in]canvasThe Tvg_Canvas object to be destroyed.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid pointer to the Tvg_Canvas object is passed.
Note
If the paints from the canvas should not be released, the tvg_canvas_clear() with a free argument value set to false should be called. Please be aware that in such a case TVG is not responsible for the paints release anymore and it has to be done manually in order to avoid memory leaks.
See also
tvg_paint_del(), tvg_canvas_clear()

◆ tvg_canvas_draw()

TVG_EXPORT Tvg_Result tvg_canvas_draw ( Tvg_Canvas *  canvas)

The function start rendering process.

All paints from the given canvas will be rasterized to the buffer.

Parameters
[in]canvasThe Tvg_Canvas object to be drawn.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.
TVG_RESULT_INSUFFICIENT_CONDITIONAn internal error.
Note
Drawing can be asynchronous based on the assigned thread number. To guarantee the drawing is done, call tvg_canvas_sync() afterwards.
See also
tvg_canvas_sync()

◆ tvg_canvas_push()

TVG_EXPORT Tvg_Result tvg_canvas_push ( Tvg_Canvas *  canvas,
Tvg_Paint *  paint 
)

Inserts a drawing element into the canvas using a Tvg_Paint object.

Parameters
[in]canvasThe Tvg_Canvas object managing the paint.
[in]paintThe Tvg_Paint object to be drawn.

Only the paints pushed into the canvas will be drawing targets. They are retained by the canvas until you call tvg_canvas_clear(). If you know the number of the pushed objects in the advance, please call tvg_canvas_reserve().

Returns
Tvg_Result return values:
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTIn case a nullptr is passed as the argument.
TVG_RESULT_INSUFFICIENT_CONDITIONAn internal error.
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.
See also
tvg_canvas_reserve(), tvg_canvas_clear()

◆ tvg_canvas_reserve()

TVG_EXPORT Tvg_Result tvg_canvas_reserve ( Tvg_Canvas *  canvas,
uint32_t  n 
)

Reserves a memory block where the objects pushed into a canvas are stored.

If the number of Tvg_Paints to be stored in a canvas is known in advance, calling this function reduces the multiple memory allocations thus improves the performance.

Tvg_Canvas *canvas = NULL;
tvg_engine_init(TVG_ENGINE_SW, 4);
canvas = tvg_swcanvas_create();
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);
tvg_canvas_reserve(canvas, 100); //reserve array for 100 paints in canvas.
tvg_canvas_destroy(canvas);
tvg_engine_term()
Parameters
[in]canvasThe Tvg_Canvas object managing the reserved memory.
[in]nThe number of objects for which the memory is to be reserved.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.

◆ tvg_canvas_sync()

TVG_EXPORT Tvg_Result tvg_canvas_sync ( Tvg_Canvas *  canvas)

Guarantees the drawing process is finished.

It should be called after tvg_canvas_draw().

Parameters
[in]canvasThe Tvg_Canvas object which was drawn.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.
See also
tvg_canvas_sync()

◆ tvg_canvas_update()

TVG_EXPORT Tvg_Result tvg_canvas_update ( Tvg_Canvas *  canvas)

Updates all paints in a canvas.

Should be called before drawing in order to prepare paints for the rendering.

//A frame drawing example. Thread safety and events implementation is skipped to show only TVG code.
static Tvg_Canvas *canvas = NULL;
static Tvg_Paint *rect = NULL;
int _frame_render(void) {
tvg_canvas_update(canvas);
tvg_canvas_draw(canvas);
tvg_canvas_sync(canvas);
}
//event handler from your code or third party library
void _event_handler(event *event_data) {
if (!event_data) return NULL;
switch(event_data.type) {
case EVENT_RECT_ADD:
if (!rect) {
tvg_shape_append_rect(rect, 10, 10, 50, 50, 0, 0);
tvg_shape_set_stroke_width(rect, 1.0f);
tvg_shape_set_stroke_color(rect, 255, 0, 0, 255);
tvg_canvas_push(canvas, rect);
}
break;
case EVENT_RECT_MOVE:
if (rect) tvg_paint_translate(rect, 10.0, 10.0);
break;
default:
break;
}
}
int main(int argc, char **argv) {
//example handler from your code or third party lib
event_handler_add(handler, _event_handler);
//create frame rendering process which calls _frame_render() function.
app_loop_begin(_frame_render);
app_loop_finish();
cleanup();
}
Parameters
[in]canvasThe Tvg_Canvas object to be updated.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.
TVG_RESULT_INSUFFICIENT_CONDITIONAn internal error.

◆ tvg_canvas_update_paint()

TVG_EXPORT Tvg_Result tvg_canvas_update_paint ( Tvg_Canvas *  canvas,
Tvg_Paint *  paint 
)

Updates the given Tvg_Paint object from the canvas before the rendering.

If a client application using the TVG library does not update the entire canvas with tvg_canvas_update() in the frame rendering process, Tvg_Paint objects previously added to the canvas should be updated manually with this function.

Parameters
[in]canvasThe Tvg_Canvas object to which the paint belongs.
[in]paintThe Tvg_Paint object to be updated.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTIn case a nullptr is passed as the argument.