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.

Modules

Macros

Functions

Detailed Description

Function Documentation

◆ tvg_canvas_clear()

◆ tvg_canvas_destroy()

◆ tvg_canvas_draw()

◆ tvg_canvas_push()

◆ tvg_canvas_reserve()

◆ tvg_canvas_sync()

◆ tvg_canvas_update()

◆ tvg_canvas_update_paint()