| ThorVG v0.8

Enumerations | Functions
Shape
ThorVG_CAPI

A module for managing two-dimensional figures and their properties. More...

Collaboration diagram for Shape:

## Enumerations
enum | Tvg_Path_Command { TVG_PATH_COMMAND_CLOSE = 0, TVG_PATH_COMMAND_MOVE_TO, TVG_PATH_COMMAND_LINE_TO, TVG_PATH_COMMAND_CUBIC_TO }
| Enumeration specifying the values of the path commands accepted by TVG. More...
enum | Tvg_Stroke_Cap { TVG_STROKE_CAP_SQUARE = 0, TVG_STROKE_CAP_ROUND, TVG_STROKE_CAP_BUTT }
| Enumeration determining the ending type of a stroke in the open sub-paths. More...
enum | Tvg_Stroke_Join { TVG_STROKE_JOIN_BEVEL = 0, TVG_STROKE_JOIN_ROUND, TVG_STROKE_JOIN_MITER }
| Enumeration specifying how to fill the area outside the gradient bounds. More...
enum | Tvg_Stroke_Fill { TVG_STROKE_FILL_PAD = 0, TVG_STROKE_FILL_REFLECT, TVG_STROKE_FILL_REPEAT }
| Enumeration specifying how to fill the area outside the gradient bounds. More...
enum | Tvg_Fill_Rule { TVG_FILL_RULE_WINDING = 0, TVG_FILL_RULE_EVEN_ODD }
| Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape. More...

## Functions
TVG_EXPORT Tvg_Paint * | tvg_shape_new ()
| Creates a new shape object. More...
TVG_EXPORT Tvg_Result | tvg_shape_reset (Tvg_Paint *paint)
| Resets the shape path properties. More...
TVG_EXPORT Tvg_Result | tvg_shape_move_to (Tvg_Paint *paint, float x, float y)
| Sets the initial point of the sub-path. More...
TVG_EXPORT Tvg_Result | tvg_shape_line_to (Tvg_Paint *paint, float x, float y)
| Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point. More...
TVG_EXPORT Tvg_Result | tvg_shape_cubic_to (Tvg_Paint *paint, float cx1, float cy1, float cx2, float cy2, float x, float y)
| Adds new points to the sub-path, which results in drawing a cubic Bezier curve. More...
TVG_EXPORT Tvg_Result | tvg_shape_close (Tvg_Paint *paint)
| Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path. More...
TVG_EXPORT 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. More...
TVG_EXPORT Tvg_Result | tvg_shape_append_circle (Tvg_Paint *paint, float cx, float cy, float rx, float ry)
| Appends an ellipse to the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_append_arc (Tvg_Paint *paint, float cx, float cy, float radius, float startAngle, float sweep, uint8_t pie)
| Appends a circular arc to the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_append_path (Tvg_Paint *paint, const Tvg_Path_Command *cmds, uint32_t cmdCnt, const Tvg_Point *pts, uint32_t ptsCnt)
| Appends a given sub-path to the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_path_coords (const Tvg_Paint *paint, const Tvg_Point **pts, uint32_t *cnt)
| Gets the points values of the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_path_commands (const Tvg_Paint *paint, const Tvg_Path_Command **cmds, uint32_t *cnt)
| Gets the commands data of the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_width (Tvg_Paint *paint, float width)
| Sets the stroke width for all of the figures from the `paint`. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_width (const Tvg_Paint *paint, float *width)
| Gets the shape's stroke width. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_color (Tvg_Paint *paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)
| Sets the shape's stroke color. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_color (const Tvg_Paint *paint, uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a)
| Gets the shape's stroke color. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_linear_gradient (Tvg_Paint *paint, Tvg_Gradient *grad)
| Sets the linear gradient fill of the stroke for all of the figures from the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_radial_gradient (Tvg_Paint *paint, Tvg_Gradient *grad)
| Sets the radial gradient fill of the stroke for all of the figures from the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_gradient (const Tvg_Paint *paint, Tvg_Gradient **grad)
| Gets the gradient fill of the shape's stroke. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_dash (Tvg_Paint *paint, const float *dashPattern, uint32_t cnt)
| Sets the shape's stroke dash pattern. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_dash (const Tvg_Paint *paint, const float **dashPattern, uint32_t *cnt)
| Gets the dash pattern of the stroke. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_cap (Tvg_Paint *paint, Tvg_Stroke_Cap cap)
| Sets the cap style used for stroking the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_cap (const Tvg_Paint *paint, Tvg_Stroke_Cap *cap)
| Gets the stroke cap style used for stroking the path. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_stroke_join (Tvg_Paint *paint, Tvg_Stroke_Join join)
| Sets the join style for stroked path segments. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_stroke_join (const Tvg_Paint *paint, Tvg_Stroke_Join *join)
| The function gets the stroke join method. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_fill_color (Tvg_Paint *paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)
| Sets the shape's solid color. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_fill_color (const Tvg_Paint *paint, uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a)
| Gets the shape's solid color. More...
TVG_EXPORT Tvg_Result | tvg_shape_set_fill_rule (Tvg_Paint *paint, Tvg_Fill_Rule rule)
| Sets the shape's fill rule. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_fill_rule (const Tvg_Paint *paint, Tvg_Fill_Rule *rule)
| Gets the shape's fill rule. More...
TVG_EXPORT 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. More...
TVG_EXPORT 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. More...
TVG_EXPORT Tvg_Result | tvg_shape_get_gradient (const Tvg_Paint *paint, Tvg_Gradient **grad)
| Gets the gradient fill of the shape. More...

