Shapefinal
ThorVG

A class representing two-dimensional figures and their properties. More...

Inheritance diagram for Shape:
[legend]

## Public Member Functions

Result | reset () noexcept
| Resets the properties of the shape path. More...
Result | moveTo (float x, float y) noexcept
| Sets the initial point of the sub-path. More...
Result | lineTo (float x, float y) noexcept
| Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point. More...
Result | cubicTo (float cx1, float cy1, float cx2, float cy2, float x, float y) noexcept
| Adds new points to the sub-path, which results in drawing a cubic Bezier curve starting at the current point and ending at the given end-point (`x`, `y`) using the control points (`cx1`, `cy1`) and (`cx2`, `cy2`). More...
Result | close () noexcept
| Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path. More...
Result | appendRect (float x, float y, float w, float h, float rx, float ry) noexcept
| Appends a rectangle to the path. More...
Result | appendCircle (float cx, float cy, float rx, float ry) noexcept
| Appends an ellipse to the path. More...
Result | appendArc (float cx, float cy, float radius, float startAngle, float sweep, bool pie) noexcept
| Appends a circular arc to the path. More...
Result | appendPath (const PathCommand *cmds, uint32_t cmdCnt, const Point *pts, uint32_t ptsCnt) noexcept
| Appends a given sub-path to the path. More...
Result | stroke (float width) noexcept
| Sets the stroke width for all of the figures from the path. More...
Result | stroke (uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept
| Sets the color of the stroke for all of the figures from the path. More...
Result | stroke (std::unique_ptr< Fill > f) noexcept
| Sets the gradient fill of the stroke for all of the figures from the path. More...
Result | stroke (const float *dashPattern, uint32_t cnt) noexcept
| Sets the dash pattern of the stroke. More...
Result | stroke (StrokeCap cap) noexcept
| Sets the cap style of the stroke in the open sub-paths. More...
Result | stroke (StrokeJoin join) noexcept
| Sets the join style for stroked path segments. More...
Result | fill (uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept
| Sets the solid color for all of the figures from the path. More...
Result | fill (std::unique_ptr< Fill > f) noexcept
| Sets the gradient fill for all of the figures from the path. More...
Result | fill (FillRule r) noexcept
| Sets the fill rule for the Shape object. More...
uint32_t | pathCommands (const PathCommand **cmds) const noexcept
| Gets the commands data of the path. More...
uint32_t | pathCoords (const Point **pts) const noexcept
| Gets the points values of the path. More...
const Fill * | fill () const noexcept
| Gets the pointer to the gradient fill of the shape. More...
Result | fillColor (uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a) const noexcept
| Gets the solid color of the shape. More...
FillRule | fillRule () const noexcept
| Gets the fill rule value. More...
float | strokeWidth () const noexcept
| Gets the stroke width. More...
Result | strokeColor (uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a) const noexcept
| Gets the color of the shape's stroke. More...
const Fill * | strokeFill () const noexcept
| Gets the pointer to the gradient fill of the stroke. More...
uint32_t | strokeDash (const float **dashPattern) const noexcept
| Gets the dash pattern of the stroke. More...
StrokeCap | strokeCap () const noexcept
| Gets the cap style used for stroking the path. More...
StrokeJoin | strokeJoin () const noexcept
| Gets the join style value used for stroking the path. More...
Public Member Functions inherited from Paint
Result | rotate (float degree) noexcept
| Sets the angle by which the object is rotated. More...
Result | scale (float factor) noexcept
| Sets the scale value of the object. More...
Result | translate (float x, float y) noexcept
| Sets the values by which the object is moved in a two-dimensional space. More...
Result | transform (const Matrix &m) noexcept
| Sets the matrix of the affine transformation for the object. More...
Result | opacity (uint8_t o) noexcept
| Sets the opacity of the object. More...
Result | composite (std::unique_ptr< Paint > target, CompositeMethod method) const noexcept
| Sets the composition target object and the composition method. More...
Result | bounds (float *x, float *y, float *w, float *h) const noexcept
| Gets the bounding box of the paint object before any transformation. More...
Paint * | duplicate () const noexcept
| Duplicates the object. More...
uint8_t | opacity () const noexcept
| Gets the opacity value of the object. More...

## Static Public Member Functions

static std::unique_ptr< Shape > | gen () noexcept
| Creates a new Shape object. More...

## Detailed Description

A class representing 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 moveTo(), lineTo(), cubicTo(), or complete shape interfaces such as appendRect(), appendCircle(), etc. Path can consists of sub-paths. One sub-path is determined by a close command.

The stroke of 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.

## Member Function Documentation

## appendArc()

Result appendArc | ( | float | cx,
|  | float | cy,
|  | float | radius,
|  | float | startAngle,
|  | float | sweep,
|  | bool | pie
| ) |  |

noexcept

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] | 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
  Result::Success when succeed.

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

## appendCircle()

Result appendCircle | ( | float | cx,
|  | float | cy,
|  | float | rx,
|  | float | ry
| ) |  |

noexcept

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] | 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
  Result::Success when succeed.

