Canvas

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_API 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_API 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_API 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_API 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_API Tvg_Result	tvg_canvas_update (Tvg_Canvas *canvas)
	Updates all paints in a canvas. More...
TVG_API 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_API Tvg_Result	tvg_canvas_draw (Tvg_Canvas *canvas)
	Requests the canvas to draw the Tvg_Paint objects. More...
TVG_API 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_API 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]	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.
TVG_RESULT_INSUFFICIENT_CONDITION	An 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_API 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]

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_API 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]

canvas

The Tvg_Canvas object containing elements 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_API 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 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_API 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]	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_RESULT_FAILED_ALLOCATION	An internal error with memory allocation.

tvg_canvas_sync()

TVG_API 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]

canvas

The Tvg_Canvas object containing elements which were 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.

See also

tvg_canvas_draw()

tvg_canvas_update()

TVG_API 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.

See also

tvg_canvas_update_paint()

tvg_canvas_update_paint()

TVG_API 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.

See also

tvg_canvas_update()