## Detailed Description

A module for managing two-dimensional figures and their properties.

A shape has three major properties: shape outline, stroking, filling. The outline in the shape is retained as the path. Path can be composed by accumulating primitive commands such as tvg_shape_move_to(), tvg_shape_line_to(), tvg_shape_cubic_to() or complete shape interfaces such as tvg_shape_append_rect(), tvg_shape_append_circle(), etc. Path can consists of sub-paths. One sub-path is determined by a close command.

The stroke of a shape is an optional property in case the shape needs to be represented with/without the outline borders. It's efficient since the shape path and the stroking path can be shared with each other. It's also convenient when controlling both in one context.

## Enumeration Type Documentation

## ◆ Tvg_Fill_Rule

enum Tvg_Fill_Rule

Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape.

Enumerator
TVG_FILL_RULE_WINDING | A line from the point to a location outside the shape is drawn. The intersections of the line with the path segment of the shape are counted. Starting from zero, if the path segment of the shape crosses the line clockwise, one is added, otherwise one is subtracted. If the resulting sum is non zero, the point is inside the shape.
TVG_FILL_RULE_EVEN_ODD | A line from the point to a location outside the shape is drawn and its intersections with the path segments of the shape are counted. If the number of intersections is an odd number, the point is inside the shape.

## ◆ Tvg_Path_Command

enum Tvg_Path_Command

Enumeration specifying the values of the path commands accepted by TVG.

Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). TVG interprets all of them and translates to the ones from the PathCommand values.

Enumerator
TVG_PATH_COMMAND_CLOSE | Ends the current sub-path and connects it with its initial point - corresponds to Z command in the svg path commands.
TVG_PATH_COMMAND_MOVE_TO | Sets a new initial point of the sub-path and a new current point - corresponds to M command in the svg path commands.
TVG_PATH_COMMAND_LINE_TO | Draws a line from the current point to the given point and sets a new value of the current point - corresponds to L command in the svg path commands.
TVG_PATH_COMMAND_CUBIC_TO | Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point - corresponds to C command in the svg path commands.

## ◆ Tvg_Stroke_Cap

enum Tvg_Stroke_Cap

Enumeration determining the ending type of a stroke in the open sub-paths.