## appendPath()

Result appendPath | ( | const PathCommand * | cmds,
|  | uint32_t | cmdCnt,
|  | const Point * | pts,
|  | uint32_t | ptsCnt
| ) |  |

noexcept

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.

Parameters

  [in] | cmds | The array of the commands in the sub-path.
  [in] | cmdCnt | The number of the sub-path's commands.
  [in] | pts | The array of the two-dimensional points.
  [in] | ptsCnt | The number of the points in the `pts` array.

Returns
  Result::Success when succeed, Result::InvalidArguments otherwise.

Note
  The interface is designed for optimal path setting if the caller has a completed path commands already.

## appendRect()

Result appendRect | ( | float | x,
|  | float | y,
|  | float | w,
|  | float | h,
|  | float | rx,
|  | float | ry
| ) |  |

noexcept

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] | 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
  Result::Success when succeed.

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.

## close()

Result close | ( |  | ) |

noexcept

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.

Returns
  Result::Success when succeed.

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

## cubicTo()

Result cubicTo | ( | float | cx1,
|  | float | cy1,
|  | float | cx2,
|  | float | cy2,
|  | float | x,
|  | float | y
| ) |  |

noexcept

Adds new points to the sub-path, which results in drawing a cubic Bezier curve starting at the current point and ending at the given end-point (`x`, `y`) using the control points (`cx1`, `cy1`) and (`cx2`, `cy2`).

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

