thorvg_capi.h

The module provides C bindings for the ThorVG library. Please refer to src/examples/Capi.cpp to find the thorvg_capi usage examples.

The thorvg_capi module allows to implement the ThorVG client and provides the following functionalities:

drawing shapes: line, curve, polygon, circle, user-defined, ...
filling: solid, linear and radial gradient
scene graph & affine transformation (translation, rotation, scale, ...)
stroking: width, join, cap, dash
composition: blending, masking, path clipping
pictures: SVG, PNG, JPG, bitmap

Defines

TVG_BUILD

__THORVG_CAPI_H__

TVG_API

TVG_DEPRECATED

Typedefs

typedef struct _Tvg_Canvas Tvg_Canvas

A structure responsible for managing and drawing graphical elements.

It sets up the target buffer, which can be drawn on the screen. It stores the Tvg_Paint objects (Shape, Scene, Picture).

typedef struct _Tvg_Paint Tvg_Paint: A structure representing a graphical element.

Warning

The TvgPaint objects cannot be shared between Canvases.

typedef struct _Tvg_Gradient Tvg_Gradient: A structure representing a gradient fill of a Tvg_Paint object.

typedef struct _Tvg_Saver Tvg_Saver: A structure representing an object that enables to save a Tvg_Paint object into a file.

typedef struct _Tvg_Animation Tvg_Animation: A structure representing an animation controller object.

Enums

enum Tvg_Engine

Enumeration specifying the engine type used for the graphics backend. For multiple backends bitwise operation is allowed.

Values:

enumerator TVG_ENGINE_SW: CPU rasterizer.

enumerator TVG_ENGINE_GL: OpenGL rasterizer.

enum Tvg_Result

Enumeration specifying the result from the APIs.

All ThorVG APIs could potentially return one of the values in the list. Please note that some APIs may additionally specify the reasons that trigger their return values.

Values:

enumerator TVG_RESULT_SUCCESS: The value returned in case of a correct request execution.

enumerator TVG_RESULT_INVALID_ARGUMENT: The value returned in the event of a problem with the arguments given to the API - e.g. empty paths or null pointers.

enumerator TVG_RESULT_INSUFFICIENT_CONDITION: The value returned in case the request cannot be processed - e.g. asking for properties of an object, which does not exist.

enumerator TVG_RESULT_FAILED_ALLOCATION: The value returned in case of unsuccessful memory allocation.

enumerator TVG_RESULT_MEMORY_CORRUPTION: The value returned in the event of bad memory handling - e.g. failing in pointer releasing or casting.

enumerator TVG_RESULT_NOT_SUPPORTED: The value returned in case of choosing unsupported engine features(options).

enumerator TVG_RESULT_UNKNOWN: The value returned in all other cases.

enum Tvg_Composite_Method

Enumeration indicating the method used in the composition of two objects - the target and the source.

Values:

enumerator TVG_COMPOSITE_METHOD_NONE: No composition is applied.

enumerator TVG_COMPOSITE_METHOD_CLIP_PATH

The intersection of the source and the target is determined and only the resulting pixels from the source are rendered. Note that ClipPath only supports the Shape type.

Deprecated:: Use Paint::clip() instead.

enumerator TVG_COMPOSITE_METHOD_ALPHA_MASK: The pixels of the source and the target are alpha blended. As a result, only the part of the source, which intersects with the target is visible.

enumerator TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK: The pixels of the source and the complement to the target's pixels are alpha blended. As a result, only the part of the source which is not covered by the target is visible.

enumerator TVG_COMPOSITE_METHOD_LUMA_MASK

The source pixels are converted to grayscale (luma value) and alpha blended with the target. As a result, only the part of the source which intersects with the target is visible.

Since: 0.9

enumerator TVG_COMPOSITE_METHOD_INVERSE_LUMA_MASK

The source pixels are converted to grayscale (luma value) and complement to the target's pixels are alpha blended. As a result, only the part of the source which is not covered by the target is visible.

Since: 0.14

enum Tvg_Blend_Method

Enumeration indicates the method used for blending paint. Please refer to the respective formulas for each method.

Since: 0.15

Values:

enumerator TVG_BLEND_METHOD_NORMAL: Perform the alpha blending(default). S if (Sa == 255), otherwise (Sa * S) + (255 - Sa) * D.

enumerator TVG_BLEND_METHOD_MULTIPLY: Takes the RGB channel values from 0 to 255 of each pixel in the top layer and multiples them with the values for the corresponding pixel from the bottom layer. (S * D)

enumerator TVG_BLEND_METHOD_SCREEN: The values of the pixels in the two layers are inverted, multiplied, and then inverted again. (S + D) - (S * D)

enumerator TVG_BLEND_METHOD_OVERLAY: Combines Multiply and Screen blend modes. (2 * S * D) if (2 * D < Da), otherwise (Sa * Da) - 2 * (Da - S) * (Sa - D)

enumerator TVG_BLEND_METHOD_SRCOVER: Replace the bottom layer with the top layer.

enumerator TVG_BLEND_METHOD_DARKEN: Creates a pixel that retains the smallest components of the top and bottom layer pixels. min(S, D)

enumerator TVG_BLEND_METHOD_LIGHTEN: Only has the opposite action of Darken Only. max(S, D)

enumerator TVG_BLEND_METHOD_COLORDODGE: Divides the bottom layer by the inverted top layer. D / (255 - S)

enumerator TVG_BLEND_METHOD_COLORBURN: Divides the inverted bottom layer by the top layer, and then inverts the result. 255 - (255 - D) / S.

enumerator TVG_BLEND_METHOD_HARDLIGHT: The same as Overlay but with the color roles reversed. (2 * S * D) if (S < Sa), otherwise (Sa * Da) - 2 * (Da - S) * (Sa - D)

enumerator TVG_BLEND_METHOD_SOFTLIGHT: The same as Overlay but with applying pure black or white does not result in pure black or white. (1 - 2 * S) * (D ^ 2) + (2 * S * D)

enumerator TVG_BLEND_METHOD_DIFFERENCE: Subtracts the bottom layer from the top layer or the other way around, to always get a non-negative value. (S - D) if (S > D), otherwise (D - S)

enumerator TVG_BLEND_METHOD_EXCLUSION: The result is twice the product of the top and bottom layers, subtracted from their sum. s + d - (2 * s * d)

enumerator TVG_BLEND_METHOD_HUE: Reserved. Not supported.

enumerator TVG_BLEND_METHOD_SATURATION: Reserved. Not supported.

enumerator TVG_BLEND_METHOD_COLOR: Reserved. Not supported.

enumerator TVG_BLEND_METHOD_LUMINOSITY: Reserved. Not supported.

enumerator TVG_BLEND_METHOD_ADD: Simply adds pixel values of one layer with the other. (S + D)

enumerator TVG_BLEND_METHOD_HARDMIX: Reserved. Not supported.

enum Tvg_Identifier

Deprecated:

See also

Tvg_Type

Values:

enumerator TVG_IDENTIFIER_UNDEF: Undefined type.

enumerator TVG_IDENTIFIER_SHAPE: A shape type paint.

enumerator TVG_IDENTIFIER_SCENE: A scene type paint.

enumerator TVG_IDENTIFIER_PICTURE: A picture type paint.

enumerator TVG_IDENTIFIER_LINEAR_GRAD: A linear gradient type.

enumerator TVG_IDENTIFIER_RADIAL_GRAD: A radial gradient type.

enumerator TVG_IDENTIFIER_TEXT: A text type paint.

enum Tvg_Type

Enumeration indicating the ThorVG object type value.

ThorVG's drawing objects can return object type values, allowing you to identify the specific type of each object.

See also

tvg_paint_get_type()

See also

tvg_gradient_get_type()

Note

Experimental API

Values:

enumerator TVG_TYPE_UNDEF: Undefined type.

enumerator TVG_TYPE_SHAPE: A shape type paint.

enumerator TVG_TYPE_SCENE: A scene type paint.

enumerator TVG_TYPE_PICTURE: A picture type paint.

enumerator TVG_TYPE_TEXT: A text type paint.

enumerator TVG_TYPE_LINEAR_GRAD: A linear gradient type.