Enumerator
TVG_STROKE_CAP_SQUARE | The stroke is extended in both endpoints of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width.
TVG_STROKE_CAP_ROUND | The stroke is extended in both endpoints of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered.
TVG_STROKE_CAP_BUTT | The stroke ends exactly at each of the two endpoints of a sub-path. For zero length sub-paths no stroke is rendered.

## ◆ Tvg_Stroke_Fill

enum Tvg_Stroke_Fill

Enumeration specifying how to fill the area outside the gradient bounds.

Enumerator
TVG_STROKE_FILL_PAD | The remaining area is filled with the closest stop color.
TVG_STROKE_FILL_REFLECT | The gradient pattern is reflected outside the gradient area until the expected region is filled.
TVG_STROKE_FILL_REPEAT | The gradient pattern is repeated continuously beyond the gradient area until the expected region is filled.

## ◆ Tvg_Stroke_Join

enum Tvg_Stroke_Join

Enumeration specifying how to fill the area outside the gradient bounds.

Enumerator
TVG_STROKE_JOIN_BEVEL | The outer corner of the joined path segments is bevelled at the join point. The triangular region of the corner is enclosed by a straight line between the outer corners of each stroke.
TVG_STROKE_JOIN_ROUND | The outer corner of the joined path segments is rounded. The circular region is centered at the join point.
TVG_STROKE_JOIN_MITER | The outer corner of the joined path segments is spiked. The spike is created by extension beyond the join point of the outer edges of the stroke until they intersect. In case the extension goes beyond the limit, the join style is converted to the Bevel style.

## Function Documentation

## ◆ tvg_shape_append_arc()

TVG_EXPORT Tvg_Result tvg_shape_append_arc | ( | Tvg_Paint * | paint,
|  | float | cx,
|  | float | cy,
|  | float | radius,
|  | float | startAngle,
|  | float | sweep,
|  | uint8_t | pie
| ) |  |

Appends a circular arc to the path.

The arc is treated as a new sub-path - it is not connected with the previous sub-path. The current point value is set to the end-point of the arc in case `pie` is `false`, and to the center of the arc otherwise.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | cx | The horizontal coordinate of the center of the arc.
  [in] | cy | The vertical coordinate of the center of the arc.
  [in] | radius | The radius of the arc.
  [in] | startAngle | The start angle of the arc given in degrees, measured counter-clockwise from the horizontal line.
  [in] | sweep | The central angle of the arc given in degrees, measured counter-clockwise from `startAngle`.
  [in] | pie | Specifies whether to draw radii from the arc's center to both of its end-point - drawn if `true`.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  Setting `sweep` value greater than 360 degrees, is equivalent to calling tvg_shape_append_circle(paint, cx, cy, radius, radius).

## ◆ tvg_shape_append_circle()

TVG_EXPORT Tvg_Result tvg_shape_append_circle | ( | Tvg_Paint * | paint,
|  | float | cx,
|  | float | cy,
|  | float | rx,
|  | float | ry
| ) |  |

Appends an ellipse to the path.

The position of the ellipse is specified by the coordinates of its center - `cx` and `cy` arguments.

The ellipse is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (`cx`, `cy` - `ry`).

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | cx | The horizontal coordinate of the center of the ellipse.
  [in] | cy | The vertical coordinate of the center of the ellipse.
  [in] | rx | The x-axis radius of the ellipse.
  [in] | ry | The y-axis radius of the ellipse.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

## ◆ tvg_shape_append_path()

TVG_EXPORT Tvg_Result tvg_shape_append_path | ( | Tvg_Paint * | paint,
|  | const Tvg_Path_Command * | cmds,
|  | uint32_t | cmdCnt,
|  | const Tvg_Point * | pts,
|  | uint32_t | ptsCnt
| ) |  |

Appends a given sub-path to the path.

