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

Inheritance diagram for Shape:

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

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

CompositeMethod	composite (const Paint **target) const noexcept
	Gets the composition target object and the composition method. 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 that either `dashPattern` is `nullptr` or `cnt` is zero.

Note: If any of the dash pattern values is zero, this function has no effect.; 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() [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.

Public Member Functions

Static Public Member Functions

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

◆ lineTo()

◆ moveTo()

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

◆ strokeWidth()