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

#include <thorvg.h>

Inheritance diagram for Shape:

Collaboration diagram for Shape:

Public Member Functions
Result	reset () noexcept
	Resets the shape path.

Result	moveTo (float x, float y) noexcept
	Sets the initial point of the sub-path.

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.

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

Result	close () noexcept
	Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path.

Result	appendRect (float x, float y, float w, float h, float rx=0, float ry=0, bool cw=true) noexcept
	Appends a rectangle to the path.

Result	appendCircle (float cx, float cy, float rx, float ry, bool cw=true) noexcept
	Appends an ellipse to the path.

Result	appendPath (const PathCommand cmds, uint32_t cmdCnt, const Point pts, uint32_t ptsCnt) noexcept
	Appends a given sub-path to the path.

Result	strokeWidth (float width) noexcept
	Sets the stroke width for the path.

Result	strokeFill (uint8_t r, uint8_t g, uint8_t b, uint8_t a=255) noexcept
	Sets the stroke color for the path.

Result	strokeFill (Fill *f) noexcept
	Sets the gradient fill of the stroke for all of the figures from the path.

Result	strokeDash (const float *dashPattern, uint32_t cnt, float offset=0.0f) noexcept
	Sets the dash pattern of the stroke.

Result	strokeCap (StrokeCap cap) noexcept
	Sets the cap style of the stroke in the open sub-paths.

Result	strokeJoin (StrokeJoin join) noexcept
	Sets the join style for stroked path segments.

Result	strokeMiterlimit (float miterlimit) noexcept
	Sets the stroke miterlimit.

Result	trimpath (float begin, float end, bool simultaneous=true) noexcept
	Sets the trim of the shape along the defined path segment, allowing control over which part of the shape is visible.

Result	fill (uint8_t r, uint8_t g, uint8_t b, uint8_t a=255) noexcept
	Sets the solid color for all of the figures from the path.

Result	fill (Fill *f) noexcept
	Sets the gradient fill for all of the figures from the path.

Result	fillRule (FillRule r) noexcept
	Sets the fill rule for the shape.

Result	order (bool strokeFirst) noexcept
	Sets the rendering order of the stroke and the fill.

Result	path (const PathCommand *cmds, uint32_t cmdsCnt, const Point *pts, uint32_t ptsCnt) const noexcept
	Retrieves the current path data of the shape.

const Fill *	fill () const noexcept
	Gets the pointer to the gradient fill of the shape.

Result	fill (uint8_t r, uint8_t g, uint8_t b, uint8_t a=nullptr) const noexcept
	Gets the solid color of the shape.

FillRule	fillRule () const noexcept
	Retrieves the current fill rule used by the shape.

float	strokeWidth () const noexcept
	Gets the stroke width.

Result	strokeFill (uint8_t r, uint8_t g, uint8_t b, uint8_t a=nullptr) const noexcept
	Gets the color of the shape's stroke.

const Fill *	strokeFill () const noexcept
	Gets the pointer to the gradient fill of the stroke.

uint32_t	strokeDash (const float *dashPattern, float offset=nullptr) const noexcept
	Gets the dash pattern of the stroke.

StrokeCap	strokeCap () const noexcept
	Gets the cap style used for stroking the path.

StrokeJoin	strokeJoin () const noexcept
	Gets the join style value used for stroking the path.

float	strokeMiterlimit () const noexcept
	Gets the stroke miterlimit.

Type	type () const noexcept override
	Returns the ID value of this class.

Public Member Functions inherited from Paint
const Paint *	parent () const noexcept
	Retrieves the parent paint object.

Result	visible (bool on) noexcept
	Sets the visibility of the Paint object.

Result	rotate (float degree) noexcept
	Sets the angle by which the object is rotated.

Result	scale (float factor) noexcept
	Sets the scale value of the object.

Result	translate (float x, float y) noexcept
	Sets the values by which the object is moved in a two-dimensional space.

Result	transform (const Matrix &m) noexcept
	Sets the matrix of the affine transformation for the object.

Matrix &	transform () noexcept
	Gets the matrix of the affine transformation of the object.

Result	opacity (uint8_t o) noexcept
	Sets the opacity of the object.

Result	mask (Paint *target, MaskMethod method) noexcept
	Sets the masking target object and the masking method.

Result	clip (Shape *clipper) noexcept
	Clip the drawing region of the paint object.

Result	blend (BlendMethod method) noexcept
	Sets the blending method for the paint object.

Result	bounds (Point *pt4) noexcept
	Retrieves the object-oriented bounding box (OBB) of the paint object in canvas space.

Result	bounds (float x, float y, float w, float h) noexcept
	Retrieves the axis-aligned bounding box (AABB) of the paint object in canvas space.

bool	intersects (int32_t x, int32_t y, int32_t w=1, int32_t h=1) noexcept
	Checks whether a given region intersects the filled area of the paint.

Paint *	duplicate () const noexcept
	Duplicates the object.

uint8_t	opacity () const noexcept
	Gets the opacity value of the object.