The current point value is set to the last point from the sub-path. For each command from the `cmds` array, an appropriate number of points in `pts` array should be specified. If the number of points in the `pts` array is different than the number required by the `cmds` array, the shape with this sub-path will not be displayed on the screen.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | cmds | The array of the commands in the sub-path.
  [in] | cmdCnt | The length of the `cmds` array.
  [in] | pts | The array of the two-dimensional points.
  [in] | ptsCnt | The length of the `pts` array.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` passed as the argument or `cmdCnt` or `ptsCnt` equal to zero.

## ◆ tvg_shape_append_rect()

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

The rectangle with rounded corners can be achieved by setting non-zero values to `rx` and `ry` arguments. The `rx` and `ry` values specify the radii of the ellipse defining the rounding of the corners.

The position of the rectangle is specified by the coordinates of its upper left corner - `x` and `y` arguments.

The rectangle is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (`x` + `rx`, `y`) - in case `rx` is greater than `w/2` the current point is set to (`x` + `w/2`, `y`)

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | x | The horizontal coordinate of the upper left corner of the rectangle.
  [in] | y | The vertical coordinate of the upper left corner of the rectangle.
  [in] | w | The width of the rectangle.
  [in] | h | The height of the rectangle.
  [in] | rx | The x-axis radius of the ellipse defining the rounded corners of the rectangle.
  [in] | ry | The y-axis radius of the ellipse defining the rounded corners of the rectangle.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

&

Note
  For `rx` and `ry` greater than or equal to the half of `w` and the half of `h`, respectively, the shape become an ellipse.

## ◆ tvg_shape_close()

TVG_EXPORT Tvg_Result tvg_shape_close | ( | Tvg_Paint * | paint | ) |

Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path.

The value of the current point is set to the initial point of the closed sub-path.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  In case the sub-path does not contain any points, this function has no effect.

## ◆ tvg_shape_cubic_to()

TVG_EXPORT Tvg_Result tvg_shape_cubic_to | ( | Tvg_Paint * | paint,
|  | float | cx1,
|  | float | cy1,
|  | float | cx2,
|  | float | cy2,
|  | float | x,
|  | float | y
| ) |  |

Adds new points to the sub-path, which results in drawing a cubic Bezier curve.

The Bezier curve starts at the current point and ends at the given end-point (`x`, `y`). Two control points (`cx1`, `cy1`) and (`cx2`, `cy2`) are used to determine the shape of the curve. The value of the current point is set to the given end-point.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | cx1 | The horizontal coordinate of the 1st control point.
  [in] | cy1 | The vertical coordinate of the 1st control point.
  [in] | cx2 | The horizontal coordinate of the 2nd control point.
  [in] | cy2 | The vertical coordinate of the 2nd control point.
  [in] | x | The horizontal coordinate of the endpoint of the curve.
  [in] | y | The vertical coordinate of the endpoint of the curve.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  In case this is the first command in the path, no data from the path are rendered.

## ◆ tvg_shape_get_fill_color()

TVG_EXPORT Tvg_Result tvg_shape_get_fill_color | ( | const Tvg_Paint * | paint,
|  | uint8_t * | r,
|  | uint8_t * | g,
|  | uint8_t * | b,
|  | uint8_t * | a
| ) |  |

Gets the shape's solid color.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | r | The red color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | g | The green color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | b | The blue color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | a | The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

## ◆ tvg_shape_get_fill_rule()

TVG_EXPORT Tvg_Result tvg_shape_get_fill_rule | ( | const Tvg_Paint * | paint,
|  | Tvg_Fill_Rule * | rule
| ) |  |

Gets the shape's fill rule.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | rule | shape's fill rule

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_gradient()

TVG_EXPORT Tvg_Result tvg_shape_get_gradient | ( | const Tvg_Paint * | paint,
|  | Tvg_Gradient ** | grad
| ) |  |

Gets the gradient fill of the shape.

The function does not allocate any data.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | grad | The gradient fill.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_path_commands()

TVG_EXPORT Tvg_Result tvg_shape_get_path_commands | ( | const Tvg_Paint * | paint,
|  | const Tvg_Path_Command ** | cmds,
|  | uint32_t * | cnt
| ) |  |

Gets the commands data of the path.

The function does not allocate any data. There is no need to free the `cmds` array.

Tvg_Shape *shape = tvg_shape_new();
Tvg_Path_Command *cmds = NULL;
uint32_t len = 0;
tvg_shape_append_circle(shape, 10, 10, 50, 50);
tvg_shape_get_path_commands(shape, (const Tvg_Path_Command**)&cmds, &len);
//TVG approximates a circle by four Bezier curves. In the example above the cmds array stores the commands of the path data.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | cmds | The pointer to the array of the commands from the path.
  [out] | cnt | The length of the `cmds` array.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` passed as the argument.

