| ThorVG v0.9

Enumerations | Functions
Paint
ThorVG_CAPI

A module for managing graphical elements. It enables duplication, transformation and composition. More...

Collaboration diagram for Paint:

## Enumerations
enum | Tvg_Composite_Method { TVG_COMPOSITE_METHOD_NONE = 0 , TVG_COMPOSITE_METHOD_CLIP_PATH , TVG_COMPOSITE_METHOD_ALPHA_MASK , TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK , TVG_COMPOSITE_METHOD_LUMA_MASK }
| Enumeration indicating the method used in the composition of two objects - the target and the source. More...
enum | Tvg_Identifier { TVG_IDENTIFIER_UNDEF = 0 , TVG_IDENTIFIER_SHAPE , TVG_IDENTIFIER_SCENE , TVG_IDENTIFIER_PICTURE , TVG_IDENTIFIER_LINEAR_GRAD , TVG_IDENTIFIER_RADIAL_GRAD }
| Enumeration indicating the ThorVG class type. More...

## Functions
TVG_API Tvg_Result | tvg_paint_del (Tvg_Paint *paint)
| Releases the given Tvg_Paint object. More...
TVG_API Tvg_Result | tvg_paint_scale (Tvg_Paint *paint, float factor)
| Scales the given Tvg_Paint object by the given factor. More...
TVG_API Tvg_Result | tvg_paint_rotate (Tvg_Paint *paint, float degree)
| Rotates the given Tvg_Paint by the given angle. More...
TVG_API Tvg_Result | tvg_paint_translate (Tvg_Paint *paint, float x, float y)
| Moves the given Tvg_Paint in a two-dimensional space. More...
TVG_API Tvg_Result | tvg_paint_set_transform (Tvg_Paint *paint, const Tvg_Matrix *m)
| Transforms the given Tvg_Paint using the augmented transformation matrix. More...
TVG_API 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. More...
TVG_API Tvg_Result | tvg_paint_set_opacity (Tvg_Paint *paint, uint8_t opacity)
| Sets the opacity of the given Tvg_Paint. More...
TVG_API Tvg_Result | tvg_paint_get_opacity (const Tvg_Paint *paint, uint8_t *opacity)
| Gets the opacity of the given Tvg_Paint. More...
TVG_API Tvg_Paint * | tvg_paint_duplicate (Tvg_Paint *paint)
| Duplicates the given Tvg_Paint object. More...
TVG_API 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. More...
TVG_API 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. More...
TVG_API 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. More...
TVG_API Tvg_Result | tvg_paint_get_identifier (const Tvg_Paint *paint, Tvg_Identifier *identifier)
| Gets the unique id value of the paint instance indicating the instance type. More...

## Detailed Description

A module for managing graphical elements. It enables duplication, transformation and composition.

## Enumeration Type Documentation

## ◆ Tvg_Composite_Method

enum Tvg_Composite_Method

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

Enumerator
TVG_COMPOSITE_METHOD_NONE | No composition is applied.
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.
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.
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.
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

## ◆ Tvg_Identifier

enum Tvg_Identifier

Enumeration indicating the ThorVG class type.

Since
  0.9

Enumerator
TVG_IDENTIFIER_UNDEF | Undefined type.
TVG_IDENTIFIER_SHAPE | A shape type paint.
TVG_IDENTIFIER_SCENE | A scene type paint.
TVG_IDENTIFIER_PICTURE | A picture type paint.
TVG_IDENTIFIER_LINEAR_GRAD | A linear gradient type.
TVG_IDENTIFIER_RADIAL_GRAD | A radial gradient type.

## Function Documentation

## ◆ tvg_paint_del()

TVG_API 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;
}
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 obj...
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 th...
tvg_paint_del
TVG_API Tvg_Result tvg_paint_del(Tvg_Paint *paint)
Releases the given Tvg_Paint object.
Tvg_Paint
struct _Tvg_Paint Tvg_Paint
A structure representing a graphical element.
Definition: thorvg_capi.h:77

Parameters

  [in] | paint | The Tvg_Paint object to be released.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

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.

See also
  tvg_canvas_clear(), tvg_canvas_destroy()

## ◆ tvg_paint_duplicate()

TVG_API 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

  [in] | paint | The Tvg_Paint object to be copied.

Returns
  A copied Tvg_Paint object if succeed, `nullptr` otherwise.

## ◆ tvg_paint_get_bounds()

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

Parameters

  [in] | paint | The Tvg_Paint object of which to get the bounds.
  [out] | x | The x coordinate of the upper left corner of the object.
  [out] | y | The y coordinate of the upper left corner of the object.
  [out] | w | The width of the object.
  [out] | h | The height of the object.
  [in] | transformed | If `true`, the transformation of the paint is taken into account, otherwise it isn't.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_INSUFFICIENT_CONDITION | Other errors.

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

## ◆ tvg_paint_get_composite_method()

TVG_API 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

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` is passed as the argument.

## ◆ tvg_paint_get_identifier()

TVG_API Tvg_Result tvg_paint_get_identifier | ( | const Tvg_Paint * | paint,
|  | Tvg_Identifier * | identifier
| ) |  |

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

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

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

Since
  0.9

## ◆ tvg_paint_get_opacity()

TVG_API Tvg_Result tvg_paint_get_opacity | ( | const Tvg_Paint * | paint,
|  | uint8_t * | opacity
| ) |  |

Gets the opacity of the given Tvg_Paint.

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

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

## ◆ tvg_paint_get_transform()

TVG_API 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

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` is passed as the argument.

## ◆ tvg_paint_rotate()

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

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with memory allocation.

## ◆ tvg_paint_scale()

TVG_API Tvg_Result tvg_paint_scale | ( | Tvg_Paint * | paint,
|  | float | factor
| ) |  |

Scales the given Tvg_Paint object by the given factor.

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with memory allocation.

## ◆ tvg_paint_set_composite_method()

TVG_API 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

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid `paint` or `target` object or the `method` equal to TVG_COMPOSITE_METHOD_NONE.

## ◆ tvg_paint_set_opacity()

TVG_API Tvg_Result tvg_paint_set_opacity | ( | Tvg_Paint * | paint,
|  | uint8_t | opacity
| ) |  |

Sets the opacity of the given Tvg_Paint.

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

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

## ◆ tvg_paint_set_transform()

TVG_API 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

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` is passed as the argument.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with memory allocation.

## ◆ tvg_paint_translate()

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

Parameters

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

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with memory allocation.