Gradient

A module managing the gradient fill of objects. More...

Collaboration diagram for Gradient:

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

Functions
TVG_API Tvg_Gradient *	tvg_linear_gradient_new ()
	Creates a new linear gradient object. More...
TVG_API Tvg_Gradient *	tvg_radial_gradient_new ()
	Creates a new radial gradient object. More...
TVG_API Tvg_Result	tvg_linear_gradient_set (Tvg_Gradient *grad, float x1, float y1, float x2, float y2)
	Sets the linear gradient bounds. More...
TVG_API Tvg_Result	tvg_linear_gradient_get (Tvg_Gradient *grad, float *x1, float *y1, float *x2, float *y2)
	Gets the linear gradient bounds. More...
TVG_API Tvg_Result	tvg_radial_gradient_set (Tvg_Gradient *grad, float cx, float cy, float radius)
	Sets the radial gradient bounds. More...
TVG_API Tvg_Result	tvg_radial_gradient_get (Tvg_Gradient *grad, float *cx, float *cy, float *radius)
	The function gets radial gradient center point ant radius. More...
TVG_API 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. More...
TVG_API 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. More...
TVG_API 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. More...
TVG_API Tvg_Result	tvg_gradient_get_spread (const Tvg_Gradient *grad, Tvg_Stroke_Fill *spread)
	Gets the FillSpread value of the gradient object. More...
TVG_API Tvg_Result	tvg_gradient_set_transform (Tvg_Gradient *grad, const Tvg_Matrix *m)
	Sets the matrix of the affine transformation for the gradient object. More...
TVG_API Tvg_Result	tvg_gradient_get_transform (const Tvg_Gradient *grad, Tvg_Matrix *m)
	Gets the matrix of the affine transformation of the gradient object. More...
TVG_API Tvg_Result	tvg_gradient_get_identifier (const Tvg_Gradient *grad, Tvg_Identifier *identifier)
	Gets the unique id value of the gradient instance indicating the instance type. More...
TVG_API Tvg_Gradient *	tvg_gradient_duplicate (Tvg_Gradient *grad)
	Duplicates the given Tvg_Gradient object. More...
TVG_API Tvg_Result	tvg_gradient_del (Tvg_Gradient *grad)
	Deletes the given gradient object. More...

Detailed Description

A module managing the gradient fill of objects.

The module enables to set and to get the gradient colors and their arrangement inside the gradient bounds, to specify the gradient bounds and the gradient behavior in case the area defined by the gradient bounds is smaller than the area to be filled.

Function Documentation

tvg_gradient_del()

TVG_API Tvg_Result tvg_gradient_del

(

Tvg_Gradient *

grad

)

Deletes the given gradient object.

Parameters

[in]

grad

The gradient object to be deleted.

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

tvg_gradient_duplicate()

TVG_API 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

[in]

grad

The Tvg_Gradient object to be copied.

Returns

A copied Tvg_Gradient object if succeed, nullptr otherwise.

tvg_gradient_get_color_stops()

TVG_API 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

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	A nullptr passed as the argument.

tvg_gradient_get_identifier()

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

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

Parameters

[in]	grad	The Tvg_Gradient object of which to get the identifier value.
[out]	identifier	The unique identifier of the gradient 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_gradient_get_spread()

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

Gets the FillSpread value of the gradient object.

Parameters

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	A nullptr passed as the argument.

tvg_gradient_get_transform()

TVG_API 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

[in]	grad	The Tvg_Gradient 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_gradient_set_color_stops()

TVG_API 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

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

tvg_gradient_set_spread()

TVG_API 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

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

tvg_gradient_set_transform()

TVG_API 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

[in]	grad	The Tvg_Gradient 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 a memory allocation.

tvg_linear_gradient_get()

TVG_API 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

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

tvg_linear_gradient_new()

TVG_API Tvg_Gradient* tvg_linear_gradient_new

(

)

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

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

Parameters

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

Note

In case the first and the second points are equal, an object filled with such a gradient fill is not rendered.

tvg_radial_gradient_get()

TVG_API 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

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

Returns

Tvg_Result enumeration.

Return values

TVG_RESULT_SUCCESS	Succeed.
TVG_RESULT_INVALID_ARGUMENT	An invalid Tvg_Gradient pointer.

tvg_radial_gradient_new()

TVG_API Tvg_Gradient* tvg_radial_gradient_new

(

)

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

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

Parameters

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

Returns

Tvg_Result enumeration.

Return values

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