## ◆ tvg_shape_get_path_coords()

TVG_EXPORT Tvg_Result tvg_shape_get_path_coords | ( | const Tvg_Paint * | paint,
|  | const Tvg_Point ** | pts,
|  | uint32_t * | cnt
| ) |  |

Gets the points values of the path.

The function does not allocate any data, it operates on internal memory. There is no need to free the `pts` array.

Tvg_Shape *shape = tvg_shape_new();
Tvg_Point *coords = NULL;
uint32_t len = 0;
tvg_shape_append_circle(shape, 10, 10, 50, 50);
tvg_shape_get_path_coords(shape, (const Tvg_Point**)&coords, &len);
//TVG approximates a circle by four Bezier curves. In the example above the coords array stores their coordinates.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | pts | The pointer to the array of the two-dimensional points from the path.
  [out] | cnt | The length of the `pts` array.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` passed as the argument.

## ◆ tvg_shape_get_stroke_cap()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_cap | ( | const Tvg_Paint * | paint,
|  | Tvg_Stroke_Cap * | cap
| ) |  |

Gets the stroke cap style used for stroking the path.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | cap | The cap style value.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_stroke_color()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_color | ( | const Tvg_Paint * | paint,
|  | uint8_t * | r,
|  | uint8_t * | g,
|  | uint8_t * | b,
|  | uint8_t * | a
| ) |  |

Gets the shape's stroke color.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | r | The red color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | g | The green color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | b | The blue color channel value in the range [0 ~ 255]. The default value is 0.
  [out] | a | The alpha channel 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.
  TVG_RESULT_INSUFFICIENT_CONDITION | No stroke was set.

## ◆ tvg_shape_get_stroke_dash()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_dash | ( | const Tvg_Paint * | paint,
|  | const float ** | dashPattern,
|  | uint32_t * | cnt
| ) |  |

Gets the dash pattern of the stroke.

The function does not allocate any memory.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | dashPattern | The array of consecutive pair values of the dash length and the gap length.
  [out] | cnt | The size of the `dashPattern` array.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_stroke_gradient()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient | ( | const Tvg_Paint * | paint,
|  | Tvg_Gradient ** | grad
| ) |  |

Gets the gradient fill of the shape's stroke.

The function does not allocate any memory.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | grad | The gradient fill.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_stroke_join()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_join | ( | const Tvg_Paint * | paint,
|  | Tvg_Stroke_Join * | join
| ) |  |

The function gets the stroke join method.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | join | The join style value.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_get_stroke_width()

TVG_EXPORT Tvg_Result tvg_shape_get_stroke_width | ( | const Tvg_Paint * | paint,
|  | float * | width
| ) |  |

Gets the shape's stroke width.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [out] | width | The stroke width.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument.

## ◆ tvg_shape_line_to()

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

Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point.

The value of the current point is set to the given end-point.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | x | The horizontal coordinate of the end-point of the line.
  [in] | y | The vertical coordinate of the end-point of the line.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  In case this is the first command in the path, it corresponds to the tvg_shape_move_to() call.

## ◆ tvg_shape_move_to()

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

Sets the initial point of the sub-path.

The value of the current point is set to the given point.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | x | The horizontal coordinate of the initial point of the sub-path.
  [in] | y | The vertical coordinate of the initial point of the sub-path.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

## ◆ tvg_shape_new()

TVG_EXPORT Tvg_Paint* tvg_shape_new | ( |  | ) |

Creates a new shape object.

Returns
  A new shape object.

## ◆ tvg_shape_reset()

TVG_EXPORT Tvg_Result tvg_shape_reset | ( | Tvg_Paint * | paint | ) |

Resets the shape path properties.

The color, the fill and the stroke properties are retained.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  The memory, where the path data is stored, is not deallocated at this stage for caching effect.

## ◆ tvg_shape_set_fill_color()

TVG_EXPORT Tvg_Result tvg_shape_set_fill_color | ( | Tvg_Paint * | paint,
|  | uint8_t | r,
|  | uint8_t | g,
|  | uint8_t | b,
|  | uint8_t | a
| ) |  |

Sets the shape's solid color.

The parts of the shape defined as inner are colored.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | r | The red color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | g | The green color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | b | The blue color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | a | The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

See also
  tvg_shape_set_fill_rule()

## ◆ tvg_shape_set_fill_rule()

TVG_EXPORT Tvg_Result tvg_shape_set_fill_rule | ( | Tvg_Paint * | paint,
|  | Tvg_Fill_Rule | rule
| ) |  |

Sets the shape's fill rule.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | rule | The fill rule value. The default value is `TVG_FILL_RULE_WINDING`.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.

## ◆ tvg_shape_set_linear_gradient()

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

The parts of the shape defined as inner are filled.

Tvg_Gradient* grad = tvg_linear_gradient_new();
tvg_linear_gradient_set(grad, 700, 700, 800, 800);
Tvg_Color_Stop color_stops[4] =
{
{0.0 , 0, 0, 0, 255},
{0.25, 255, 0, 0, 255},
{0.5 , 0, 255, 0, 255},
{1.0 , 0, 0, 255, 255}
};
tvg_gradient_set_color_stops(grad, color_stops, 4);
tvg_shape_set_linear_gradient(shape, grad);

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | grad | The linear gradient fill.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_MEMORY_CORRUPTION | An invalid Tvg_Gradient pointer.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

See also
  tvg_shape_set_fill_rule()

## ◆ tvg_shape_set_radial_gradient()

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

The parts of the shape defined as inner are filled.

Tvg_Gradient* grad = tvg_radial_gradient_new();
tvg_radial_gradient_set(grad, 550, 550, 50);
Tvg_Color_Stop color_stops[4] =
{
{0.0 , 0, 0, 0, 255},
{0.25, 255, 0, 0, 255},
{0.5 , 0, 255, 0, 255},
{1.0 , 0, 0, 255, 255}
};
tvg_gradient_set_color_stops(grad, color_stops, 4);
tvg_shape_set_radial_gradient(shape, grad);

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | grad | The radial gradient fill.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.
  TVG_RESULT_MEMORY_CORRUPTION | An invalid Tvg_Gradient pointer.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

See also
  tvg_shape_set_fill_rule()

## ◆ tvg_shape_set_stroke_cap()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_cap | ( | Tvg_Paint * | paint,
|  | Tvg_Stroke_Cap | cap
| ) |  |

Sets the cap style used for stroking the path.

The cap style specifies the shape to be used at the end of the open stroked sub-paths.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | cap | The cap style value. The default value is `TVG_STROKE_CAP_SQUARE`.

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 a memory allocation.

## ◆ tvg_shape_set_stroke_color()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_color | ( | Tvg_Paint * | paint,
|  | uint8_t | r,
|  | uint8_t | g,
|  | uint8_t | b,
|  | uint8_t | a
| ) |  |

Sets the shape's stroke color.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | r | The red color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | g | The green color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | b | The blue color channel value in the range [0 ~ 255]. The default value is 0.
  [in] | a | The alpha channel 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.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with a memory allocation.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

## ◆ tvg_shape_set_stroke_dash()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_dash | ( | Tvg_Paint * | paint,
|  | const float * | dashPattern,
|  | uint32_t | cnt
| ) |  |

Sets the shape's stroke dash pattern.

//dash pattern examples
float dashPattern[2] = {20, 10}; // -- -- --
float dashPattern[2] = {40, 20}; // ---- ---- ----
float dashPattern[4] = {10, 20, 30, 40} // - --- - ---

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | dashPattern | The array of consecutive pair values of the dash length and the gap length.
  [in] | cnt | The size of the `dashPattern` array.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid pointer passed as an argument and `cnt` > 0, the given length of the array is less than two or any of the `dashPattern` values is zero or less.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with a memory allocation.

Note
  To reset the stroke dash pattern, pass `nullptr` to `dashPattern` and zero to `cnt`.

## ◆ tvg_shape_set_stroke_join()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_join | ( | Tvg_Paint * | paint,
|  | Tvg_Stroke_Join | join
| ) |  |

Sets the join style for stroked path segments.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | join | The join style value. The default value is `TVG_STROKE_JOIN_BEVEL`.

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 a memory allocation.

## ◆ tvg_shape_set_stroke_linear_gradient()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient | ( | Tvg_Paint * | paint,
|  | Tvg_Gradient * | grad
| ) |  |

Sets the linear gradient fill of the stroke for all of the figures from the path.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | grad | The linear gradient fill.

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 a memory allocation.
  TVG_RESULT_MEMORY_CORRUPTION | An invalid Tvg_Gradient pointer.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

## ◆ tvg_shape_set_stroke_radial_gradient()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient | ( | Tvg_Paint * | paint,
|  | Tvg_Gradient * | grad
| ) |  |

Sets the radial gradient fill of the stroke for all of the figures from the path.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | grad | The radial gradient fill.

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 a memory allocation.
  TVG_RESULT_MEMORY_CORRUPTION | An invalid Tvg_Gradient pointer.

Note
  Either a solid color or a gradient fill is applied, depending on what was set as last.

## ◆ tvg_shape_set_stroke_width()

TVG_EXPORT Tvg_Result tvg_shape_set_stroke_width | ( | Tvg_Paint * | paint,
|  | float | width
| ) |  |

Sets the stroke width for all of the figures from the `paint`.

Parameters

  [in] | paint | A Tvg_Paint pointer to the shape object.
  [in] | width | The width of the stroke. The default value is 0.

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 a memory allocation.

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.
tvg_shape_get_path_coords
TVG_EXPORT Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint *paint, const Tvg_Point **pts, uint32_t *cnt)
Gets the points values of the path.
tvg_radial_gradient_new
TVG_EXPORT Tvg_Gradient * tvg_radial_gradient_new()
Creates a new radial gradient object.
tvg_shape_get_path_commands
TVG_EXPORT Tvg_Result tvg_shape_get_path_commands(const Tvg_Paint *paint, const Tvg_Path_Command **cmds, uint32_t *cnt)
Gets the commands data of the path.
Tvg_Point
A data structure representing a point in two-dimensional space.
Definition: thorvg_capi.h:199
tvg_shape_new
TVG_EXPORT Tvg_Paint * tvg_shape_new()
Creates a new shape object.
tvg_shape_set_linear_gradient
TVG_EXPORT 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_append_circle
TVG_EXPORT Tvg_Result tvg_shape_append_circle(Tvg_Paint *paint, float cx, float cy, float rx, float ry)
Appends an ellipse to the path.
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.
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.
Tvg_Gradient
struct _Tvg_Gradient Tvg_Gradient
A structure representing a gradient fill of a Tvg_Paint object.
Definition: thorvg_capi.h:69
tvg_linear_gradient_new
TVG_EXPORT Tvg_Gradient * tvg_linear_gradient_new()
Creates a new linear gradient object.
Tvg_Color_Stop
A data structure storing the information about the color and its relative position inside the gradien...
Definition: thorvg_capi.h:184
Tvg_Path_Command
Tvg_Path_Command
Enumeration specifying the values of the path commands accepted by TVG.
Definition: thorvg_capi.h:127
tvg_shape_set_radial_gradient
TVG_EXPORT 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.