Parameters

  [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 end-point of the curve.
  [in] | y | The vertical coordinate of the end-point of the curve.

Returns
  Result::Success when succeed.

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

## fill() [1/4]

Result fill | ( | uint8_t | r,
|  | uint8_t | g,
|  | uint8_t | b,
|  | uint8_t | a
| ) |  |

noexcept

Sets the solid color for all of the figures from the path.

The parts of the shape defined as inner are colored.

Parameters

  [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
  Result::Success when succeed.

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

## fill() [2/4]

Result fill | ( | std::unique_ptr< Fill > | f | ) |

noexcept

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

The parts of the shape defined as inner are filled.

Parameters

  [in] | f | The unique pointer to the gradient fill.

Returns
  Result::Success when succeed, Result::MemoryCorruption otherwise.

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

## fill() [3/4]

Result fill | ( | FillRule | r | ) |

noexcept

Sets the fill rule for the Shape object.

Parameters

  [in] | r | The fill rule value.

Returns
  Result::Success when succeed.

## fill() [4/4]

const Fill* fill | ( |  | ) | const

noexcept

Gets the pointer to the gradient fill of the shape.

Returns
  The pointer to the gradient fill of the stroke when succeed, `nullptr` in case no fill was set.

## fillColor()

Result fillColor | ( | uint8_t * | r,
|  | uint8_t * | g,
|  | uint8_t * | b,
|  | uint8_t * | a
| ) |  | const

noexcept

Gets the solid color of the shape.

Parameters

  [out] | r | The red color channel value in the range [0 ~ 255].
  [out] | g | The green color channel value in the range [0 ~ 255].
  [out] | b | The blue color channel value in the range [0 ~ 255].
  [out] | a | The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Returns
  Result::Success when succeed.

## fillRule()

FillRule fillRule | ( |  | ) | const

noexcept

Gets the fill rule value.

Returns
  The fill rule value of the shape.

## gen()

static std::unique_ptr<Shape> gen | ( |  | ) |

staticnoexcept

Creates a new Shape object.

Returns
  A new Shape object.

## lineTo()

Result lineTo | ( | float | x,
|  | float | y
| ) |  |

noexcept

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] | x | The horizontal coordinate of the end-point of the line.
  [in] | y | The vertical coordinate of the end-point of the line.

Returns
  Result::Success when succeed.

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

## moveTo()

Result moveTo | ( | float | x,
|  | float | y
| ) |  |

noexcept

Sets the initial point of the sub-path.

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

Parameters

  [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
  Result::Success when succeed.

## pathCommands()

uint32_t pathCommands | ( | const PathCommand ** | cmds | ) | const

noexcept

Gets the commands data of the path.

Parameters

  [out] | cmds | The pointer to the array of the commands from the path.

Returns
  The length of the `cmds` array when succeed, zero otherwise.

## pathCoords()

uint32_t pathCoords | ( | const Point ** | pts | ) | const

noexcept

Gets the points values of the path.

Parameters

  [out] | pts | The pointer to the array of the two-dimensional points from the path.

Returns
  The length of the `pts` array when succeed, zero otherwise.

## reset()

Result reset | ( |  | ) |

noexcept

Resets the properties of the shape path.

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

Returns
  Result::Success when succeed.

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

## stroke() [1/6]

Result stroke | ( | float | width | ) |

noexcept

Sets the stroke width for all of the figures from the path.

Parameters

  [in] | width | The width of the stroke. The default value is 0.

Returns
  Result::Success when succeed, Result::FailedAllocation otherwise.

## stroke() [2/6]

Result stroke | ( | uint8_t | r,
|  | uint8_t | g,
|  | uint8_t | b,
|  | uint8_t | a
| ) |  |

noexcept

Sets the color of the stroke for all of the figures from the path.

Parameters

  [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
  Result::Success when succeed, Result::FailedAllocation otherwise.

## stroke() [3/6]

Result stroke | ( | std::unique_ptr< Fill > | f | ) |

noexcept

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

Parameters

  [in] | f | The gradient fill.

Return values

  Result::Success | When succeed.
  Result::FailedAllocation | An internal error with a memory allocation for an object to be filled.
  Result::MemoryCorruption | In case a `nullptr` is passed as the argument.

## stroke() [4/6]

Result stroke | ( | const float * | dashPattern,
|  | uint32_t | cnt
| ) |  |

noexcept

Sets the dash pattern of the stroke.

Parameters

  [in] | dashPattern | The array of consecutive pair values of the dash length and the gap length.
  [in] | cnt | The length of the `dashPattern` array.

Return values

  Result::Success | When succeed.
  Result::FailedAllocation | An internal error with a memory allocation for an object to be dashed.
  Result::InvalidArguments | In case a `nullptr` is passed as the `dashPattern`, the given length of the array is less than two or any of the `dashPattern` values is zero or less.

Note
  If any of the dash pattern values is zero, this function has no effect.

## stroke() [5/6]

Result stroke | ( | StrokeCap | cap | ) |

noexcept

Sets the cap style of the stroke in the open sub-paths.

Parameters

  [in] | cap | The cap style value. The default value is `StrokeCap::Square`.

Returns
  Result::Success when succeed, Result::FailedAllocation otherwise.

## stroke() [6/6]

Result stroke | ( | StrokeJoin | join | ) |

noexcept

Sets the join style for stroked path segments.

The join style is used for joining the two line segment while stroking the path.

Parameters

  [in] | join | The join style value. The default value is `StrokeJoin::Bevel`.

Returns
  Result::Success when succeed, Result::FailedAllocation otherwise.

## strokeCap()

StrokeCap strokeCap | ( |  | ) | const

noexcept

Gets the cap style used for stroking the path.

Returns
  The cap style value of the stroke.

## strokeColor()

Result strokeColor | ( | uint8_t * | r,
|  | uint8_t * | g,
|  | uint8_t * | b,
|  | uint8_t * | a
| ) |  | const

noexcept

Gets the color of the shape's stroke.

Parameters

  [out] | r | The red color channel value in the range [0 ~ 255].
  [out] | g | The green color channel value in the range [0 ~ 255].
  [out] | b | The blue color channel value in the range [0 ~ 255].
  [out] | a | The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Returns
  Result::Success when succeed, Result::InsufficientCondition otherwise.

## strokeDash()

uint32_t strokeDash | ( | const float ** | dashPattern | ) | const

noexcept

Gets the dash pattern of the stroke.

Parameters

  [out] | dashPattern | The pointer to the memory, where the dash pattern array is stored.

Returns
  The length of the `dashPattern` array.

## strokeFill()

const Fill* strokeFill | ( |  | ) | const

noexcept

Gets the pointer to the gradient fill of the stroke.

Returns
  The pointer to the gradient fill of the stroke when succeed, `nullptr` otherwise.

## strokeJoin()

StrokeJoin strokeJoin | ( |  | ) | const

noexcept

Gets the join style value used for stroking the path.

Returns
  The join style value of the stroke.

## strokeWidth()

float strokeWidth | ( |  | ) | const

noexcept

Gets the stroke width.

Returns
  The stroke width value when succeed, zero if no stroke was set.