enumerator TVG_TYPE_RADIAL_GRAD: A radial gradient type.

enum Tvg_Path_Command

Enumeration specifying the values of the path commands accepted by TVG.

Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). TVG interprets all of them and translates to the ones from the PathCommand values.

Values:

enumerator TVG_PATH_COMMAND_CLOSE: Ends the current sub-path and connects it with its initial point - corresponds to Z command in the svg path commands.

enumerator TVG_PATH_COMMAND_MOVE_TO: Sets a new initial point of the sub-path and a new current point - corresponds to M command in the svg path commands.

enumerator TVG_PATH_COMMAND_LINE_TO: Draws a line from the current point to the given point and sets a new value of the current point - corresponds to L command in the svg path commands.

enumerator TVG_PATH_COMMAND_CUBIC_TO: Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point - corresponds to C command in the svg path commands.

enum Tvg_Stroke_Cap

Enumeration determining the ending type of a stroke in the open sub-paths.

Values:

enumerator TVG_STROKE_CAP_SQUARE: The stroke is extended in both endpoints of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width.

enumerator TVG_STROKE_CAP_ROUND: The stroke is extended in both endpoints of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered.

enumerator TVG_STROKE_CAP_BUTT: The stroke ends exactly at each of the two endpoints of a sub-path. For zero length sub-paths no stroke is rendered.

enum Tvg_Stroke_Join

Enumeration specifying how to fill the area outside the gradient bounds.

Values:

enumerator TVG_STROKE_JOIN_BEVEL: The outer corner of the joined path segments is bevelled at the join point. The triangular region of the corner is enclosed by a straight line between the outer corners of each stroke.

enumerator TVG_STROKE_JOIN_ROUND: The outer corner of the joined path segments is rounded. The circular region is centered at the join point.

enumerator TVG_STROKE_JOIN_MITER: The outer corner of the joined path segments is spiked. The spike is created by extension beyond the join point of the outer edges of the stroke until they intersect. In case the extension goes beyond the limit, the join style is converted to the Bevel style.

enum Tvg_Stroke_Fill

Enumeration specifying how to fill the area outside the gradient bounds.

Values:

enumerator TVG_STROKE_FILL_PAD: The remaining area is filled with the closest stop color.

enumerator TVG_STROKE_FILL_REFLECT: The gradient pattern is reflected outside the gradient area until the expected region is filled.

enumerator TVG_STROKE_FILL_REPEAT: The gradient pattern is repeated continuously beyond the gradient area until the expected region is filled.

enum Tvg_Fill_Rule

Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape.

Values:

enumerator TVG_FILL_RULE_WINDING: A line from the point to a location outside the shape is drawn. The intersections of the line with the path segment of the shape are counted. Starting from zero, if the path segment of the shape crosses the line clockwise, one is added, otherwise one is subtracted. If the resulting sum is non zero, the point is inside the shape.

enumerator TVG_FILL_RULE_EVEN_ODD: A line from the point to a location outside the shape is drawn and its intersections with the path segments of the shape are counted. If the number of intersections is an odd number, the point is inside the shape.

enum Tvg_Mempool_Policy

Enumeration specifying the methods of Memory Pool behavior policy.

Values:

enumerator TVG_MEMPOOL_POLICY_DEFAULT: Default behavior that ThorVG is designed to.

enumerator TVG_MEMPOOL_POLICY_SHAREABLE: Memory Pool is shared among canvases.

enumerator TVG_MEMPOOL_POLICY_INDIVIDUAL: Allocate designated memory pool that is used only by the current canvas instance.

enum Tvg_Colorspace

Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.

Values:

enumerator TVG_COLORSPACE_ABGR8888: The channels are joined in the order: alpha, blue, green, red. Colors are alpha-premultiplied. (a << 24 | b << 16 | g << 8 | r)

enumerator TVG_COLORSPACE_ARGB8888: The channels are joined in the order: alpha, red, green, blue. Colors are alpha-premultiplied. (a << 24 | r << 16 | g << 8 | b)

enumerator TVG_COLORSPACE_ABGR8888S

The channels are joined in the order: alpha, blue, green, red. Colors are un-alpha-premultiplied.

Since: 0.13

enumerator TVG_COLORSPACE_ARGB8888S

The channels are joined in the order: alpha, red, green, blue. Colors are un-alpha-premultiplied.

Since: 0.13

Functions

Tvg_Result tvg_engine_init(Tvg_Engine engine_method, unsigned threads)

Initializes TVG engines.

TVG requires the running-engine environment. TVG runs its own task-scheduler for parallelizing rendering tasks efficiently. You can indicate the number of threads, the count of which is designated threads. In the initialization step, TVG will generate/spawn the threads as set by threads count.

tvg_engine_init(TVG_ENGINE_SW, 0);  //Initialize software renderer and use the main thread only

See also

tvg_engine_term()

See also

Tvg_Engine

Note

The Initializer keeps track of the number of times it was called. Threads count is fixed at the first init() call.

Parameters:

engine_method – [in] The engine types to initialize. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed.
- TVG_ENGINE_SW: CPU rasterizer
- TVG_ENGINE_GL: OpenGL rasterizer (not supported yet)
threads – [in] The number of additional threads used to perform rendering. Zero indicates only the main thread is to be used.

Return values:

TVG_RESULT_INVALID_ARGUMENT – Unknown engine type.
TVG_RESULT_NOT_SUPPORTED – Unsupported engine type.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_engine_term(Tvg_Engine engine_method)

Terminates TVG engines.

It should be called in case of termination of the TVG client with the same engine types as were passed when tvg_engine_init() was called.

tvg_engine_init(TVG_ENGINE_SW, 0);
//define canvas and shapes, update shapes, general rendering calls
tvg_engine_term(TVG_ENGINE_SW);

See also

tvg_engine_init()

See also

Tvg_Engine

Parameters:

engine_method – The engine types to terminate. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed

TVG_ENGINE_SW: CPU rasterizer
TVG_ENGINE_GL: OpenGL rasterizer (not supported yet)

Return values:

TVG_RESULT_INSUFFICIENT_CONDITION – Nothing to be terminated.
TVG_RESULT_INVALID_ARGUMENT – Unknown engine type.
TVG_RESULT_NOT_SUPPORTED – Unsupported engine type.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_engine_version(uint32_t *major, uint32_t *minor, uint32_t *micro, const char **version)

Retrieves the version of the TVG engine.

Since: 0.15

Parameters:

major – [out] A major version number.
minor – [out] A minor version number.
micro – [out] A micro version number.
version – [out] The version of the engine in the format major.minor.micro, or a nullptr in case of an internal error.

Return values:

TVG_RESULT_SUCCESS. –

Returns:

Tvg_Result enumeration.

Tvg_Canvas *tvg_swcanvas_create(void)

Creates a Canvas object.

Tvg_Canvas *canvas = NULL;

tvg_engine_init(TVG_ENGINE_SW, 4);
canvas = tvg_swcanvas_create();

//set up the canvas buffer
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);

//set up paints and add them into the canvas before drawing it

tvg_canvas_destroy(canvas);
tvg_engine_term(TVG_ENGINE_SW);

Returns:: A new Tvg_Canvas object.

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.

For optimisation reasons TVG does not allocate memory for the output buffer on its own. The buffer of a desirable size should be allocated and owned by the caller.

See also

Tvg_Colorspace

Warning

Do not access buffer during tvg_canvas_draw() - tvg_canvas_sync(). It should not be accessed while the engine is writing on it.

Parameters:

canvas – [in] The Tvg_Canvas object managing the buffer.
buffer – [in] A pointer to the allocated memory block of the size stride x h.
stride – [in] The stride of the raster image - in most cases same value as w.
w – [in] The width of the raster image.
h – [in] The height of the raster image.
cs – [in] The colorspace value defining the way the 32-bits colors should be read/written.
- TVG_COLORSPACE_ABGR8888
- TVG_COLORSPACE_ARGB8888

Return values:

