Paint

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_set_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_get_transform (Tvg_Paint *paint, Tvg_Matrix *m)
	Gets the matrix of the affine transformation of the given Tvg_Paint object. 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 (const 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, bool transformed)
	Gets the axis-aligned bounding box of the Tvg_Paint object. (BETA_API) 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...
TVG_EXPORT 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...

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,
		bool	transformed
	)

Gets the axis-aligned bounding box of the Tvg_Paint object. (BETA_API)

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

TVG_EXPORT 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_EXPORT 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_EXPORT 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_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_set_transform()

TVG_EXPORT 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_EXPORT 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.