Paint
ThorVG_CAPI (BETA version)

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 }
| Enumeration indicating the method used in the composition of two objects - the target and the source. More...

## Functions

TVG_EXPORT Tvg_Result | tvg_paint_del (Tvg_Paint *paint)
| Releases the given Tvg_Paint object. More...
TVG_EXPORT Tvg_Result | tvg_paint_scale (Tvg_Paint *paint, float factor)
| Scales the given Tvg_Paint object by the given factor. More...
TVG_EXPORT Tvg_Result | tvg_paint_rotate (Tvg_Paint *paint, float degree)
| Rotates the given Tvg_Paint by the given angle. More...
TVG_EXPORT Tvg_Result | tvg_paint_translate (Tvg_Paint *paint, float x, float y)
| Moves the given Tvg_Paint in a two-dimensional space. More...
TVG_EXPORT Tvg_Result | tvg_paint_transform (Tvg_Paint *paint, const Tvg_Matrix *m)
| Transforms the given Tvg_Paint using the augmented transformation matrix. More...
TVG_EXPORT Tvg_Result | tvg_paint_set_opacity (Tvg_Paint *paint, uint8_t opacity)
| Sets the opacity of the given Tvg_Paint. More...
TVG_EXPORT Tvg_Result | tvg_paint_get_opacity (Tvg_Paint *paint, uint8_t *opacity)
| Gets the opacity of the given Tvg_Paint. More...
TVG_EXPORT Tvg_Paint * | tvg_paint_duplicate (Tvg_Paint *paint)
| Duplicates the given Tvg_Paint object. More...
TVG_EXPORT Tvg_Result | tvg_paint_get_bounds (const Tvg_Paint *paint, float *x, float *y, float *w, float *h)
| Gets the bounding box of the Tvg_Paint object before any transformation. More...
TVG_EXPORT 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...

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

## Function Documentation

## tvg_paint_del()

TVG_EXPORT 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;
}

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_EXPORT 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_EXPORT Tvg_Result tvg_paint_get_bounds | ( | const Tvg_Paint * | paint,
|  | float * | x,
|  | float * | y,
|  | float * | w,
|  | float * | h
| ) |  |

Gets the bounding box of the Tvg_Paint object before any transformation.

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.

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.

## tvg_paint_get_opacity()

TVG_EXPORT Tvg_Result tvg_paint_get_opacity | ( | 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_rotate()

TVG_EXPORT Tvg_Result tvg_paint_rotate | ( | Tvg_Paint * | paint,
|  | float | degree
| ) |  |

Rotates the given Tvg_Paint by the given angle.

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_EXPORT 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_EXPORT 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_EXPORT 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_transform()

TVG_EXPORT Tvg_Result tvg_paint_transform | ( | Tvg_Paint * | paint,
|  | const Tvg_Matrix * | m
| ) |  |

Transforms the given Tvg_Paint using the augmented transformation matrix.

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 | An invalid Tvg_Paint pointer.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with memory allocation.

## tvg_paint_translate()

TVG_EXPORT Tvg_Result tvg_paint_translate | ( | Tvg_Paint * | paint,
|  | float | x,
|  | float | y
| ) |  |

Moves the given Tvg_Paint in a two-dimensional space.

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.