TVG_RESULT_INVALID_ARGUMENTS – An invalid canvas or buffer pointer passed or one of the stride, w or h being zero.
TVG_RESULT_INSUFFICIENT_CONDITION – if the canvas is performing rendering. Please ensure the canvas is synced.
TVG_RESULT_NOT_SUPPORTED – The software engine is not supported.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_swcanvas_set_mempool(Tvg_Canvas *canvas, Tvg_Mempool_Policy policy)

Sets the software engine memory pool behavior policy.

ThorVG draws a lot of shapes, it allocates/deallocates a few chunk of memory while processing rendering. It internally uses one shared memory pool which can be reused among the canvases in order to avoid memory overhead.

Thus ThorVG suggests using a memory pool policy to satisfy user demands, if it needs to guarantee the thread-safety of the internal data access.

Note

When policy is set as TVG_MEMPOOL_POLICY_INDIVIDUAL, the current instance of canvas uses its own individual memory data, which is not shared with others. This is necessary when the canvas is accessed on a worker-thread.

Warning

It's not allowed after pushing any paints.

Parameters:

canvas – [in] The Tvg_Canvas object of which the Memory Pool behavior is to be specified.
policy – [in] The method specifying the Memory Pool behavior. The default value is TVG_MEMPOOL_POLICY_DEFAULT.

Return values:

TVG_RESULT_INVALID_ARGUMENTS – An invalid canvas pointer passed.
TVG_RESULT_INSUFFICIENT_CONDITION – The canvas contains some paints already.
TVG_RESULT_NOT_SUPPORTED – The software engine is not supported.

Returns:

Tvg_Result enumeration.

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)

See also

tvg_paint_del(), tvg_canvas_clear()

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.

Parameters:: canvas – [in] The Tvg_Canvas object to be destroyed.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid pointer to the Tvg_Canvas object is passed.
Returns:: Tvg_Result enumeration.

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

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

Only the paints pushed into the canvas will be drawing targets. They are retained by the canvas until you call tvg_canvas_clear().

See also

tvg_canvas_clear()

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.

Parameters:

canvas – [in] The Tvg_Canvas object managing the paint.
paint – [in] The Tvg_Paint object to be drawn.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.
TVG_RESULT_INSUFFICIENT_CONDITION – An internal error.

Returns:

Tvg_Result return values:

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_destroy(canvas);
tvg_engine_term(TVG_ENGINE_SW)

Parameters:

canvas – [in] The Tvg_Canvas object managing the reserved memory.
n – [in] The number of objects for which the memory is to be reserved.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.

Returns:

Tvg_Result enumeration.

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.

See also

tvg_canvas_destroy()

Parameters:

canvas – [in] The Tvg_Canvas object to be cleared.
free – [in] If true the memory occupied by paints is deallocated, otherwise it is not.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.

Returns:

Tvg_Result enumeration.

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();
}

See also

tvg_canvas_update_paint()

Parameters:: canvas – [in] The Tvg_Canvas object to be updated.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.
Returns:: Tvg_Result enumeration.

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.

See also

tvg_canvas_update()

Parameters:

canvas – [in] The Tvg_Canvas object to which the paint belongs.
paint – [in] The Tvg_Paint object to be updated.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

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.

See also

tvg_canvas_sync()

Note

Drawing can be asynchronous based on the assigned thread number. To guarantee the drawing is done, call tvg_canvas_sync() afterwards.

Parameters:: canvas – [in] The Tvg_Canvas object containing elements to be drawn.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.
Returns:: Tvg_Result enumeration.

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().

See also

tvg_canvas_draw()

Parameters:

canvas – [in] The Tvg_Canvas object containing elements which were drawn.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – canvas is either already in sync condition or in a damaged condition (a draw is required before syncing).

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_canvas_set_viewport(Tvg_Canvas *canvas, int32_t x, int32_t y, int32_t w, int32_t h)

Sets the drawing region in the canvas.

This function defines the rectangular area of the canvas that will be used for drawing operations. The specified viewport is used to clip the rendering output to the boundaries of the rectangle.

See also

tvg_swcanvas_set_target()

Since: 0.15

Note

When resetting the target, the viewport will also be reset to the target size.

Warning

It's not allowed to change the viewport during tvg_canvas_update() - tvg_canvas_sync() or tvg_canvas_push() - tvg_canvas_sync().

Parameters:

canvas – [in] The Tvg_Canvas object containing elements which were drawn.
x – [in] The x-coordinate of the upper-left corner of the rectangle.
y – [in] The y-coordinate of the upper-left corner of the rectangle.
w – [in] The width of the rectangle.
h – [in] The height of the rectangle.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_del(Tvg_Paint *paint)

Releases the given Tvg_Paint object.

//example of cleanup function
Tvg_Paint *rect = NULL; //rectangle shape added in other function

//rectangle delete API
int rectangle_delete(void) {
  if (rect) tvg_paint_del(rect);
  rect = NULL;
}

int cleanup(void) {
  tvg_canvas_clear(canvas, false);
  tvg_canvas_destroy(canvas);
  canvas = NULL;
}

Warning

If this function is used, tvg_canvas_clear() with the free argument value set to false should be used in order to avoid unexpected behaviours.

Parameters:: paint – [in] The Tvg_Paint object to be released.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
Returns:: Tvg_Result enumeration.

Tvg_Result tvg_paint_scale(Tvg_Paint *paint, float factor)

Scales the given Tvg_Paint object by the given factor.

See also

tvg_paint_set_transform()

Parameters:

paint – [in] The Tvg_Paint object to be scaled.
factor – [in] The value of the scaling factor. The default value is 1.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – in case a custom transform is applied.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_rotate(Tvg_Paint *paint, float degree)

Rotates the given Tvg_Paint by the given angle.

The angle in measured clockwise from the horizontal axis. The rotational axis passes through the point on the object with zero coordinates.

See also

tvg_paint_set_transform()

Parameters:

paint – [in] The Tvg_Paint object to be rotated.
degree – [in] The value of the rotation angle in degrees.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – in case a custom transform is applied.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_translate(Tvg_Paint *paint, float x, float y)

Moves the given Tvg_Paint in a two-dimensional space.

The origin of the coordinate system is in the upper-left corner of the canvas. The horizontal and vertical axes point to the right and down, respectively.

See also

tvg_paint_set_transform()

Parameters:

paint – [in] The Tvg_Paint object to be shifted.
x – [in] The value of the horizontal shift.
y – [in] The value of the vertical shift.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – in case a custom transform is applied.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_set_transform(Tvg_Paint *paint, const Tvg_Matrix *m)

Transforms the given Tvg_Paint using the augmented transformation matrix.

The augmented matrix of the transformation is expected to be given.

Parameters:

paint – [in] The Tvg_Paint object to be transformed.
m – [in] The 3x3 augmented matrix.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_get_transform(Tvg_Paint *paint, Tvg_Matrix *m)

Gets the matrix of the affine transformation of the given Tvg_Paint object.

In case no transformation was applied, the identity matrix is returned.

Parameters:

paint – [in] The Tvg_Paint object of which to get the transformation matrix.
m – [out] The 3x3 augmented matrix.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_set_opacity(Tvg_Paint *paint, uint8_t opacity)

Sets the opacity of the given Tvg_Paint.

Note

Setting the opacity with this API may require multiple renderings using a composition. It is recommended to avoid changing the opacity if possible.

Parameters:

paint – [in] The Tvg_Paint object of which the opacity value is to be set.
opacity – [in] The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_get_opacity(const Tvg_Paint *paint, uint8_t *opacity)

Gets the opacity of the given Tvg_Paint.

Parameters:

paint – [in] The Tvg_Paint object of which to get the opacity value.
opacity – [out] The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Paint *tvg_paint_duplicate(Tvg_Paint *paint)

Duplicates the given Tvg_Paint object.

Creates a new object and sets its all properties as in the original object.

Parameters:: paint – [in] The Tvg_Paint object to be copied.
Returns:: A copied Tvg_Paint object if succeed, nullptr otherwise.

Tvg_Result tvg_paint_get_bounds(const Tvg_Paint *paint, float *x, float *y, float *w, float *h, bool transformed)

Gets the axis-aligned bounding box of the Tvg_Paint object.

See also

tvg_canvas_update_paint()