MaskMethod	mask (const Paint **target) const noexcept
	Gets the masking target object and the masking method.

Shape *	clip () const noexcept
	Get the clipper shape of the paint object.

bool	visible () const noexcept
	Gets the current visibility status of the Paint object.

uint16_t	ref () noexcept
	Increment the reference count for the Paint instance.

uint16_t	unref (bool free=true) noexcept
	Decrement the reference count for the Paint instance.

uint16_t	refCnt () const noexcept
	Retrieve the current reference count of the Paint instance.

Static Public Member Functions
static Shape *	gen () noexcept
	Creates a new Shape object.

Static Public Member Functions inherited from Paint
static void	rel (Paint *paint) noexcept
	Safely releases a Paint object.

Additional Inherited Members
Public Attributes inherited from Paint
uint32_t	id = 0
	Unique ID of this instance.

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.

Warning: This class is not designed for inheritance.

Member Function Documentation

◆ appendCircle()

Result appendCircle	(	float	cx,
		float	cy,
		float	rx,
		float	ry,
		bool	cw = `true`
	)

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.
[in]	cw	Specifies the path direction: `true` for clockwise, `false` for counterclockwise.

◆ 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. 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]	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.

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 = `0`,
		float	ry = `0`,
		bool	cw = `true`
	)

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.
[in]	cw	Specifies the path direction: `true` for clockwise, `false` for counterclockwise.

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.

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.

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

