Gradient
ThorVG_CAPI (BETA version)

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_EXPORT Tvg_Gradient * | tvg_linear_gradient_new ()
| Creates a new linear gradient object. More...
TVG_EXPORT Tvg_Gradient * | tvg_radial_gradient_new ()
| Creates a new radial gradient object. More...
TVG_EXPORT Tvg_Result | tvg_linear_gradient_set (Tvg_Gradient *grad, float x1, float y1, float x2, float y2)
| Sets the linear gradient bounds. More...
TVG_EXPORT Tvg_Result | tvg_linear_gradient_get (Tvg_Gradient *grad, float *x1, float *y1, float *x2, float *y2)
| Gets the linear gradient bounds. More...
TVG_EXPORT Tvg_Result | tvg_radial_gradient_set (Tvg_Gradient *grad, float cx, float cy, float radius)
| Sets the radial gradient bounds. More...
TVG_EXPORT 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_EXPORT 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_EXPORT Tvg_Result | tvg_gradient_get_color_stops (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_EXPORT 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_EXPORT Tvg_Result | tvg_gradient_get_spread (Tvg_Gradient *grad, Tvg_Stroke_Fill *spread)
| Gets the FillSpread value of the gradient object. More...
TVG_EXPORT 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_EXPORT 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_get_color_stops()

TVG_EXPORT Tvg_Result tvg_gradient_get_color_stops | ( | 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_spread()

TVG_EXPORT Tvg_Result tvg_gradient_get_spread | ( | 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_set_color_stops()

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

TVG_EXPORT 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_EXPORT 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] =
{
{.offset=0, .r=0, .g=0, .b=0, .a=255},
{.offset=1, .r=0, .g=255, .b=0, .a=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_EXPORT 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 or the first and the second points are equal.

## tvg_radial_gradient_get()

TVG_EXPORT 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_EXPORT 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_linear_gradient_set(grad, 550, 550, 50);
Tvg_Color_Stop color_stops[2] =
{
{.offset=0, .r=0, .g=0, .b=0, .a=255},
{.offset=1, .r=0, .g=255, .b=0, .a=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_EXPORT 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.