Note

This is useful when you need to figure out the bounding box of the paint in the canvas space.

Note

The bounding box doesn't indicate the actual drawing region. It's the smallest rectangle that encloses the object.

Note

If transformed is true, the paint needs to be pushed into a canvas and updated before this api is called.

Parameters:

paint – [in] The Tvg_Paint object of which to get the bounds.
x – [out] The x-coordinate of the upper-left corner of the object.
y – [out] The y-coordinate of the upper-left corner of the object.
w – [out] The width of the object.
h – [out] The height of the object.
transformed – [in] If true, the paint's transformations are taken into account in the scene it belongs to. Otherwise they aren't.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_set_composite_method(Tvg_Paint *paint, Tvg_Paint *target, Tvg_Composite_Method method)

Sets the composition target object and the composition method.

Parameters:

paint – [in] The source object of the composition.
target – [in] The target object of the composition.
method – [in] The method used to composite the source object with the target.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid paint or target object or the method equal to TVG_COMPOSITE_METHOD_NONE.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_get_composite_method(const Tvg_Paint *paint, const Tvg_Paint **target, Tvg_Composite_Method *method)

Gets the composition target object and the composition method.

Parameters:

paint – [in] The source object of the composition.
target – [out] The target object of the composition.
method – [out] The method used to composite the source object with the target.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_set_clip(Tvg_Paint *paint, Tvg_Paint *clipper)

Clip the drawing region of the paint object.

This function restricts the drawing area of the paint object to the specified shape's paths.

Note

Experimental API

Parameters:

paint – [in] The target object of the clipping.
clipper – [in] The shape object as the clipper.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.
TVG_RESULT_NOT_SUPPORTED – If the clipper type is not Shape.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_get_type(const Tvg_Paint *paint, Tvg_Type *type)

Gets the unique value of the paint instance indicating the instance type.

Note

Experimental API

Parameters:

paint – [in] The Tvg_Paint object of which to get the type value.
type – [out] The unique type of the paint instance type.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_paint_get_identifier(const Tvg_Paint *paint, Tvg_Identifier *identifier)

See also

tvg_paint_get_type()

Tvg_Result tvg_paint_set_blend_method(Tvg_Paint *paint, Tvg_Blend_Method method)

Sets the blending method for the paint object.

The blending feature allows you to combine colors to create visually appealing effects, including transparency, lighting, shading, and color mixing, among others. its process involves the combination of colors or images from the source paint object with the destination (the lower layer image) using blending operations. The blending operation is determined by the chosen BlendMethod, which specifies how the colors or images are combined.

Since: 0.15

Parameters:

paint – [in] The Tvg_Paint object of which to set the blend method.
method – [in] The blending method to be set.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Paint *tvg_shape_new(void)

Creates a new shape object.

Returns:: A new shape object.

Tvg_Result tvg_shape_reset(Tvg_Paint *paint)

Resets the shape path properties.

The color, the fill and the stroke properties are retained.

Note

The memory, where the path data is stored, is not deallocated at this stage for caching effect.

Parameters:: paint – [in] A Tvg_Paint pointer to the shape object.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
Returns:: Tvg_Result enumeration.

Tvg_Result tvg_shape_move_to(Tvg_Paint *paint, float x, float y)

Sets the initial point of the sub-path.

The value of the current point is set to the given point.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
x – [in] The horizontal coordinate of the initial point of the sub-path.
y – [in] The vertical coordinate of the initial point of the sub-path.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_line_to(Tvg_Paint *paint, float x, float y)

Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point.

The value of the current point is set to the given end-point.

Note

In case this is the first command in the path, it corresponds to the tvg_shape_move_to() call.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
x – [in] The horizontal coordinate of the end-point of the line.
y – [in] The vertical coordinate of the end-point of the line.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_cubic_to(Tvg_Paint *paint, float cx1, float cy1, float cx2, float cy2, float x, float y)

Adds new points to the sub-path, which results in drawing a cubic Bezier curve.

The Bezier curve starts at the current point and ends at the given end-point (x, y). Two control points (cx1, cy1) and (cx2, cy2) are used to determine the shape of the curve. The value of the current point is set to the given end-point.

Note

In case this is the first command in the path, no data from the path are rendered.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cx1 – [in] The horizontal coordinate of the 1st control point.
cy1 – [in] The vertical coordinate of the 1st control point.
cx2 – [in] The horizontal coordinate of the 2nd control point.
cy2 – [in] The vertical coordinate of the 2nd control point.
x – [in] The horizontal coordinate of the endpoint of the curve.
y – [in] The vertical coordinate of the endpoint of the curve.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_close(Tvg_Paint *paint)

Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path.

The value of the current point is set to the initial point of the closed sub-path.

Note

In case the sub-path does not contain any points, this function has no effect.

Parameters:: paint – [in] A Tvg_Paint pointer to the shape object.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
Returns:: Tvg_Result enumeration.

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.

The rectangle with rounded corners can be achieved by setting non-zero values to rx and ry arguments. The rx and ry values specify the radii of the ellipse defining the rounding of the corners.

The position of the rectangle is specified by the coordinates of its upper-left corner - x and y arguments.

The rectangle is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (x + rx, y) - in case rx is greater than w/2 the current point is set to (x + w/2, y)

&

Note

For rx and ry greater than or equal to the half of w and the half of h, respectively, the shape become an ellipse.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
x – [in] The horizontal coordinate of the upper-left corner of the rectangle.
y – [in] The vertical coordinate of the upper-left corner of the rectangle.
w – [in] The width of the rectangle.
h – [in] The height of the rectangle.
rx – [in] The x-axis radius of the ellipse defining the rounded corners of the rectangle.
ry – [in] The y-axis radius of the ellipse defining the rounded corners of the rectangle.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_append_circle(Tvg_Paint *paint, float cx, float cy, float rx, float ry)

Appends an ellipse to the path.

The position of the ellipse is specified by the coordinates of its center - cx and cy arguments.

The ellipse is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (cx, cy - ry).

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cx – [in] The horizontal coordinate of the center of the ellipse.
cy – [in] The vertical coordinate of the center of the ellipse.
rx – [in] The x-axis radius of the ellipse.
ry – [in] The y-axis radius of the ellipse.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_append_arc(Tvg_Paint *paint, float cx, float cy, float radius, float startAngle, float sweep, uint8_t pie)

Appends a circular arc to the path.

The arc is treated as a new sub-path - it is not connected with the previous sub-path. The current point value is set to the end-point of the arc in case pie is false, and to the center of the arc otherwise.

Note

Setting sweep value greater than 360 degrees, is equivalent to calling tvg_shape_append_circle(paint, cx, cy, radius, radius).

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cx – [in] The horizontal coordinate of the center of the arc.
cy – [in] The vertical coordinate of the center of the arc.
radius – [in] The radius of the arc.
startAngle – [in] The start angle of the arc given in degrees, measured counter-clockwise from the horizontal line.
sweep – [in] The central angle of the arc given in degrees, measured counter-clockwise from startAngle.
pie – [in] Specifies whether to draw radii from the arc's center to both of its end-point - drawn if true.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_append_path(Tvg_Paint *paint, const Tvg_Path_Command *cmds, uint32_t cmdCnt, const Tvg_Point *pts, uint32_t ptsCnt)

Appends a given sub-path to the path.

The current point value is set to the last point from the sub-path. For each command from the cmds array, an appropriate number of points in pts array should be specified. If the number of points in the pts array is different than the number required by the cmds array, the shape with this sub-path will not be displayed on the screen.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cmds – [in] The array of the commands in the sub-path.
cmdCnt – [in] The length of the cmds array.
pts – [in] The array of the two-dimensional points.
ptsCnt – [in] The length of the pts array.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument or cmdCnt or ptsCnt equal to zero.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint *paint, const Tvg_Point **pts, uint32_t *cnt)

Gets the points values of the path.

The function does not allocate any data, it operates on internal memory. There is no need to free the pts array.

Tvg_Paint *shape = tvg_shape_new();
Tvg_Point *coords = NULL;
uint32_t len = 0;

