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] | canvas | The Tvg_Canvas object to be cleared.
  [in] | free | If `true` the memory occupied by paints is deallocated, otherwise it is not.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An 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] | canvas | The Tvg_Canvas object to be destroyed.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An 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] | canvas | The Tvg_Canvas object to be drawn.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Canvas pointer.
  TVG_RESULT_INSUFFICIENT_CONDITION | An 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] | canvas | The Tvg_Canvas object managing the `paint`.
  [in] | paint | The 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_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | In case a `nullptr` is passed as the argument.
  TVG_RESULT_INSUFFICIENT_CONDITION | An 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] | canvas | The Tvg_Canvas object managing the reserved memory.
  [in] | n | The number of objects for which the memory is to be reserved.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An 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] | canvas | The Tvg_Canvas object which was drawn.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An 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] | canvas | The Tvg_Canvas object to be updated.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Canvas pointer.
  TVG_RESULT_INSUFFICIENT_CONDITION | An 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] | canvas | The Tvg_Canvas object to which the `paint` belongs.
  [in] | paint | The Tvg_Paint object to be updated.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | In case a `nullptr` is passed as the argument.