| ThorVG v0.9

Classes | Functions
Gradient
ThorVG_CAPI

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);
tvg_linear_gradient_new
TVG_API Tvg_Gradient * tvg_linear_gradient_new()
Creates 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.
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.
tvg_shape_append_rect
TVG_API Tvg_Result tvg_shape_append_rect(Tvg_Paint *paint, float x, float y, float w, float h, float rx, float ry)
Appends a rectangle to the path.
tvg_shape_set_linear_gradient
TVG_API Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)
Sets the linear gradient fill for all of the figures from the path.
tvg_shape_new
TVG_API Tvg_Paint * tvg_shape_new()
Creates a new shape object.
Tvg_Paint
struct _Tvg_Paint Tvg_Paint
A structure representing a graphical element.
Definition: thorvg_capi.h:77
Tvg_Gradient
struct _Tvg_Gradient Tvg_Gradient
A structure representing a gradient fill of a Tvg_Paint object.
Definition: thorvg_capi.h:83
Tvg_Color_Stop
A data structure storing the information about the color and its relative position inside the gradien...
Definition: thorvg_capi.h:217

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);
tvg_radial_gradient_new
TVG_API Tvg_Gradient * tvg_radial_gradient_new()
Creates 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.
tvg_shape_set_radial_gradient
TVG_API Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint *paint, Tvg_Gradient *grad)
Sets the radial gradient fill for all of the figures from the path.

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.