tvg_shape_append_circle(shape, 10, 10, 50, 50);
tvg_shape_get_path_coords(shape, (const Tvg_Point**)&coords, &len);
//TVG approximates a circle by four Bezier curves. In the example above the coords array stores their coordinates.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
pts – [out] The pointer to the array of the two-dimensional points from the path.
cnt – [out] The length of the pts array.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_path_commands(const Tvg_Paint *paint, const Tvg_Path_Command **cmds, uint32_t *cnt)

Gets the commands data of the path.

The function does not allocate any data. There is no need to free the cmds array.

Tvg_Paint *shape = tvg_shape_new();
Tvg_Path_Command *cmds = NULL;
uint32_t len = 0;

tvg_shape_append_circle(shape, 10, 10, 50, 50);
tvg_shape_get_path_commands(shape, (const Tvg_Path_Command**)&cmds, &len);
//TVG approximates a circle by four Bezier curves. In the example above the cmds array stores the commands of the path data.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cmds – [out] The pointer to the array of the commands from the path.
cnt – [out] The length of the cmds array.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_width(Tvg_Paint *paint, float width)

Sets the stroke width for all of the figures from the paint.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
width – [in] The width of the stroke. The default value is 0.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_width(const Tvg_Paint *paint, float *width)

Gets the shape's stroke width.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
width – [out] The stroke width.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

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.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
r – [in] The red color channel value in the range [0 ~ 255]. The default value is 0.
g – [in] The green color channel value in the range [0 ~ 255]. The default value is 0.
b – [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.
a – [in] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_color(const Tvg_Paint *paint, uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a)

Gets the shape's stroke color.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
r – [out] The red color channel value in the range [0 ~ 255]. The default value is 0.
g – [out] The green color channel value in the range [0 ~ 255]. The default value is 0.
b – [out] The blue color channel value in the range [0 ~ 255]. The default value is 0.
a – [out] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – No stroke was set.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)

Sets the linear gradient fill of the stroke for all of the figures from the path.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [in] The linear gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_MEMORY_CORRUPTION – An invalid Tvg_Gradient pointer or an error with accessing it.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)

Sets the radial gradient fill of the stroke for all of the figures from the path.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [in] The radial gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_MEMORY_CORRUPTION – An invalid Tvg_Gradient pointer or an error with accessing it.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint *paint, Tvg_Gradient **grad)

Gets the gradient fill of the shape's stroke.

The function does not allocate any memory.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [out] The gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_dash(Tvg_Paint *paint, const float *dashPattern, uint32_t cnt)

Sets the shape's stroke dash pattern.

Note

To reset the stroke dash pattern, pass nullptr to dashPattern and zero to cnt.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
dashPattern – [in] The array of consecutive pair values of the dash length and the gap length.
cnt – [in] The size of the dashPattern array.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument and cnt > 0, the given length of the array is less than two or any of the dashPattern values is zero or less.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_dash(const Tvg_Paint *paint, const float **dashPattern, uint32_t *cnt)

Gets the dash pattern of the stroke.

The function does not allocate any memory.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
dashPattern – [out] The array of consecutive pair values of the dash length and the gap length.
cnt – [out] The size of the dashPattern array.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_cap(Tvg_Paint *paint, Tvg_Stroke_Cap cap)

Sets the cap style used for stroking the path.

The cap style specifies the shape to be used at the end of the open stroked sub-paths.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cap – [in] The cap style value. The default value is TVG_STROKE_CAP_SQUARE.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_cap(const Tvg_Paint *paint, Tvg_Stroke_Cap *cap)

Gets the stroke cap style used for stroking the path.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
cap – [out] The cap style value.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_join(Tvg_Paint *paint, Tvg_Stroke_Join join)

Sets the join style for stroked path segments.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
join – [in] The join style value. The default value is TVG_STROKE_JOIN_BEVEL.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_join(const Tvg_Paint *paint, Tvg_Stroke_Join *join)

The function gets the stroke join method.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
join – [out] The join style value.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_miterlimit(Tvg_Paint *paint, float miterlimit)

Sets the stroke miterlimit.

Since: 0.11

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
miterlimit – [in] The miterlimit imposes a limit on the extent of the stroke join when the TVG_STROKE_JOIN_MITER join style is set. The default value is 4.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer or Unsupported miterlimit values (less than zero).

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_stroke_miterlimit(const Tvg_Paint *paint, float *miterlimit)

The function gets the stroke miterlimit.

Since: 0.11

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
miterlimit – [out] The stroke miterlimit.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_stroke_trim(Tvg_Paint *paint, float begin, float end, bool simultaneous)

Sets the trim of the stroke along the defined path segment, allowing control over which part of the stroke is visible.

If the values of the arguments begin and end exceed the 0-1 range, they are wrapped around in a manner similar to angle wrapping, effectively treating the range as circular.

Note

Experimental API

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
begin – [in] Specifies the start of the segment to display along the path.
end – [in] Specifies the end of the segment to display along the path.
simultaneous – [in] Determines how to trim multiple paths within a single shape. If set to true (default), trimming is applied simultaneously to all paths; Otherwise, all paths are treated as a single entity with a combined length equal to the sum of their individual lengths and are trimmed as such.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_fill_color(Tvg_Paint *paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)

Sets the shape's solid color.

The parts of the shape defined as inner are colored.

See also

tvg_shape_set_fill_rule()

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
r – [in] The red color channel value in the range [0 ~ 255]. The default value is 0.
g – [in] The green color channel value in the range [0 ~ 255]. The default value is 0.
b – [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.
a – [in] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_fill_color(const Tvg_Paint *paint, uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a)

Gets the shape's solid color.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
r – [out] The red color channel value in the range [0 ~ 255]. The default value is 0.
g – [out] The green color channel value in the range [0 ~ 255]. The default value is 0.
b – [out] The blue color channel value in the range [0 ~ 255]. The default value is 0.
a – [out] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint *paint, Tvg_Fill_Rule rule)

Sets the shape's fill rule.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
rule – [in] The fill rule value. The default value is TVG_FILL_RULE_WINDING.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_fill_rule(const Tvg_Paint *paint, Tvg_Fill_Rule *rule)

Gets the shape's fill rule.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
rule – [out] shape's fill rule

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_paint_order(Tvg_Paint *paint, bool strokeFirst)

Sets the rendering order of the stroke and the fill.

Since: 0.10

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
strokeFirst – [in] If true the stroke is rendered before the fill, otherwise the stroke is rendered as the second one (the default option).

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)

Sets the linear gradient fill for all of the figures from the path.

The parts of the shape defined as inner are filled.

Tvg_Gradient* grad = tvg_linear_gradient_new();
tvg_linear_gradient_set(grad, 700, 700, 800, 800);
Tvg_Color_Stop color_stops[4] =
{
  {0.0 , 0,   0,   0,   255},
  {0.25, 255, 0,   0,   255},
  {0.5 , 0,   255, 0,   255},
  {1.0 , 0,   0,   255, 255}
};
tvg_gradient_set_color_stops(grad, color_stops, 4);
tvg_shape_set_linear_gradient(shape, grad);

See also

tvg_shape_set_fill_rule()

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [in] The linear gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_MEMORY_CORRUPTION – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)

Sets the radial gradient fill for all of the figures from the path.

The parts of the shape defined as inner are filled.

Tvg_Gradient* grad = tvg_radial_gradient_new();
tvg_radial_gradient_set(grad, 550, 550, 50);
Tvg_Color_Stop color_stops[4] =
{
  {0.0 , 0,   0,   0,   255},
  {0.25, 255, 0,   0,   255},
  {0.5 , 0,   255, 0,   255},
  {1.0 , 0,   0,   255, 255}
};
tvg_gradient_set_color_stops(grad, color_stops, 4);
tvg_shape_set_radial_gradient(shape, grad);

See also

tvg_shape_set_fill_rule()

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [in] The radial gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.
TVG_RESULT_MEMORY_CORRUPTION – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_shape_get_gradient(const Tvg_Paint *paint, Tvg_Gradient **grad)

Gets the gradient fill of the shape.

The function does not allocate any data.

Parameters:

paint – [in] A Tvg_Paint pointer to the shape object.
grad – [out] The gradient fill.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid pointer passed as an argument.

