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

Inheritance diagram for Shape:

Collaboration diagram for Shape:

Public Member Functions
Result	reset () noexcept
	Resets 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=0, float ry=0) 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...

TVG_DEPRECATED 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=255) 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	strokeMiterlimit (float miterlimit) noexcept
	Sets the stroke miterlimit. More...

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

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

Result	order (bool strokeFirst) noexcept
	Sets the rendering order of the stroke and the fill. 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=nullptr) 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=nullptr) 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...

float	strokeMiterlimit () const noexcept
	Gets the stroke miterlimit. More...

Type	type () const noexcept override
	Returns the ID value of this class. 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...

Matrix	transform () noexcept
	Gets the matrix of the affine transformation of 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) noexcept
	Sets the composition target object and the composition method. More...

Result	clip (std::unique_ptr< Paint > clipper) noexcept
	Clip the drawing region of the paint object. More...

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

TVG_DEPRECATED Result	bounds (float x, float y, float w, float h) const noexcept

Result	bounds (float x, float y, float w, float h, bool transformed) const noexcept
	Gets the axis-aligned bounding box of the paint object. More...

Paint *	duplicate () const noexcept
	Duplicates the object. More...

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

CompositeMethod	composite (const Paint **target) const noexcept
	Gets the composition target object and the composition method. More...

TVG_DEPRECATED uint32_t	identifier () const noexcept

Static Public Member Functions
static std::unique_ptr< Shape >	gen () noexcept
	Creates a new Shape object. More...

static TVG_DEPRECATED uint32_t	identifier () noexcept

Additional Inherited Members
Public Attributes inherited from Paint
uint32_t	id = 0
	Unique ID of this instance. 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()

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

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.

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

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.

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 ( FillRule r )

noexcept

Sets the fill rule for the Shape object.

Parameters

[in] r The fill rule value. The default value is FillRule::Winding.

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

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

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

◆ fillColor()

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

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

◆ identifier()

static TVG_DEPRECATED uint32_t identifier ( )

staticnoexcept

See also: Shape::type()

◆ 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

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

◆ stroke() [1/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::InvalidArguments In case dashPattern is nullptr and cnt > 0, cnt is zero, any of the dash pattern values is zero or less.

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

Warning: cnt must be greater than 1 if the dash pattern is valid.

◆ stroke() [2/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.

◆ 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::MemoryCorruption In case a nullptr is passed as the argument.

◆ stroke() [4/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.

◆ stroke() [5/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.

◆ stroke() [6/6]

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

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.

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

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

◆ 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

◆ strokeTrim()

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

noexcept

Sets the trim of the stroke along the defined path segment, allowing control over which part of the stroke 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.

Note: Experimental API

◆ strokeWidth()

float strokeWidth ( ) const

noexcept

Gets the stroke width.

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

◆ 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: Experimental API

Implements Paint.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ appendArc()

◆ appendCircle()

◆ appendPath()

◆ appendRect()

◆ close()

◆ cubicTo()

◆ fill() [1/4]

◆ fill() [2/4]

◆ fill() [3/4]

◆ fill() [4/4]

◆ fillColor()

◆ fillRule()

◆ gen()

◆ identifier()

◆ lineTo()

◆ moveTo()

◆ order()

◆ pathCommands()

◆ pathCoords()

◆ reset()

◆ stroke() [1/6]

◆ stroke() [2/6]

◆ stroke() [3/6]

◆ stroke() [4/6]

◆ stroke() [5/6]

◆ stroke() [6/6]

◆ strokeCap()

◆ strokeColor()

◆ strokeDash()

◆ strokeFill()

◆ strokeJoin()

◆ strokeMiterlimit() [1/2]

◆ strokeMiterlimit() [2/2]

◆ strokeTrim()

◆ strokeWidth()

◆ type()