ThorVG  v0.8
Modules | Functions
Canvas
ThorVG_CAPI

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.
 

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)
 Sets the total number of the paints pushed into the canvas to be zero. 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. 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)
 Requests the canvas to draw the Tvg_Paint objects. More...
 
TVG_EXPORT Tvg_Result tvg_canvas_sync (Tvg_Canvas *canvas)
 Guarantees that the drawing process is finished. More...
 

Detailed Description

A module for managing and drawing graphical elements.

A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.

Note
A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.
Warning
The Paint objects belonging to one Canvas can't be shared among multiple Canvases.

Function Documentation

◆ tvg_canvas_clear()

TVG_EXPORT Tvg_Result tvg_canvas_clear ( Tvg_Canvas *  canvas,
bool  free 
)

Sets the total number of the paints pushed into the canvas to be zero. 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.
TVG_RESULT_INSUFFICIENT_CONDITIONAn internal error.
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) {
//define a valid rectangle shape
switch (cmd) {
case CMD_EXIT: return 0;
case CMD_ADD_RECT:
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(TVG_ENGINE_SW)
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)

Requests the canvas to draw the Tvg_Paint objects.

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

Parameters
[in]canvasThe Tvg_Canvas object containing elements 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 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(TVG_ENGINE_SW)
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_RESULT_FAILED_ALLOCATIONAn internal error with memory allocation.

◆ tvg_canvas_sync()

TVG_EXPORT Tvg_Result tvg_canvas_sync ( Tvg_Canvas *  canvas)

Guarantees that the drawing process is finished.

Since the canvas rendering can be performed asynchronously, it should be called after the tvg_canvas_draw().

Parameters
[in]canvasThe Tvg_Canvas object containing elements which were drawn.
Returns
Tvg_Result enumeration.
Return values
TVG_RESULT_SUCCESSSucceed.
TVG_RESULT_INVALID_ARGUMENTAn invalid Tvg_Canvas pointer.
TVG_RESULT_INSUFFICIENT_CONDITIONAn internal error.
See also
tvg_canvas_draw()

◆ 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.
See also
tvg_canvas_update_paint()

◆ 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.
See also
tvg_canvas_update()
tvg_shape_append_rect
TVG_EXPORT Tvg_Result tvg_shape_append_rect(Tvg_Paint *paint, float x, float y, float w, float h, float rx, float ry)
Appends a rectangle to the path.
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.
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_canvas_sync
TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas *canvas)
Guarantees that the drawing process is finished.
tvg_canvas_clear
TVG_EXPORT Tvg_Result tvg_canvas_clear(Tvg_Canvas *canvas, bool free)
Sets the total number of the paints pushed into the canvas to be zero. Tvg_Paint objects stored in th...
TVG_ENGINE_SW
@ TVG_ENGINE_SW
CPU rasterizer.
Definition: thorvg_capi.h:84
tvg_paint_del
TVG_EXPORT Tvg_Result tvg_paint_del(Tvg_Paint *paint)
Releases the given Tvg_Paint object.
Tvg_Canvas
struct _Tvg_Canvas Tvg_Canvas
A structure responsible for managing and drawing graphical elements.
Definition: thorvg_capi.h:55
tvg_canvas_update
TVG_EXPORT Tvg_Result tvg_canvas_update(Tvg_Canvas *canvas)
Updates all paints in a canvas.
tvg_canvas_draw
TVG_EXPORT Tvg_Result tvg_canvas_draw(Tvg_Canvas *canvas)
Requests the canvas to draw the Tvg_Paint objects.
tvg_paint_translate
TVG_EXPORT Tvg_Result tvg_paint_translate(Tvg_Paint *paint, float x, float y)
Moves the given Tvg_Paint in a two-dimensional space.
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_Paint
struct _Tvg_Paint Tvg_Paint
A structure representing a graphical element.
Definition: thorvg_capi.h:63
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_shape_set_stroke_width
TVG_EXPORT Tvg_Result tvg_shape_set_stroke_width(Tvg_Paint *paint, float width)
Sets the stroke width for all of the figures from the paint.
tvg_shape_set_stroke_color
TVG_EXPORT Tvg_Result tvg_shape_set_stroke_color(Tvg_Paint *paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)
Sets the shape's stroke color.
tvg_engine_term
TVG_EXPORT Tvg_Result tvg_engine_term(Tvg_Engine engine_method)
Terminates TVG engines.
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.
Generated by   doxygen 1.8.17