◆ fill() [1/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.

◆ fill() [2/4]

Result fill ( 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.

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

◆ fill() [3/4]

Result fill	(	uint8_t *	r,
		uint8_t *	g,
		uint8_t *	b,
		uint8_t *	a = `nullptr`
	)		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.

◆ fill() [4/4]

Result fill	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b,
		uint8_t	a = `255`
	)

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.

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

◆ fillRule() [1/2]

FillRule fillRule ( ) const

noexcept

Retrieves the current fill rule used by the shape.

This function returns the fill rule, which determines how the interior regions of the shape are calculated when it overlaps itself.

See also: Shape::fillRule(FillRule r)

Returns: The current FillRule value of the shape.

◆ fillRule() [2/2]

Result fillRule ( FillRule r )

noexcept

Sets the fill rule for the shape.

Specifies how the interior of the shape is determined when its path intersects itself. The default fill rule is FillRule::NonZero.

Parameters

[in] r The fill rule to apply to the shape.

◆ gen()

static Shape * gen ( )

staticnoexcept

Creates a new Shape object.

This function allocates and returns a new Shape instance. To properly destroy the Shape object, use Paint::rel().

Returns: A pointer to the newly created Shape object.

See also: Paint::rel()

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

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.

◆ order()

Result order ( bool strokeFirst )

noexcept

Sets the rendering order of the stroke and the fill.

Parameters

[in] strokeFirst If true the stroke is rendered before the fill, otherwise the stroke is rendered as the second one (the default option).

Since: 0.10

◆ path()

Result path	(	const PathCommand **	cmds,
		uint32_t *	cmdsCnt,
		const Point **	pts,
		uint32_t *	ptsCnt
	)		const

noexcept

Retrieves the current path data of the shape.

This function provides access to the shape's path data, including the commands and points that define the path.

Parameters

[out]	cmds	Pointer to the array of commands representing the path. Can be `nullptr` if this information is not needed.
[out]	cmdsCnt	Pointer to the variable that receives the number of commands in the `cmds` array. Can be `nullptr` if this information is not needed.
[out]	pts	Pointer to the array of two-dimensional points that define the path. Can be `nullptr` if this information is not needed.
[out]	ptsCnt	Pointer to the variable that receives the number of points in the `pts` array. Can be `nullptr` if this information is not needed.

◆ reset()

Result reset ( )

noexcept

Resets the shape path.

The transformation matrix, color, fill, and stroke properties are retained.

Note: The memory where the path data is stored is not deallocated at this stage to allow for caching.

◆ strokeCap() [1/2]

StrokeCap strokeCap ( ) const

noexcept

Gets the cap style used for stroking the path.

Returns: The cap style value of the stroke.

◆ strokeCap() [2/2]

Result strokeCap ( 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.

◆ strokeDash() [1/2]

uint32_t strokeDash	(	const float **	dashPattern,
		float *	offset = `nullptr`
	)		const

noexcept

Gets the dash pattern of the stroke.

Parameters

[out]	dashPattern	The pointer to the memory, where the dash pattern array is stored.
[out]	offset	The shift of the starting point within the repeating dash pattern.

Returns: The length of the dashPattern array.

Since: 1.0

◆ strokeDash() [2/2]

Result strokeDash	(	const float *	dashPattern,
		uint32_t	cnt,
		float	offset = `0.0f`
	)

noexcept

Sets the dash pattern of the stroke.

Parameters

[in]	dashPattern	An array of alternating dash and gap lengths.
[in]	cnt	The length of the `dashPattern` array.
[in]	offset	The shift of the starting point within the repeating dash pattern, from which the pattern begins to be applied.

Return values

Result::InvalidArguments In case dashPattern is nullptr and cnt > 0 or dashPattern is not nullptr and cnt is zero.

Note: To reset the stroke dash pattern, pass nullptr to dashPattern and zero to cnt.; Values of dashPattern less than zero are treated as zero.; If all values in the dashPattern are equal to or less than 0, the dash is ignored.; If the dashPattern contains an odd number of elements, the sequence is repeated in the same order to form an even-length pattern, preserving the alternation of dashes and gaps.

Since: 1.0

◆ strokeFill() [1/4]

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.

◆ strokeFill() [2/4]

Result strokeFill ( 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::InvalidArgument In case a nullptr is passed as the argument.

Note: If the stroke width is 0 (default), the stroke will not be visible regardless of the color.; Either a solid color or a gradient fill is applied, depending on what was set as last.

See also: strokeFill(uint8_t r, uint8_t g, uint8_t b, uint8_t a)

◆ strokeFill() [3/4]

Result strokeFill	(	uint8_t *	r,
		uint8_t *	g,
		uint8_t *	b,
		uint8_t *	a = `nullptr`
	)		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.

◆ strokeFill() [4/4]

Result strokeFill	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b,
		uint8_t	a = `255`
	)

noexcept

Sets the stroke color for the path.

This function defines the RGBA color of the stroke applied to all figures in the path object. The stroke color is used when rendering the outline of the path geometry.

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.

Note: If the stroke width is 0 (default), the stroke will not be visible regardless of the color.; Either a solid color or a gradient fill is applied, depending on what was set as last.

See also: strokeWidth(); strokeFill(Fill* f)

◆ strokeJoin() [1/2]

StrokeJoin strokeJoin ( ) const

noexcept

Gets the join style value used for stroking the path.

Returns: The join style value of the stroke.

◆ strokeJoin() [2/2]

Result strokeJoin ( 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.

◆ strokeMiterlimit() [1/2]

float strokeMiterlimit ( ) const

noexcept

Gets the stroke miterlimit.

Returns: The stroke miterlimit value when succeed, 4 if no stroke was set.

Since: 0.11

◆ strokeMiterlimit() [2/2]

Result strokeMiterlimit ( float miterlimit )

noexcept

Sets the stroke miterlimit.

Parameters

[in] miterlimit The miterlimit imposes a limit on the extent of the stroke join, when the StrokeJoin::Miter join style is set. The default value is 4.

Return values

Result::InvalidArgument for miterlimit values less than zero.

Since: 0.11

◆ strokeWidth() [1/2]

float strokeWidth ( ) const

noexcept

Gets the stroke width.

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

◆ strokeWidth() [2/2]

Result strokeWidth ( float width )

noexcept

Sets the stroke width for the path.

This function defines the thickness of the stroke applied to all figures in the path object. A stroke is the outline drawn along the edges of the path's geometry.

Parameters

[in] width The width of the stroke in pixels. Must be positive value. (The default is 0)

Note: A value of width 0 disables the stroke.

See also: strokeFill()

◆ trimpath()

Result trimpath	(	float	begin,
		float	end,
		bool	simultaneous = `true`
	)

noexcept

Sets the trim of the shape along the defined path segment, allowing control over which part of the shape is visible.

If the values of the arguments begin and end exceed the 0-1 range, they are wrapped around in a manner similar to angle wrapping, effectively treating the range as circular.

Parameters

[in]	begin	Specifies the start of the segment to display along the path.
[in]	end	Specifies the end of the segment to display along the path.
[in]	simultaneous	Determines how to trim multiple paths within a single shape. If set to `true` (default), trimming is applied simultaneously to all paths; Otherwise, all paths are treated as a single entity with a combined length equal to the sum of their individual lengths and are trimmed as such.

Since: 1.0

◆ type()

Type type ( ) const

overridevirtualnoexcept

Returns the ID value of this class.

This method can be used to check the current concrete instance type.

Returns: The class type ID of the Shape instance.

Since: 1.0

Implements Paint.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ appendCircle()

◆ appendPath()

◆ appendRect()

◆ close()

◆ cubicTo()

◆ fill() [1/4]

◆ fill() [2/4]

◆ fill() [3/4]

◆ fill() [4/4]

◆ fillRule() [1/2]

◆ fillRule() [2/2]

◆ gen()

◆ lineTo()

◆ moveTo()

◆ order()

◆ path()

◆ reset()

◆ strokeCap() [1/2]

◆ strokeCap() [2/2]

◆ strokeDash() [1/2]

◆ strokeDash() [2/2]

◆ strokeFill() [1/4]

◆ strokeFill() [2/4]

◆ strokeFill() [3/4]

◆ strokeFill() [4/4]

◆ strokeJoin() [1/2]

◆ strokeJoin() [2/2]

◆ strokeMiterlimit() [1/2]

◆ strokeMiterlimit() [2/2]

◆ strokeWidth() [1/2]

◆ strokeWidth() [2/2]

◆ trimpath()

◆ type()