Returns:

Tvg_Result enumeration.

Tvg_Gradient *tvg_linear_gradient_new(void)

Creates a new linear gradient object.

Tvg_Paint* shape = tvg_shape_new();
tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20);
Tvg_Gradient* grad = tvg_linear_gradient_new();
tvg_linear_gradient_set(grad, 700, 700, 800, 800);
Tvg_Color_Stop color_stops[2] =
{
  {0.0, 0, 0,   0, 255},
  {1.0, 0, 255, 0, 255},
};
tvg_gradient_set_color_stops(grad, color_stops, 2);
tvg_shape_set_linear_gradient(shape, grad);

Returns:: A new linear gradient object.

Tvg_Gradient *tvg_radial_gradient_new(void)

Creates a new radial gradient object.

Tvg_Paint* shape = tvg_shape_new();
tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20);
Tvg_Gradient* grad = tvg_radial_gradient_new();
tvg_radial_gradient_set(grad, 550, 550, 50);
Tvg_Color_Stop color_stops[2] =
{
  {0.0, 0, 0,   0, 255},
  {1.0, 0, 255, 0, 255},
};
tvg_gradient_set_color_stops(grad, color_stops, 2);
tvg_shape_set_radial_gradient(shape, grad);

Returns:: A new radial gradient object.

Tvg_Result tvg_linear_gradient_set(Tvg_Gradient *grad, float x1, float y1, float x2, float y2)

Sets the linear gradient bounds.

The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking (x1, y1) and (x2, y2).

See also

tvg_gradient_set_color_stops()

Note

In case the first and the second points are equal, an object is filled with a single color using the last color specified in the tvg_gradient_set_color_stops().

Parameters:

grad – [in] The Tvg_Gradient object of which bounds are to be set.
x1 – [in] The horizontal coordinate of the first point used to determine the gradient bounds.
y1 – [in] The vertical coordinate of the first point used to determine the gradient bounds.
x2 – [in] The horizontal coordinate of the second point used to determine the gradient bounds.
y2 – [in] The vertical coordinate of the second point used to determine the gradient bounds.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_linear_gradient_get(Tvg_Gradient *grad, float *x1, float *y1, float *x2, float *y2)

Gets the linear gradient bounds.

The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking (x1, y1) and (x2, y2).

Parameters:

grad – [in] The Tvg_Gradient object of which to get the bounds.
x1 – [out] The horizontal coordinate of the first point used to determine the gradient bounds.
y1 – [out] The vertical coordinate of the first point used to determine the gradient bounds.
x2 – [out] The horizontal coordinate of the second point used to determine the gradient bounds.
y2 – [out] The vertical coordinate of the second point used to determine the gradient bounds.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_radial_gradient_set(Tvg_Gradient *grad, float cx, float cy, float radius)

Sets the radial gradient bounds.

The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius.

See also

tvg_gradient_set_color_stops()

Note

In case the radius is zero, an object is filled with a single color using the last color specified in the specified in the tvg_gradient_set_color_stops().

Parameters:

grad – [in] The Tvg_Gradient object of which bounds are to be set.
cx – [in] The horizontal coordinate of the center of the bounding circle.
cy – [in] The vertical coordinate of the center of the bounding circle.
radius – [in] The radius of the bounding circle.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer or the radius value less than zero.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_radial_gradient_get(Tvg_Gradient *grad, float *cx, float *cy, float *radius)

The function gets radial gradient center point ant radius.

Parameters:

grad – [in] The Tvg_Gradient object of which bounds are to be set.
cx – [out] The horizontal coordinate of the center of the bounding circle.
cy – [out] The vertical coordinate of the center of the bounding circle.
radius – [out] The radius of the bounding circle.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_set_color_stops(Tvg_Gradient *grad, const Tvg_Color_Stop *color_stop, uint32_t cnt)

Sets the parameters of the colors of the gradient and their position.

Parameters:

grad – [in] The Tvg_Gradient object of which the color information is to be set.
color_stop – [in] An array of Tvg_Color_Stop data structure.
cnt – [in] The size of the color_stop array equal to the colors number used in the gradient.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_get_color_stops(const Tvg_Gradient *grad, const Tvg_Color_Stop **color_stop, uint32_t *cnt)

Gets the parameters of the colors of the gradient, their position and number.

The function does not allocate any memory.

Parameters:

grad – [in] The Tvg_Gradient object of which to get the color information.
color_stop – [out] An array of Tvg_Color_Stop data structure.
cnt – [out] The size of the color_stop array equal to the colors number used in the gradient.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_set_spread(Tvg_Gradient *grad, const Tvg_Stroke_Fill spread)

Sets the Tvg_Stroke_Fill value, which specifies how to fill the area outside the gradient bounds.

Parameters:

grad – [in] The Tvg_Gradient object.
spread – [in] The FillSpread value.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_get_spread(const Tvg_Gradient *grad, Tvg_Stroke_Fill *spread)

Gets the FillSpread value of the gradient object.

Parameters:

grad – [in] The Tvg_Gradient object.
spread – [out] The FillSpread value.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_set_transform(Tvg_Gradient *grad, const Tvg_Matrix *m)

Sets the matrix of the affine transformation for the gradient object.

The augmented matrix of the transformation is expected to be given.

Parameters:

grad – [in] The Tvg_Gradient object to be transformed.
m – [in] The 3x3 augmented matrix.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_get_transform(const Tvg_Gradient *grad, Tvg_Matrix *m)

Gets the matrix of the affine transformation of the gradient object.

In case no transformation was applied, the identity matrix is set.

Parameters:

grad – [in] The Tvg_Gradient object of which to get the transformation matrix.
m – [out] The 3x3 augmented matrix.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_get_type(const Tvg_Gradient *grad, Tvg_Type *type)

Gets the unique value of the gradient instance indicating the instance type.

Note

Experimental API

Parameters:

grad – [in] The Tvg_Gradient object of which to get the type value.
type – [out] The unique type of the gradient instance type.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_gradient_get_identifier(const Tvg_Gradient *grad, Tvg_Identifier *identifier)

See also

tvg_gradient_get_type()

Tvg_Gradient *tvg_gradient_duplicate(Tvg_Gradient *grad)

Duplicates the given Tvg_Gradient object.

Creates a new object and sets its all properties as in the original object.

Parameters:: grad – [in] The Tvg_Gradient object to be copied.
Returns:: A copied Tvg_Gradient object if succeed, nullptr otherwise.

Tvg_Result tvg_gradient_del(Tvg_Gradient *grad)

Deletes the given gradient object.

Parameters:: grad – [in] The gradient object to be deleted.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Gradient pointer.
Returns:: Tvg_Result enumeration.

Tvg_Paint *tvg_picture_new(void)

Creates a new picture object.

Returns:: A new picture object.

Tvg_Result tvg_picture_load(Tvg_Paint *paint, const char *path)

Loads a picture data directly from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded picture data.

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
path – [in] The absolute path to the image file.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer or an empty path.
TVG_RESULT_NOT_SUPPORTED – A file with an unknown extension.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_picture_load_raw(Tvg_Paint *paint, uint32_t *data, uint32_t w, uint32_t h, bool copy)

Loads a picture data from a memory block of a given size.

ThorVG efficiently caches the loaded data using the specified data address as a key when the copy has false. This means that loading the same data again will not result in duplicate operations for the sharable data. Instead, ThorVG will reuse the previously loaded picture data.

Since: 0.9

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
data – [in] A pointer to a memory location where the content of the picture raw data is stored.
w – [in] The width of the image data in pixels.
h – [in] The height of the image data in pixels.
premultiplied – [in] If true, the given image data is alpha-premultiplied.
copy – [in] If true the data are copied into the engine local buffer, otherwise they are not.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer or no data are provided or the width or height value is zero or less.
TVG_RESULT_FAILED_ALLOCATION – A problem with memory allocation occurs.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_picture_load_data(Tvg_Paint *paint, const char *data, uint32_t size, const char *mimetype, bool copy)

Loads a picture data from a memory block of a given size.

ThorVG efficiently caches the loaded data using the specified data address as a key when the copy has false. This means that loading the same data again will not result in duplicate operations for the sharable data. Instead, ThorVG will reuse the previously loaded picture data.

Warning

: It's the user responsibility to release the data memory if the copy is true.

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
data – [in] A pointer to a memory location where the content of the picture file is stored. A null-terminated string is expected for non-binary data if copy is false
size – [in] The size in bytes of the memory occupied by the data.
mimetype – [in] Mimetype or extension of data such as "jpg", "jpeg", "svg", "svg+xml", "lottie", "png", etc. In case an empty string or an unknown type is provided, the loaders will be tried one by one.
copy – [in] If true the data are copied into the engine local buffer, otherwise they are not.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument or the size is zero or less.
TVG_RESULT_NOT_SUPPORTED – A file with an unknown extension.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_picture_set_size(Tvg_Paint *paint, float w, float h)

Resizes the picture content to the given width and height.

The picture content is resized while keeping the default size aspect ratio. The scaling factor is established for each of dimensions and the smaller value is applied to both of them.

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
w – [in] A new width of the image in pixels.
h – [in] A new height of the image in pixels.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_picture_get_size(const Tvg_Paint *paint, float *w, float *h)

Gets the size of the loaded picture.

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
w – [out] A width of the image in pixels.
h – [out] A height of the image in pixels.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

const Tvg_Paint *tvg_picture_get_paint(Tvg_Paint *paint, uint32_t id)

Retrieve a paint object from the Picture scene by its Unique ID.

This function searches for a paint object within the Picture scene that matches the provided id.

See also

tvg_accessor_generate_id()

Note

experimental API

Parameters:

paint – [in] A Tvg_Paint pointer to the picture object.
id – [in] The Unique ID of the paint object.

Returns:

A pointer to the paint object that matches the given identifier, or nullptr if no matching paint object is found.

Tvg_Paint *tvg_scene_new(void)

Creates a new scene object.

A scene object is used to group many paints into one object, which can be manipulated using TVG APIs.

Returns:: A new scene object.

Tvg_Result tvg_scene_reserve(Tvg_Paint *scene, uint32_t size)

Sets the size of the container, where all the paints pushed into the scene are stored.

If the number of objects pushed into the scene is known in advance, calling the function prevents multiple memory reallocation, thus improving the performance.

Parameters:

scene – [in] A Tvg_Paint pointer to the scene object.
size – [in] The number of objects for which the memory is to be reserved.

Return values:

TVG_RESULT_FAILED_ALLOCATION – An internal error with a memory allocation.
TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Paint pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_scene_push(Tvg_Paint *scene, Tvg_Paint *paint)

Passes drawing elements to the scene using Tvg_Paint objects.

Only the paints pushed into the scene will be the drawn targets. The paints are retained by the scene until the tvg_scene_clear() is called. If you know the number of pushed objects in advance, please call tvg_scene_reserve().

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.

Parameters:

scene – [in] A Tvg_Paint pointer to the scene object.
paint – [in] A graphical object to be drawn.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_scene_clear(Tvg_Paint *scene, bool free)

Clears a scene objects from pushed paints.

Tvg_Paint objects stored in the scene 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.

Warning

Please use the free argument only when you know how it works, otherwise it's not recommended.

Parameters:

scene – [in] The scene object to be cleared.
free – [in] If true the memory occupied by paints is deallocated, otherwise it is not.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Canvas pointer.

Returns:

Tvg_Result enumeration.

Tvg_Paint *tvg_text_new(void)

Creates a new text object.

Since: 0.15

Returns:: A new text object.

Tvg_Result tvg_text_set_font(Tvg_Paint *paint, const char *name, float size, const char *style)

Sets the font properties for the text.

This function allows you to define the font characteristics used for text rendering. It sets the font name, size and optionally the style.

Note

Experimental API

Parameters:

paint – [in] A Tvg_Paint pointer to the text object.
name – [in] The name of the font. This should correspond to a font available in the canvas.
size – [in] The size of the font in points.
style – [in] The style of the font. If empty, the default style is used. Currently only 'italic' style is supported.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the paint argument.
TVG_RESULT_INSUFFICIENT_CONDITION – The specified name cannot be found.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_text_set_text(Tvg_Paint *paint, const char *text)

Assigns the given unicode text to be rendered.

This function sets the unicode text that will be displayed by the rendering system. The text is set according to the specified UTF encoding method, which defaults to UTF-8.

Note

Experimental API

Parameters:

paint – [in] A Tvg_Paint pointer to the text object.
text – [in] The multi-byte text encoded with utf8 string to be rendered.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the paint argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_text_set_fill_color(Tvg_Paint *paint, uint8_t r, uint8_t g, uint8_t b)

Sets the text solid color.

See also

tvg_text_set_font()

Since: 0.15

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the text object.
r – [in] The red color channel value in the range [0 ~ 255]. The default value is 0.
g – [in] The green color channel value in the range [0 ~ 255]. The default value is 0.
b – [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the paint argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_text_set_gradient(Tvg_Paint *paint, Tvg_Gradient *gradient)

Sets the gradient fill for the text.

See also

tvg_text_set_font()

Since: 0.15

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

paint – [in] A Tvg_Paint pointer to the text object.
grad – [in] The linear or radial gradient fill

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the paint argument.
TVG_RESULT_MEMORY_CORRUPTION – An invalid Tvg_Gradient pointer.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_font_load(const char *path)

Loads a scalable font data from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded font data.

See also

tvg_font_unload()

Since: 0.15

Parameters:

path – [in] The path to the font file.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid path passed as an argument.
TVG_RESULT_NOT_SUPPORTED – When trying to load a file with an unknown extension.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_font_load_data(const char *name, const char *data, uint32_t size, const char *mimetype, bool copy)

Loads a scalable font data from a memory block of a given size.

ThorVG efficiently caches the loaded font data using the specified name as a key. This means that loading the same fonts again will not result in duplicate operations. Instead, ThorVG will reuse the previously loaded font data.

Since: 0.15

Note

To unload the font data loaded using this API, pass the proper name and nullptr as data.

Warning

: It's the user responsibility to release the data memory.

Parameters:

name – [in] The name under which the font will be stored and accessible (e.x. in a tvg_text_set_font API).
data – [in] A pointer to a memory location where the content of the font data is stored.
size – [in] The size in bytes of the memory occupied by the data.
mimetype – [in] Mimetype or extension of font data. In case a NULL or an empty "" value is provided the loader will be determined automatically.
copy – [in] If true the data are copied into the engine local buffer, otherwise they are not (default).

Return values:

TVG_RESULT_INVALID_ARGUMENT – If no name is provided or if size is zero while data points to a valid memory location.
TVG_RESULT_NOT_SUPPORTED – When trying to load a file with an unknown extension.
TVG_RESULT_INSUFFICIENT_CONDITION – When trying to unload the font data that has not been previously loaded.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_font_unload(const char *path)

Unloads the specified scalable font data that was previously loaded.

This function is used to release resources associated with a font file that has been loaded into memory.

See also

tvg_font_load()

Since: 0.15

Note

If the font data is currently in use, it will not be immediately unloaded.

Parameters:: path – [in] The path to the loaded font file.
Return values:: TVG_RESULT_INSUFFICIENT_CONDITION – The loader is not initialized.
Returns:: Tvg_Result enumeration.

Tvg_Saver *tvg_saver_new(void)

Creates a new Tvg_Saver object.

Returns:: A new Tvg_Saver object.

Tvg_Result tvg_saver_save(Tvg_Saver *saver, Tvg_Paint *paint, const char *path, bool compress)

Exports the given paint data to the given path.

If the saver module supports any compression mechanism, it will optimize the data size. This might affect the encoding/decoding time in some cases. You can turn off the compression if you wish to optimize for speed.

See also

tvg_saver_sync()

Note

Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call tvg_saver_sync() afterwards.

Parameters:

saver – [in] The Tvg_Saver object connected with the saving task.
paint – [in] The paint to be saved with all its associated properties.
path – [in] A path to the file, in which the paint data is to be saved.
compress – [in] If true then compress data if possible.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.
TVG_RESULT_INSUFFICIENT_CONDITION – Currently saving other resources.
TVG_RESULT_NOT_SUPPORTED – Trying to save a file with an unknown extension or in an unsupported format.
TVG_RESULT_UNKNOWN – An empty paint is to be saved.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_saver_sync(Tvg_Saver *saver)

Guarantees that the saving task is finished.

The behavior of the Saver module works on a sync/async basis, depending on the threading setting of the Initializer. Thus, if you wish to have a benefit of it, you must call tvg_saver_sync() after the tvg_saver_save() in the proper delayed time. Otherwise, you can call tvg_saver_sync() immediately.

See also

tvg_saver_save()

Note

The asynchronous tasking is dependent on the Saver module implementation.

Parameters:

saver – [in] The Tvg_Saver object connected with the saving task.

Return values:

TVG_RESULT_INVALID_ARGUMENT – A nullptr passed as the argument.
TVG_RESULT_INSUFFICIENT_CONDITION – No saving task is running.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_saver_del(Tvg_Saver *saver)

Deletes the given Tvg_Saver object.

Parameters:: saver – [in] The Tvg_Saver object to be deleted.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Saver pointer.
Returns:: Tvg_Result enumeration.

Tvg_Animation *tvg_animation_new(void)

Creates a new Animation object.

Since: 0.13

Returns:: Tvg_Animation A new Tvg_Animation object.

Tvg_Result tvg_animation_set_frame(Tvg_Animation *animation, float no)

Specifies the current frame in the animation.

See also

tvg_animation_get_total_frame()

Since: 0.13

Note

For efficiency, ThorVG ignores updates to the new frame value if the difference from the current frame value is less than 0.001. In such cases, it returns Result::InsufficientCondition. Values less than 0.001 may be disregarded and may not be accurately retained by the Animation.

Parameters:

animation – [in] A Tvg_Animation pointer to the animation object.
no – [in] The index of the animation frame to be displayed. The index should be less than the tvg_animation_get_total_frame().

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Animation pointer.
TVG_RESULT_INSUFFICIENT_CONDITION – if the given no is the same as the current frame value.
TVG_RESULT_NOT_SUPPORTED – The picture data does not support animations.

Returns:

Tvg_Result enumeration.

Tvg_Paint *tvg_animation_get_picture(Tvg_Animation *animation)

Retrieves a picture instance associated with this animation instance.

This function provides access to the picture instance that can be used to load animation formats, such as Lottie(json). After setting up the picture, it can be pushed to the designated canvas, enabling control over animation frames with this Animation instance.

Since: 0.13

Warning

The picture instance is owned by Animation. It should not be deleted manually.

Parameters:: animation – [in] A Tvg_Animation pointer to the animation object.
Returns:: A picture instance that is tied to this animation.

Tvg_Result tvg_animation_get_frame(Tvg_Animation *animation, float *no)

Retrieves the current frame number of the animation.

See also

tvg_animation_get_total_frame()

See also

tvg_animation_set_frame()

Since: 0.13

Parameters:

animation – [in] A Tvg_Animation pointer to the animation object.
no – [in] The current frame number of the animation, between 0 and totalFrame() - 1.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Animation pointer or no

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_animation_get_total_frame(Tvg_Animation *animation, float *cnt)

Retrieves the total number of frames in the animation.

Since: 0.13

Note

Frame numbering starts from 0.

Note

If the Picture is not properly configured, this function will return 0.

Parameters:

animation – [in] A Tvg_Animation pointer to the animation object.
cnt – [in] The total number of frames in the animation.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Animation pointer or cnt.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_animation_get_duration(Tvg_Animation *animation, float *duration)

Retrieves the duration of the animation in seconds.

Since: 0.13

Note

If the Picture is not properly configured, this function will return 0.

Parameters:

animation – [in] A Tvg_Animation pointer to the animation object.
duration – [in] The duration of the animation in seconds.

Return values:

TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Animation pointer or duration.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_animation_set_segment(Tvg_Animation *animation, float begin, float end)

Specifies the playback segment of the animation.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation pointer to the animation object.
begin – [in] segment begin.
end – [in] segment end.

Return values:

TVG_RESULT_INSUFFICIENT_CONDITION – In case the animation is not loaded.
TVG_RESULT_INVALID_ARGUMENT – When the given parameters are out of range.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_animation_get_segment(Tvg_Animation *animation, float *begin, float *end)

Gets the current segment.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation pointer to the animation object.
begin – [out] segment begin.
end – [out] segment end.

Return values:

TVG_RESULT_INSUFFICIENT_CONDITION – In case the animation is not loaded.
TVG_RESULT_INVALID_ARGUMENT – When the given parameters are nullptr.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_animation_del(Tvg_Animation *animation)

Deletes the given Tvg_Animation object.

Since: 0.13

Parameters:: animation – [in] The Tvg_Animation object to be deleted.
Return values:: TVG_RESULT_INVALID_ARGUMENT – An invalid Tvg_Animation pointer.
Returns:: Tvg_Result enumeration.

uint32_t tvg_accessor_generate_id(const char *name)

Generate a unique ID (hash key) from a given name.

This function computes a unique identifier value based on the provided string. You can use this to assign a unique ID to the Paint object.

Note

Experimental API

Parameters:: name – [in] The input string to generate the unique identifier from.
Returns:: The generated unique identifier value.

Tvg_Animation *tvg_lottie_animation_new(void)

Creates a new LottieAnimation object.

Since: 0.15

Returns:: Tvg_Animation A new Tvg_LottieAnimation object.

Tvg_Result tvg_lottie_animation_override(Tvg_Animation *animation, const char *slot)

Override the lottie properties through the slot data.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation object to override the property with the slot.
slot – [in] The Lottie slot data in json, or nullptr to reset.

Return values:

TVG_RESULT_INSUFFICIENT_CONDITION – In case the animation is not loaded.
TVG_RESULT_INVALID_ARGUMENT – When the given slot is invalid
TVG_RESULT_NOT_SUPPORTED – The Lottie Animation is not supported.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_lottie_animation_set_marker(Tvg_Animation *animation, const char *marker)

Specifies a segment by marker.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation pointer to the Lottie animation object.
marker – [in] The name of the segment marker.

Return values:

TVG_RESULT_INSUFFICIENT_CONDITION – In case the animation is not loaded.
TVG_RESULT_INVALID_ARGUMENT – When the given marker is invalid.
TVG_RESULT_NOT_SUPPORTED – The Lottie Animation is not supported.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_lottie_animation_get_markers_cnt(Tvg_Animation *animation, uint32_t *cnt)

Gets the marker count of the animation.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation pointer to the Lottie animation object.
cnt – [out] The count value of the markers.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case a nullptr is passed as the argument.

Returns:

Tvg_Result enumeration.

Tvg_Result tvg_lottie_animation_get_marker(Tvg_Animation *animation, uint32_t idx, const char **name)

Gets the marker name by a given index.

Note

Experimental API

Parameters:

animation – [in] The Tvg_Animation pointer to the Lottie animation object.
idx – [in] The index of the animation marker, starts from 0.
name – [out] The name of marker when succeed.

Return values:

TVG_RESULT_INVALID_ARGUMENT – In case nullptr is passed as the argument or idx is out of range.

Returns:

Tvg_Result enumeration.

struct Tvg_Color_Stop

#include <thorvg_capi.h>

A data structure storing the information about the color and its relative position inside the gradient bounds.

Public Members

float offset: The relative position of the color.

uint8_t r: The red color channel value in the range [0 ~ 255].

uint8_t g: The green color channel value in the range [0 ~ 255].

uint8_t b: The blue color channel value in the range [0 ~ 255].

uint8_t a: The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

struct Tvg_Point

#include <thorvg_capi.h>

A data structure representing a point in two-dimensional space.

Public Members

float x

float y

struct Tvg_Matrix

#include <thorvg_capi.h>

A data structure representing a three-dimensional matrix.

The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor. The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively. The elements e31 and e32 are set to 0, e33 is set to 1.

Public Members

float e11

float e12

float e13

float e21

float e22

float e23

float e31

float e32

float e33